== Git, quilt and binary searching ==

Generally, kernel source trees are maintained using two basic tools, git and quilt. While
it is true that you can also use some git ”frontends”, like Cogito, Stacked GIT, Patchy Git
(pg), (h)gct, which simplify user interactions with this tool, we will focus on git itself and
on quilt, since each of them is strictly related to a specific way of maintaining a source tree.

== 4.1 Git ==

Git is a versioning control system written by Linus Torvalds specifically for the maintenance of the main Linux kernel source tree (ie. the mainline). The current maintainer of git itself is Junio C. Hamano and the latest version is git-1.5.1.3.

Of course, to use git you need to install it in your system, but all of the contemporary Linux distributions provide git packages that can be installed in usual ways. The most important of these packages is usually called git-core, as it contains the most basic git components. Alternatively, you can download the source code of git from http://www.kernel.org/pub/software/scm/git/ and build it yourself.

Like some other versioning control systems (eg. CVS ), git assumes that there is a central ”master” directory tree used as a reference for all changes made to the maintained source code. This directory tree contains the source code itself along with the history of all changes made to it since certain point in time. To be registered in the ”master” tree, the changes must be accepted by its maintainer (eg. by Linus, in the case of the Linux kernel ”master” tree) and after they have been registered (”committed” in the git-related terminology) all of the users of this tree can ”see” the source code with these changes applied. Still, they can also see how the source code looked like before specific modifications and they can follow its history (ie. view all modifications made to it after given point that may be specified in many different ways). For this reason each modification of the source code is registered in the ”master” tree along with additional information including, among other things, the name and email address of its author and a short description of the purpose and scope of the modification (known as the ”changelog”).

If you create a copy of the Linux kernel ”master” tree, all of the information contained in it will be available to you locally and can be used for many different purposes. In particular, you can use them to identify the modifications that have introduced bugs.

To make a copy of this tree, or to ”clone” it in the git language, you can run

{{{$ git-clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git linux-git}}}

This will download the entire Linus’ git tree to your machine and the local copy of it will be located in the subdirectory linux-git of the current directory (ie. the one that was current when the above command was being executed). You should remember, however, that the Linus’ tree is huge, so the download may take quite a lot of time, depending on your Internet connection’s bandwidth and the current load of the kernel.org’s git server. If you are not going to use the git capabilities described below, it might be less cumbersome to download stand-alone patches and apply them as described in Section 1.2.

Once you have downloaded the Linus’ git tree, it generally is a good idea to tell git that it is the the tree that you want to start with. To do this, change directory to linux-git and run

{{{$ git-checkout -f}}}

Now, you are able to do some really nice things with the help of git . For example, you can synchronize your local copy of the Linus’ tree with the original one by downloading only the changes that were committed by Linus after you had run git-clone . For this purpose, run
{{{
$ git-pull git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
$ git-checkout
}}}
Of course, this means that you don’t need to run git-clone every time the Linus’ tree changes. Moreover, you should not do this. In fact, it is only necessary do download the Linus’ tree once and then use git-pull to update your local copy. Naturally, if you make your own changes to the local copy of the tree, git-pull may fail, but then you can use ’{{{git-checkout -f}}}’ to revert all of the conflicting changes. Still, if you want to save your modifications, it is not that easy any more, but we won’t discuss this case any further (for more information see, for example, the tutorial at http://www.kernel.org/pub/software/scm/git/docs/tutorial.html).

Apart from the git commands presented above, you will probably find the following ones useful:
 * {{{git-whatchanged <file>}}} – shows all changes affecting given source file (the patch relative to the git tree’s root directory should be provided)
 * {{{git-bisect *}}} – used for binary searching for buggy patches (see below)
 * {{{git-revert *}}} – reverts given change (”commit” in the git terminology)
 * {{{gitk}}} – graphically visualizes the tree
 * {{{git-show}}} – prints given commit
 * {{{git-log}}} – shows the list of changes made to the tree
In our opinion particularly useful is the git-log command that allows you to track the history of the source code. By running

{{{$ git-log}}}

you can see all changes made since the Linus’ tree was created. Well, albeit impressive, this is not particularly useful, because there are very many of them, but you can easily narrow the scope of its output. For example, the command

{{{$ git-log v2.6.19..+}}}

will print the changes made since the version 2.6.19 of the kernel (this won’t work for v2.6.21.., but we don’t know why), and the following one:

{{{$ git-log --since="7 days ago"}}}

will give you all changes made since – you have guessed it – 7 days ago. Isn’t it nice?

While playing with git-log you can see that each change, or commit, in the log starts from the word commit and a long hexadecimal number. These numbers are unique commit identifiers that can be used for referring to specific commits in many git commands. For example, if you want to see the source code modifications associated with commit b5bf28cde894b3bb3bd25c13a7647020562f9ea0 in the form of a patch, run

{{{$ git-show b5bf28cde894b3bb3bd25c13a7647020562f9ea0}}}

It sometimes is unnecessary to use the entire commit identifier here, since several initial characters may be sufficient to identify the ob ject. Thus to get the same result as from the above command, it may be sufficient to run

{{{$ git-show b5bf28}}}

Of course, if you want to save the resulting patch in a file, it is only necessary to do

{{{$ git-show b5bf28 > b5bf28.patch}}}

where b5bf28.patch can be replaced with an arbitrary file name.

When you run such git commands as git-clone or git-pull, some data are being transferred over the Internet. In such cases you should always use the git:// protocol designed specifically for transferring git ob jects. Still, sometimes you may not be able to do this (eg. if you are behind a firewall that you cannot configure) and then you can use the ”ordinary” http:// protocol, but it is not generally recommended.

It is worthy of noting that the Linus’ tree is not the only git tree downloadable from kernel.org . The other ones correspond to various development branches of the kernel introduced in Section 1.3. At http://git.kernel.org there is the list of all git trees available from kernel.org . Another list of kernel git tree is available from http://git.infradead.org .

To learn more about git, you can read the documentation distributed along with it or visit, for instance, the web page at http://www.kernel.org/pub/software/scm/git/docs