Learning Git

Git is a distributed revision control and software-management package. So that’s a lot of words. Git is basically a piece of software that allows you to manage changes to code, papers, or other documents. We use Git to manage our code, but there are also people that use Git to write papers more efficiently among other things. What Git allows you to do is make a bunch of changes to some code to experiment with it, and then “commit” those changes if it works, or revert back to the previous working version if it didn’t. It’s like going back in time. But the great things is that you don’t have to manually dig through and change everything back to the way it was from your memory. We let Git remember for us because we are programmers and programmers are lazy. A cool thing about Git is that once you commit some changes, you can decide afterwards that they don’t work after all and revert back to before you made those changes too. And it’s uber fast. We have around 120,000 lines of code as of Summer 2012 and Git takes no more than a few seconds to run its commands.

So we’ve covered most of the terms in that first sentence. Software-management package: Git is just a piece of software for managing code and documents; revision control: Git lets you apply and cut out your changes at will; but what about distributed. What does that mean? Git is only one of many version-control systems. The Northern-Bites used to use a very popular system called Subversion or SVN for short. It is similar to Git in a lot of ways, but lacks many of Git’s most powerful features. First off SVN is centralized rather than distributed. This means that the “repository” (everything that SVN is told to keep track of) is centralized somewhere on a server. For users to access the code and make changes, the user has to connect to the server and check out the most recent version then connect again when they are done. With a distributed system, every user has a copy of the full repository and even has the option of keeping copies of what other users are changing. This allows for a much more flexible development environment. In addition to this, Git provides better “branching” capabilities. With one branch, a developer can be working on one part of the code, say Vision, while simultaneously working on Motion in another branch. This is especially useful when development areas overlap and you want to keep your changes for each area separate. Git has fantastic merging algorithms to handle conflicting changes so there’s no need to worry about that.

Key Terms

Repository

A repository is where all of the code is located and kept. This is also the base directory. Our repository is called nbites. A repository can be “local” (on your own machine) or “remote” (on a server like Github).

Commit

A commit is a group of changes (typically with a message) that serve a common function. For example, I might add debug print lines to a file and commit that with a message

adds debug prints

And I may add another commit that adds a new function, and another that adds comments to a file. It is generally a good thing to commit a small number of things often, rather than large number of things infrequently.

Branch

A branch is a collection of commits usually with a common purpose. For example, I might create a branch called betterBall and commit a bunch of little things with the greater purpose of seeing the ball better.

Staged vs Unstaged vs Untracked

Changes that you make in Git can be either untracked, unstaged, or staged. Suppose I have an empty Git repository and I create a new Java file called Hello World.java that has just a main method that does nothing yet. This file is currently untracked because I haven’t told the repository to keep track of it yet. I can do so with a simple command that we will get to in the next section, but for now suppose I tell the repository to track it and I commit the state of the file.

Now I realize that I haven’t actually printed “Hello World” in my program yet, so I add that into the file and test it and it works. Note I still haven’t committed anything to the repository and I can still test the full functionality of my program. But of course I want to commit these changes. Currently, the file is unstaged; it is modified, but I haven’t told the repository that I intend to commit it yet. I can run a command to put the file in the “staged” area which we will get to in the next section. Now when I run the command to commit, only the staged files will get committed.

Something else of note to point out now is when I compiled and tested my Java program, a Hello World.class file was generated by the compiler. This file is untracked because it is new to the repository and I haven’t told Git to track it yet. But I don’t really want to track the .class files and I don’t want to see them all when I check the status of the repository. Git has a solution to this problem as well. There is a hidden file called .gitignore that is in every repository. You can add all the files (or even kinds of files using regular expressions like *.class) that you want Git to ignore in this repository. Handy huh?

Checkout

“To checkout” is an action that can mean a couple different things in Git. The first and most common is to checkout a branch. This allows you to move from branch to branch as you please. Note you can only change branches if you have no outstanding changes, so you either have to commit the changes or use the stash command to store them away and then the stash pop command to bring them back. The other meaning of “checkout” relates to unstaged changes; You can checkout unstaged changes to revert back to the state they were in before you changed them.

Master

In the Northern Bites world this can be a fairly ambiguous word. Every repository, remote or local, has a master branch. This, for our team, is the branch used for the most stable software. In your local repository’s master branch (referred to as “your master”), you should try to keep as up to date with the Northern-Bites master (referred to as “the master”), which is in the remote repository on Github, as possible. Your master should be where you keep the code that you think is ready for The Master. The master on your personal remote repository on Github (also referred to as “your master”) should stay in line with your local master. Generally, we like to keep the remote repository and the local repository more or less the same.

Structure of Repositories

In our system, we have a remote nbites repository under the northern-bites user on Github. This is the repository that you forked to your own user. This means that you now have an independent copy of this repository, so it’s your job to keep it up to date. In fact, everyone on the team has a similar copy. Then you cloned that repository to your local machine creating a local copy of your own remote copy of the northern-bites nbites repository. Following this?

It is this local repository that you will create your branches on and commit and change things. You can even copy those local branches to your remote repository if you want (in fact we recommend it).

Once you have a branch that you think is ready, you need to “merge” it in with the latest changes in the northern-bites nbites repository and then put these merged changes in your remote repository so that a veteran of the team can officially put them into The Master. So many things to do… have no fear, an example is here!

Learn by Example

Now we are going to learn the every day commands through an example. There are plenty of places you can find a list of the commands and their uses, but hopefully this example will provide a different insight.

So let’s suppose we want to work on a new kick for our robots. The first thing we want to do is make sure we have the latest master. To do this we must update our remotes (of which the northern-bites/nbites repository is one if you followed the instructions in Configuring Git) by running the command

$> git remote update

This will update all of the branches on all of your remotes. Next you need to merge your master with The Master. To do this, you run

$> git checkout master
$> git merge [northern-bites]/master
</pre

Where [northern-bites] is the name of the northern-bites/nbites repository. If you followed the instructions in [[Configuring Git]], it should be northern-bites.
External Resources

This page has some links to guides that will help you learn how to use git.

The Git Reference page is a good, basic look at git. The sidebar reference is great if you need to double check something.
Git Magic is another overview of git. A little longer than the others.
ProGit is a free online book on “Effective Git Use.”
Git for the Lazy is a very short reference guide.
Git Immersion is a long walkthough. It guides you through several labs, teaching you commands as you go. It focuses on a lot of commands that aren’t super useful, and leaves off some of the important ones, so it isn’t a good reference once you have a sense of how to use git.