KernelGitGuide

Redirected from page "KernelGitGuide"

This page redirects to page "Kernel/Dev/KernelGitGuide"

Clear message

Git is the source code management tool used by the Linux kernel developer community. Ubuntu has adopted this tool for our own Linux kernel source code so that we can interact better with the community and the other kernel developers.

Current GIT Trees

All of the current live Ubuntu kernel repositories are at the URL below:

  • http://kernel.ubuntu.com/git-repos/

There is a tree for each of the currently supported releases as well as any open development and upcoming releases:

  • maverick

    git://kernel.ubuntu.com/ubuntu/ubuntu-maverick.git

    lucid

    git://kernel.ubuntu.com/ubuntu/ubuntu-lucid.git

    karmic

    git://kernel.ubuntu.com/ubuntu/ubuntu-karmic.git

    jaunty

    git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git

    hardy

    git://kernel.ubuntu.com/ubuntu/ubuntu-hardy.git

    dapper

    git://kernel.ubuntu.com/ubuntu/ubuntu-dapper.git

Typically the distro kernel is on the master branch in these repositories. A number of releases also have other Topic Branches which represent other related but divergent kernels for other purposes.

To find out what else is available try browsing http://kernel.ubuntu.com/git and searching for ubuntu).

Installing GIT

To use git you must have the git package installed on your system, which you can install like this:

  • sudo apt-get install git

Note if you're running Ubuntu 10.04 LTS (Lucid), you'll instead have to install the git-core package.

Obtaining the kernel sources for an Ubuntu release using git

All of the Ubuntu Kernel source is maintained under git. The source for each release is maintained in its own git repository on kernel.ubuntu.com. These can be browsed in gitweb, the official Ubuntu trees are in the ubuntu/ directory. The Ubuntu Linux kernel git repository is located at git://kernel.ubuntu.com/ubuntu/ubuntu-<release>.git or http://kernel.ubuntu.com/git-repos/ubuntu/ubuntu-<release>.git. To obtain a local copy you can simply git clone the repository for the release you are interested in as below. The git command is part of the git-core package:

  • git clone git://kernel.ubuntu.com/ubuntu/ubuntu-<release>.git

For example to obtain the maverick tree:

  • git clone git://kernel.ubuntu.com/ubuntu/ubuntu-maverick.git

This will download several hundred megabytes of data. If you plan on working on more than one kernel release you can save space and time by downloading the upstream kernel tree. Note that once these two trees are tied together you cannot remove the virgin Linus tree without damage to the Ubuntu tree:

  • git clone git://kernel.ubuntu.com/ubuntu/linux.git
    git clone --reference linux git://kernel.ubuntu.com/ubuntu/ubuntu-karmic.git
    git clone --reference linux git://kernel.ubuntu.com/ubuntu/ubuntu-maverick.git

In each case you will end up with a new directory ubuntu-<release> containing the source and the full history which can be manipulated using the git command from within each directory.

By default you will have the latest version of the kernel tree, the master tree. You can switch to any previously released kernel version using the release tags. To obtain a full list of the tagged versions in the release as below:

  • $ git tag -l Ubuntu-*
    Ubuntu-2.6.27-7.10
    Ubuntu-2.6.27-7.11
    Ubuntu-2.6.27-7.12
    Ubuntu-2.6.27-7.13
    Ubuntu-2.6.27-7.14
    $

To look at the 2.6.27-7.13 version you can simply checkout a new branch pointing to that version:

  • git checkout -b temp Ubuntu-2.6.27-7.13

You may then manipulate the release for example adding new commits.

Maintaining local changes

During development, the kernel git repository is being constantly rebased against Linus' tree. IOW, Ubuntu specific changes are not being merged, but rather popped off, the tree updated to mainline, and then the Ubuntu specific changes reapplied; they are rebased. There are two ways to track the kernel git tree, depending on whether you have local changes or not:

No Local Changes

  • git fetch
    git reset --hard origin/master

Preserve Local Changes

  • git fetch
    git rebase --onto origin/master origin/master@{1}

Pushing changes to the main repo

Since the main repo is not publicly writable, the primary means for sending patches to the kernel team is using git format-patch. The output from this command can then be sent to the kernel-team mailing list.

Alternatively, if you have a publicly available git repository for which changes can be pulled from, you can use git request-pull to generate an email message to send to the kernel-team mailing list.

Using Commit templates

In debian/commit-templates/ in the source tree there are several templates that should be used when committing changes that you expect to be integrated with the Ubuntu kernel repo. The commit templates contain comments for how to fill out the required information. Also note that all commits must have a Signed-off-by line (the "-s" option to git commit). A typical git commit command will look like:

  • git commit -s -F debian/commit-templates/patch -e

Note that the -e (edit) option must follow the -F option, else git will not let you edit the commit-template before committing. The primary one you will use is the patch template. It is commented heavily, so should be self explanatory. Some templates do not require editing such as the bumpabi and updateconfigs templates. An example commit log will look like this:

  • UBUNTU: scsi: My cool change to the scsi subsystem
    
    UpstreamStatus: Merged with 2.6.15-rc3
    
    My cool change to the scsi subsystem makes scsi transfers increase
    magically to 124GiB/sec.
    
    Signed-off-by: Joe Cool Hacker <jch@ubuntu.com>

