This document tells you how to follow Linux kernel development (and examine its history) with git. It does not assume you've ever used a source control system before, nor does it assume that you're familiar with "distributed" vs "centralized" source control systems.

Installing git

First, install a recent version of git. (Note that the user interface changed drastically in git-1.5.0, and this page only describes the new interface.)

Downloading the kernel with git

The following command will download the current linux-kernel repository into a local directory called "linux-git":

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git linux-git

Updating your local copy

The command "git pull" downloads all the changes committed to Linus's git repository since the last time you updated your copy, and appends those commits to your copy of the repository (in the .git subdirectory). In addition, this will automatically update the files in your working copy as appropriate. (If your working copy was set to a historical version, it won't be changed, but returning your working copy to the present after a pull will get you the newest version.)

Note that this copies the revision history into your local .git directory. Other git commands (log, checkout, tag, blame, etc.) don't need to talk to the server, you can work on your laptop without an internet connection (or with a very slow one) and still have access to the complete revision history you've already downloaded.

Looking at historical versions

The git log command lists the changes recorded in your repository, starting with the most recent and working back. The big hexadecimal numbers are unique identifiers (sha1sum) for each commit. If you want to specify a commit, you only need the first few digits, enough to form a unique prefix. (Six digits should be plenty.)

Note that git log will only follow renames if you give the --follow option.

You can limit the log to a specific file or directory, which lists only the commits changing that file/directory. Just add the file(s) you're interested in to the end of the git log command line.

The option "-1" tells git log to display only the specific commit you pointed it at. The "-p" option shows the patch as well as the description. The git show command is an alternative for git log -p -1.

The git tag -l command shows all the tagged releases. These human-readable names can be used as synonyms for the appropriate commit identifier, which is useful when doing things like checkout and diff. The special tag "master" points to the most recent commit.

The git blame $FILE command displays all the changes that resulted in the current state of a file. It shows each line, prefixed with the commit identifier which last changed that line. (If the default version of git blame is difficult to read on an 80 charater terminal, try git blame $FILE | sed 's/([^)]*)//' to see more of the file itself.)

Working with historical versions

The git checkout command changes your working copy of the source to a specific version. The -f option to checkout backs out any local changes you've made to the files. The git clean command deletes any extra files in your working directory (ones which aren't checked into the repository). The -d option to clean deletes untracked directories as well as files, the -x option bypasses git ignore rules, and the -f option is required by stupid handholding git configurations like the one that comes with Ubuntu to mean "yes, I really meant to type git clean and hit enter".

So to reset your working copy of the source to a historical version, go git checkout -f $VERSION; git clean -fdx where $VERSION is the tag or sha1sum identifier of the version you want. If you don't specify a $VERSION, git will default to "master" which is the most recent checkout in Linus's tree (what mercurial calls "tip" and Subversion calls HEAD), returning you to the present and removing any uncommitted local changes.

