The guts of git

Now that BitKeeper is no more, how will the kernel development process function? In the short term, the answer is "painfully." The rest of the 2.6.12 process looks like the good old days: patches emailed to Linus, who will apply them (hopefully) and occasionally release a snapshot tree. That mode might work for the short term, since only bug fixes should be merged before 2.6.12 comes out, but nobody wants to try to run the process that way for any period of time. The kernel team needs much better patch and workflow support if it is going to sustain a reasonable development pace. So a replacement for BitKeeper will have to come from somewhere.

For a while, the leading contender appeared to be monotone, which supports the distributed development model used with the kernel. There are some issues with monotone, however, with performance being at the top of the list: monotone simply does not scale to a project as large as the kernel. So Linus has, in classic form, gone off to create something of his own. The first version of the tool called "git" was announced on April 7. Since then, the tool has progressed rapidly. It is, however, a little difficult to understand from the documentation which is available at this point. Here's an attempt to clarify things.

Git is not a source code management (SCM) system. It is, instead, a set of low-level utilities (Linus compares it to a special-purpose filesystem) which can be used to construct an SCM system. Much of the higher-level work is yet to be done, so the interface that most developers will work with remains unclear.

At the lower levels, Git implements two data structures: an object database, and a directory cache. The object database can contain three types of objects:

• Blobs are simply chunks of binary data - they are the contents of files. One blob exists in the object database for every revision of every file that git knows about. There is no direct connection between a blob and the name (or location) of the file which contains that blob. If a file is renamed, its blob in the object database remains unchanged.

• Trees are a collection of blobs, along with their file names and permissions. A tree object describes the state of a directory hierarchy at a particular given time.

• Commits (or "changesets") mark points in the history of a tree; they contain a log message, a tree object, and pointers to one or more "parent" commits (the first commit will have no parent).

The object database relies heavily on SHA hashes to function. When an object is to be added to the database, it is hashed, and the resulting checksum (in its ASCII representation) is used as its name in the database (almost - the first two bytes of the checksum are used to spread the files across a set of directories for efficiency). Some developers have expressed concerns about hash collisions, but that possibility does not seem to worry the majority. The object itself is compressed before being checksummed and stored.

It's worth repeating that git stores every revision of an object separately in the database, addressed by the SHA checksum of its contents. There is no obvious connection between two versions of a file; that connection is made by following the commit objects and looking at what objects were contained in the relevant trees. Git might thus be expected to consume a fair amount of disk space; unlike many source code management systems, it stores whole files, rather than the differences between revisions. It is, however, quite fast, and disk space is considered to be cheap.

The directory cache is a single, binary file containing a tree object; it captures the state of the directory tree at a given time. The state as seen by the cache might not match the actual directory's contents; it could differ as a result of local changes, or of a "pull" of a repository from elsewhere.

If a developer wishes to create a repository from scratch, the first step is to run init-db in the top level of the source tree. People running PostgreSQL want to be sure not to omit the hyphen, or they may not get the results they were hoping for. init-db will create the directory cache file (.dircache/index); it will also, by default, create the object database in .dircache/objects. It is possible for the object database to be elsewhere, however, and possibly shared among users. The object database will initially be empty.

Source files can be added with the update-cache program. update-cache --add will add blobs to the object database for new files and create new blobs (leaving the old ones in place) for any files which have changed. This command will also update the directory cache with entries associating the current files' blobs with their current names, locations, and permissions.

What update-cache will not do is capture the state of the tree in any permanent way. That task is done by write-tree, which will generate a new tree object from the current directory cache and enter that object into the database. write-tree writes the SHA checksum associated with the new tree object to its standard output; the user is well-advised to capture that checksum, or the newly-created tree will be hard to access in the future.

The usual thing to do with a new tree object will be to bind it into a commit object; that is done with the commit-tree command. commit-tree takes a tree ID (the output from write-tree) and a set of parent commits, combines them with the changelog entry, and stores the whole thing as a commit object. That object, in essence, becomes the head of the current version of the source tree. Since each commit points to its parents, the entire commit history of the tree can be traversed by starting at the head. Just don't lose the SHA checksum for the last commit. Since each commit contains a tree object, the state of the source tree at commit time can be reconstructed at any point.

The directory cache can be set to a given version of the tree by using read-tree; this operation reads a tree object from the object database and stores it in the directory cache, but does not actually change any files outside of the cache. From there, checkout-cache can be used make the actual source tree look like the cached tree object. The show-diff tool prints the differences between the directory cache and what's actually in the directory tree currently. There is also a diff-tree tool which can generate the differences between any two trees.

An early example of what can be done with these tools can be had by playing with the git-pasky distribution by Petr Baudis. Petr has layered a set of scripts over the git tools to create something resembling a source management system. The git-pasky distribution itself is available as a network repository; running "git pull" will update to the current version.

A "pull" operation, as implemented in git-pasky, performs these steps:

• The current "head" commit for the local repository is found; git-pasky keeps the SHA checksum for the current commit in .dircache/HEAD.

• The current head is obtained from the remote repository (using rsync) and compared with the local head. If the two are the same, no changes have been made and the job is done.