The first line is critical and should summarise the change. The prefix for the line defines the type of the commit (see below). The last line should contain your sign-off for the patch and any acks it has received. The remainder of the text should concisely describe the change.

  • Prefix

    Meaning

    UBUNTU: SAUCE:

    a kernel source modification which is specific to Ubuntu

    UBUNTU: [Config]

    a change to the kernel configuration

    UBUNTU:

    any other change to the debian packaging for the kernel

    <none>

    upstream kernel patches

Patch acceptance criteria

In general, Ubuntu will apply the same criteria applicable to upstream kernel. Here is a checklist of reading and tools related to posting kernel patches:

  • <kernel-directory>/Documentation/SubmittingPatches

  • <kernel-directory>/scripts/checkpatch.pl

  • <kernel-directory>/scripts/cleanpatch

  • <kernel-directory>/scripts/cleanfile

  • <kernel-directory>/scripts/Lindent

If you are creating a new file, it is helpful to run it through cleanfile and/or Linent before creating a patch
If you have generated a patch, it helps running it through checkpatch.pl and cleanpatch if necessary
Also, using the commit template described above is a good idea for Ubuntu-specific patches

Developers with access to kernel.ubuntu.com

The kernel team has a git repo located on kernel.ubuntu.com (AKA zinc.ubuntu.com) in /srv/kernel.ubuntu.com/git/ubuntu.

You can, if you want, create a clone for yourself in your directory, and just have your changes pulled when ready.

Suggested way to do this:

  • git clone -l -n -s /srv/kernel.ubuntu.com/git/ubuntu/ubuntu-jaunty.git
    vi ubuntu-jaunty/.git/description
    ( give it a descriptive name )
    mv ubuntu-jaunty/.git /srv/kernel.ubuntu.com/git/<user>/my-git-tree.git

You can now push your changes to this tree via ssh. Note the -l -n -s options do a few special things, mainly making your repo share objects with ours (saves space).

Now you need to run git update-server-info in your tree so that it is available over http transport

  • cd /srv/kernel.ubuntu.com/git/<user>/my-git-tree.git
    git update-server-info
    chmod +x /srv/kernel.ubuntu.com/git/<user>/my-git-tree.git/hooks/post-commit

To work on your branch, now clone to your local machine from the same origin tree (not the tree you just created on zinc -- this is only for pushing to):

  • git clone git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git my-tree
    git remote add zinc ssh://kernel.ubuntu.com/srv/kernel.ubuntu.com/git/<user>/my-git-tree.git
    <do work>
    git push zinc maser

Suggested method for keeping this tree synced with the ubuntu tree, instead of git pull, is to do:

  • cd my-tree
    git fetch origin
    git rebase origin

This will keep your changes on top of the original tree (as opposed to being merged). This is also a good idea because during development (e.g. while following the upstream git repo), we frequently rebase to linux-2.6.git upstream, so the HEAD is not always suitable for pull/merge.

Git tips and tricks

Reordering patches

  • git rebase -i HEAD~10

allows you to interactively reorder the last 10 patches in your branch. You can also squash some patches together. Just follow the directions at the bottom of the file opened up on typing the command.

.gitconfig

Setting up your $HOME/.gitconfig file can help reduce the number of arguments you need to specify to git commands, and let you specify commonly used remote repositories.

  • [user]
            email = sconklin@canonical.com
            name = "Steve Conklin"
            signingkey = 0x3A758A1E
    
    [sendemail]
    smtpuser = sconklin@canonical.com
    envelopesender=sconklin@canonical.com
    smtpserver = /usr/bin/msmtp

Is what I have in my file to set up my email address and email.

  • [remote "sconklin"]
            url = "ssh://sconklin@zinc.canonical.com/srv/kernel.ubuntu.com/git/sconklin/ubuntu-karmic.git"
            fetch = +refs/heads/*:refs/remotes/sconklin/*
    [remote "drm-2.6"]
            url = "git://git.kernel.org/pub/scm/linux/kernel/git/airlied/drm-2.6"
            fetch = +refs/heads/*:refs/remotes/drm-2.6/*
    [remote "drm-intel"]
            url = "git://git.kernel.org/pub/scm/linux/kernel/git/anholt/drm-intel"
            fetch = +refs/heads/*:refs/remotes/drm-intel/*

Sets up the remote repositories that I use most often. With these in the config, I can "git fetch sconklin" in any repo and get that remote.

A google search for ".gitconfig" will turn up other useful settings.

More information

Please read the documentation included with the git-core package for more details on git commands. A tutorial is also available at http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html.

For a list of quick git recipes and examples, see KernelTeam/GitCheatSheet.


CategoryKernel CategoryDocumentation

KernelTeam/KernelGitGuide (last edited 2010-06-28 23:55:41 by leannogasawara)