Another way to undo all changes to your copy is to do "rm -rf *" in the linux-git directory (which doesn't delete hidden files like ".git"), followed by "git checkout -f" to grab fresh copies from the repository in the .git subdirectory. This generally isn't necessary. Most of the time, git checkout -f is sufficient to reset your working copy to the most recent version in the repository.

If you lose track of which version is currently checked out as your working copy, use git log to see the most recent commits to the version you're looking at, and git log master to compare against the most recent commits in the repository.

Using git diff

The command "git diff" shows differences between git versions. You can ask it to show differences between:

• git diff - the current version checked out from the respository and all files in the working directory
• git diff v2.6.21 - a specific historical version and all files in the working directory
• git diff v2.6.20 v2.6.21 - all files in two different historial versions
• git diff init/main.c - specific locally modified files in the working directory that don't match what was checked out from the repository
• git diff v2.6.21 init/main.c - specific file(s) in a specific historical version of the repository vs those same files in the working directory.
• git diff v2.6.20 v2.6.21 init/main.c - specific files in two different historical version of the repository

What git is doing is checking each argument to see if it recognizes it as a historical version sha1sum or tag, and if it isn't it checks to see if it's a file. If this is likely to cause confusion, you can use the magic argument "--" to indicate that all the arguments before that are versions and all the arguments after that are filenames.

The argument --find-copies-harder tells git diff to detect renamed or copied files. Notice that git diff has a special syntax to indicate renamed or copied files, which is much more concise and portable than the traditional behavior of removing all lines from one file and adding them to another. (This behavior may become the default in a future version.)

Creating tarballs

The git archive $VERSION command creates a tarball (written to stdout) of the given version. Note that "master" isn't the default here, you have to specify that if you want the most up-to-date version. You can pipe it through bzip and write it to a file (git archive master | bzip2 > master.tar.bz2) or you can use git archive to grab a clean copy out of your local git repository and extract it into another directory, ala:

mkdir $COPY
git archive master | tar xCv $COPY

You can also use the standard Linux kernel out-of-tree building infrastructure on the git working directory, ala:

cd $GITDIR
make allnoconfig O=$OTHERDIR
cd $OTHERDIR
make menuconfig
make

Finally, you can build in your git directory, and then clean it up afterwards with git checkout -f; git clean -d. (Better than "make distclean".)

Bisect

Possibly the most useful thing git does for non-kernel developers is git bisect, which can track down a bug to a specific revision. This is a multi-step process which binary searches through the revision history to find a specific commit responsible for a testable change in behavior.

(You don't need to know this, but bisect turns out to be nontrivial to implement in a distributed source control system, because the revision history isn't linear. When the history branches and comes back together again, binary searching through it requires remembering more than just a single starting and ending point. That's why bisect works the way it does.)

The git bisect commands are:

• git bisect start - start a new bisect. This opens a new (empty) log file tracking all the known good and bad versions.
• git bisect bad $VERSION - Identify a known broken version. (Leaving $VERSION blank indicates the current version, "master".)
• git bisect good $VERSION - Identify a version that was known to work.
• git bisect log - Show bisection history so far this run.
• git bisect replay $LOGFILE - Reset to an earlier state using the output of git bsect log.
• git bisect reset - Finished bisecting, clean up and return to head. (If git bisect start says "won't bisect on seeked tree", you forgot to do this last time and should do it now.)

To track down the commit that introduced a bug via git bisect, start with git bisect reset master (just to be safe), then git bisect start. Next identify the last version known to work (ala git bisect good v2.6.20), and identify the first bad version you're aware of (if it's still broken, use "master".)

After you identify one good and one bad version, git will grind for a bit and reset the working directory state to some version in between, displaying the version identifier it selected. Test this version (build and run your test), then identify it as good or bad with the appropriate git bisect command. (Just "git bisect good" or "get bisect bad", there's no need to identify version here because it's the current version.) After each such identification, git will grind for a bit and find another version to test, resetting the working directory state to the new version until it narrows it down to one specific commit.

The biggest problem with git bisect is hitting a revision that doesn't compile properly. When the build breaks, you can't determine whether or not the current version is good or bad. This is where git bisect log comes into play.

When in doubt, save the git bisect log output to a file (git bisect log > ../bisect.log). Then make a guess whether the commit you can't build would have shown the problem if you could build it. If you guess wrong (hint: every revision bisect wants to test after that comes out the opposite of your guess, all the way to the end) do a git bisect replay ../bisect.log to restart from your saved position, and guess the other way. If you realize after the fact you need to back up, the bisect log is an easily editable text file you can always chop a few lines off the end of.

Note: you can also tell git itself to skip a commit you can't test with git bisect skip. Unfortunately, the git-bisect man page gives this warning about the "skip" command:

But computing the commit to test may be slower afterwards and git may eventually not be able to tell the first bad among a bad and one or more "skip"ped commits.

Example git bisect run

git help

Linus Tovalds talks about git