• The remote object database is downloaded, again with rsync. This operation will add any new objects to the database.

• Using diff-tree, a patch from the previous (local) version to the current (remote) version is generated. That patch is then applied to the current directory's contents. The patch technique is used to help preserve, if possible, any local changes to the files.

• A call to read-tree updates the directory cache to match the current revision as obtained from the remote repository.

Petr's version of git adds a number of other features as well. It is a far cry from a full-blown source code management system, since it lacks little details like release tagging, merging, graphical interfaces, etc. A beginning structure is beginning to emerge, however.

When this work was begun, it was seen as a sort of insurance policy to be used until a real source management system could be found. There is a good chance, however, that git will evolve into something with staying power. It provides the needed low-level functionality in a reasonably simple way, and it is blindingly fast. Linus places a premium on speed:

As if on cue, Andrew announced a set of 198 patches to be merged for 2.6.12:

If this test (and the ones that come after) goes well, and the resulting system evolves to where it meets Linus's needs, he may be unlikely to switch to yet another system in the future. So git is worth watching; it could develop into a powerful system in a hurry.

Index entries for this article
Kernel	Development tools/Git
Kernel	Git

---

(Log in to post comments)

On Tue, 12 Apr 2005, Andrew Morton wrote:

>> 
>> This is the first live test of Linus's git-importing ability.  I'm about
>> to disappear for 1.5 weeks - hope we'll still have a kernel left when I
>> get back.


Yee-haa! 198 patches applied in less than 3 minutes. That's pretty exactly
the "one patch per second" I was aiming for (0.8 seconds per patch, so my
estimate from a few days ago of 0.75 was pretty much on the money).

	> du -sh .git 

	102M    .git

	> time dotest ~/andrews-first-patchbomb
	.. "Applying" messages scroll past ..

	real    2m39.840s
	user    1m40.594s
	sys     0m58.179s

	> time show-diff
	
	real    0m0.148s
	user    0m0.080s
	sys     0m0.068s

	> du -sh .git

	111M    .git

ie we added 9MB of stuff from a set of emails that totaled a 859kB mbox.

So say an expansion of about 10x over the pure emailed patches. Which is 
not out-of-line with my expectations, but considering that you _could_ 
have just compressed the patches and thrown the headers away and you'd 
have gotten a 190kB archive of just pure patches, it's not like this is 
hugely space-efficient.

I don't think I ever claimed it would be ;)

Anyway, I'm not going to release this tree, because quite frankly I want 
to double-check that everything went right, and I want to re-base the 
archive on some more history than starting _purely_ from scratch in 
2.6.12-rc2 (maybe from 2.6.11), but in general it looks good. Now, if I 
can get the stupid merging going on, it will actually be _useful_ ;)

			Linus

PS. Yes, the tree still builds after this exercise ;)

On Tue, 12 Apr 2005, Andrew Morton wrote:
>
> Linus Torvalds (torvalds at osdl.org) wrote:
> >
> > ie we added 9MB of stuff from a set of emails that totaled a 859kB mbox.
> 
> The total size of the commits list since Nov 2002 is 500MB, excluding those
> "merge" thingies.
> 
> So I assume that the git tree will grow at 2GB/year.

Yes, that's within my mental envelope. I was estimating a 3-5GB git
archive for the last three years of BK work.

The good news is that the way git works, you really can put the old
history in "storage" - throw it away (and just rely on the distribution
meaning that it's _somewhere_ out there on the net) or write it on a DVD
and forgetting about it. Most people really only care about the last few 
months.

Is 2GB a year a lot? I think it's peanuts, but hey, I can fill up my whole 
disk with kernel trees, and I wouldn't feel it's wasted space. Others may 
have slightly different priorities ("hey, I could fit 5000 songs in 
there!")

                Linus

-rw-r--r--    1 0        0            8751 Jun 06  1996 git-4.3.10-4.3.11.diff.gz
-rw-r--r--    1 0        0           55745 Aug 30  1996 git-4.3.11-4.3.12.diff.gz
-rw-r--r--    1 0        0           76156 Nov 12  1996 git-4.3.12-4.3.13.diff.gz
-rw-r--r--    1 0        0           39461 Dec 05  1996 git-4.3.13-4.3.14.diff.gz
-rw-r--r--    1 0        0           35846 Dec 24  1996 git-4.3.14-4.3.15.diff.gz
-rw-r--r--    1 0        0           12872 Jan 28  1997 git-4.3.15-4.3.16.diff.gz
-rw-r--r--    1 0        0          336211 Jan 28  1997 git-4.3.16.tar.gz
-rw-r--r--    1 0        0          402888 Mar 14  1998 git-4.3.17.tar.gz
-rw-r--r--    1 0        0            5629 Jun 29  1999 git-4.3.18-4.3.19.diff.gz
-rw-r--r--    1 0        0          406138 Jun 01  1999 git-4.3.18.tar.gz
-rw-r--r--    1 0        0           21475 Mar 13  2000 git-4.3.19-4.3.20.diff.gz
-rw-r--r--    1 0        0          406914 Jun 29  1999 git-4.3.19.tar.gz
-rw-r--r--    1 0        0          426648 Mar 13  2000 git-4.3.20.tar.gz