I’ve convinced my work colleagues over at Gecko-Research to start using Git.  I’m a git neophyte myself, but now I’m in the position of setting up our Git repository, and teaching my colleagues how to use it. I’ve written up a little guide to using Git, aimed as a reference for myself and my colleagues.   As such, it’s just a list of the commands that we use on a regular basis, or the situations we are often confronted with (and how to deal with them).  The post is totally a work in progress, so it will likely change quite a bit over the next few months as I flesh it out as needs arise.

If you are interested in a general introduction to git, or a tutorial, I would suggest one of the following:

• Git for the lazy.
• Git Tutorial
• Google Tech talk on Git

Git has a reputation for being difficult to use, or counter intuitive, but I think that’s just due to it being a distributed rather than central revisioning system (based on the concept of a central repository).  Some things do get tricky, but I think it’s primarily because git lets you work in new ways that can potentially trip you up.

Central repository systems are easy to conceptualize,  and they’re what people of our generation are used to, so they are easy to get started with.  Git  is based on a distributed model, in which each repository is equal (we can assign different roles to different repositories, but it’s not technologically imposed).    Considering that distributed systems are so becoming the norm (bittorrent, wikipedia, the free software movement, multi core computing, creative commons, blogging, twitter…) ,  I suspect tech heads growing up now will find thinking in a distributed way as simple as we old farts find the top-down, central-repository, client-server model.

Daily Use

Note that these comments are aimed at my colleagues. Your work situation may vary.

commiting

You should commit your work whenever you get anything done that can easily be summed up in one line (the commit message). There are other reasons to commit, so when in doubt, do a commit. It’s easy to go back if you need to. Committing doesn’t go on the net, it just tells your local git repository that you got some work done, and puts those changes onto the local index (git’s database of what’s what). Frequent commits will save you hassles. The command is:

 git commit -a

The -a tells git to commit all modified files (which are being tracked). You can also just commit specific files by using

 git commit <list of files>

more to come…

Configuration

gitignore file:

A gitignore file specifies intentionally untracked files that git should ignore.  It concerns files that are not tracked by git, and that you don’t want to track with git, so temporary files, results of compilation, compled documentation, etc.  The man page is here.  When git is determining what files to ignore it:

1. Checks for a relevant command line option
2. Check patterns from a .gitignore file in the same directory as the path, or in any parent directory.
3. Check for patterns in $GIT_DIR/info/exclude
4. Check for patterns in the configuration variable core.excludesfile

The man page describes the patterns, which are anyway pretty close to the usual *nix conventions that you’ll probably just get them right.  As an example, here’s my .gitignore file for a netbeans project:

*.class
*~
build/
javadoc/

This tells git to ignore any build or javadoc directories, as well as emacs temporary files.  Taking the time to setup a .gitignore file when you are starting a new project with git will make everything else more convenient down the line.

Collaboration: tracking multiple branches

Because of some wonky security policies on our institute’s network, we can’t directly push and pull from each other, so we go over a central repository. Many of us work on multiple machines, so we want to use the central repository as a convenience tool for synching up between our machines, but we don’t necessarily want out colleagues pulling our work-in-progress. The solution is for each of us to have our own branch. This post tells us how to start a new branch on a remote git repository. The steps are basically:

1. Create a remote branch. This can be done with the command

    git push origin origin:refs/heads/new_feature_name

   (assuming your remote repository is called origin).

2. Make sure everything is up to date with

    git fetch origin

3. Start tracking the new branch with

    git checkout --track -b new_feature_name origin/new_feature_name

4. Make sure everything is up to date by doing a pull.

   git pull

The third command,

 git checkout --track -b new_branch origin/new_feature_name

is one you’ll run several times, every time you clone a repository somewhere, you’ll want to use to track all the various branches you are interested in. That way you can checkout your colleagues (or bug fix) branches when you like, and merge them into your work whenever it is useful.

Situations

Deleting a branch. Okay, so you’ve been branching all over the place, and now you realize you have some dead hanging branches you really don’t want cluttering up your repository anymore.   To get rid of a branch on the remote repository, you’ll want to do the following:

git push origin :head/branch_to_delete