Kernel Hackers' Guide to git

Serial ATA
This tutorial is a cookbook of recipes getting up and running w ith Linus's source code
IPv6 management (SCM) softw are, "git." Its targetted mainly at Linux kernel hackers, though
others may find it useful.
DNS
Table of Contents
Current projects
Getting Started
Installing git
First kernel tree download
Private .rpm
Basic tasks Repository
Download remote tree updates Spend more time
Undo all working dir modifications building. While we
Undo recent commits run your repo
Check in changes
Generate diff of working dir changes
Generate summary of working dir changes
List all changeset descriptions
List all changeset descriptions belonging to a specific file
Branches
List all branches
Switch working dir to new branch
Create new branch
List current branch
Diff against master branch
List changes present only on local branch
Merge changes from one branch into another
Misc. debris
Check out an older kernel version
Apply mailbox full of patches
Download tags periodically
Create a tag
Further reading

Getting Started
Installing git
git requires bootstrapping, since you must have git installed in order to
check out git.git (git repository), and linux-2.6.git (kernel repository).
You may find that your distribution already provides a usable version
of git. If so, try that first.

Fedora 7 and later: The git-core package is available through the standard package
repositories. Fedora Core 3 through 6: git-core package is in Fedora Extras.

yum install git-core

If your distro does not package git, you may dow nload the latest stable release from:
http://www.kernel.org/pub/software/scm/git/

tarball build-deps: zlib, libcurl, libcrypto (openssl)

install tarball:

unpack && make prefix=/usr/local && sudo make prefix=/usr/local install

After reading the rest of this document, come back and update your copy of git to the
latest: git://git.kernel.org/pub/scm/git/git.git

Download a linux kernel tree for the very first time

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

NOTE: The kernel tree is very large. This constitutes dow nloading just over 300 megabytes
of compressed data (as of Jun 2008).

converted by W eb2PDFConvert.com
Basic Tasks
Update local kernel tree to latest 2.6.x upstream ("fast-
forward merge")

$ cd linux-2.6
$ git pull git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git

or more simply, to pull from the location from w hich you cloned:

$ cd linux-2.6
$ git pull

to pull from the origin repository from w hich you originally cloned the tree.
Undo all local modifications:

$ git checkout -f

Check in your own modifications (e.g. do some hacking, or

apply a patch)

# go to repository
$ cd linux-2.6

# make some modifications

$ vi drivers/net/sk98lin/skdim.c

# NOTE: Run 'git add' and 'git rm' if adding or removing files.

# check in all modifications

$ git commit -a

Undo recent commits:

Sometimes you have made a few commits, or just pulled a change, and simply w ant those
commits to go aw ay.

$ cd my-kernel-tree-2.6
$ git reset HEAD~2 # make last 2 commits disappear

w ill "disappear" the top tw o commits. DO NOT do this, if anyone has downloaded a tree
containing the commits you just eliminated.

Note that this is quite different from git revert, w hich applies a reversed patch as an
additional commit.

List all changes in working dir, in diff format.

Display changes since last 'git add' or 'git rm':

$ git diff

Display changes since last commit:

$ git diff HEAD

Obtain summary of all changes in working dir

$ git status

converted by W eb2PDFConvert.com
List all changeset descriptions

$ git log

The 'git log' option "-p" show s diffs in addition to changeset text. The option "--stat" show s
the diffstat in addition to the changeset text.
List all changesets belonging to a specific file
(in this case, net/ieee80211/ieee80211_module.c)

$ git log net/ieee80211/ieee80211_module.c

Branches
List all branches

$ git branch

Make desired branch current in working directory

$ git checkout $branch

Create a new branch, and make it current

$ git checkout -b my-new-branch-name master

Examine which branch is current

$ git status

('git branch' also show s you the current branch, using a "*" to indicate this)

Obtain a diff between current branch, and master branch

In most trees with branches, .git/refs/heads/master contains the current 'vanilla' upstream
tree, for easy diffing and merging. (in trees w ithout branches, 'master' simply contains your
latest changes)

$ git diff master..HEAD

(this is equivalent to git diff HEAD, w hen used w ith HEAD branch)

Obtain a list of changes between current branch, and master

branch

$ git log master..HEAD

(this is equivalent to git log, w hen used w ith HEAD)

or rather than full changeset descriptions, obtain a one-line summary of each changes:

$ git shortlog master..HEAD

Merge changes from one branch into another

Let us suppose that you do w ork on branch A and branch B, and after w ork on those tw o
branches is complete, you merge the w ork into mainline branch M.

$ git checkout M # switch to branch M

converted by W eb2PDFConvert.com
 $ git merge A # merge A into M
$ git merge B # merge B into M

Misc. Debris
Optimize your repository
git is heavily optimized for fast storage and retrieval on a per-command basis. How ever,
over a long period of time, it can be useful to perform further optimizations, including
packing all git objects into single "packfile" for fast retrieval and less w asted disk space.

$ cd my-kernel-tree-2.6
$ git gc

w ill optimize your repository. You don't need to run this frequently — git is quite fast even
w ithout it. See the 'git gc' man page for more details.

Check out an older kernel version

$ cd my-kernel-tree-2.6
$ git checkout -b tmp v2.6.22

This creates a temporary branch 'tmp', w ith the contents of kernel version 2.6.22.

Apply all patches in a Berkeley mbox-format file

First, make sure that the tools subdirectory of the git-core repository is in your PATH.

$ cd my-kernel-tree-2.6
$ git am --utf8 --signoff /path/to/mbox

The file /path/to/mbox is a Berkeley mbox file, containing one or more patches to be
committed to the git repository. The --signoff option indicates that 'git am' should append
the

Signed-off-by: Your Name <[email protected]>

line that is common to almost all kernel submissions. The name and email address are
taken from the GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL environment variables
(I recommend setting these in your .bash_profile or similar file).

Don't forget to download tags from time to time.

git pull only dow nloads sha1-indexed object data, and the requested remote head. This
misses updates to the .git/refs/tags/ and .git/refs/heads/ directories. For tags, run git
fetch --tags $URL.

Tag a particular commit.

For your ow n repositories, you may w ish to give interesting or significant commits a name,
know n as a tag. The Linux kernel uses tags to for each kernel version: "v2.6.21", "v2.6.22",
etc.

$ cd my-kernel-tree-2.6
$ git tag my-tag

creates a new tag named "my-tag", based on the current commit. You can do a lot more
w ith tagging, including GPG-signing, so read the man page for more details.

Further reading
Another good introduction is the official git tutorial, follow ed by the more in-depth git man
page documentation.

C opyright © 2008 Jeff Garzik

converted by W eb2PDFConvert.com
converted by W eb2PDFConvert.com