KernelGitGuide

Differences between revisions 32 and 68 (spanning 36 versions)

Summary

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 obtain the git binaries, simply install the git-core package:

```
sudo apt-get install git-core
```

Use apt-get because other tools such as aptitude will autoremove packages that have no install links.

Note that the git package is an entirely different tool which will not do what you want.

Getting the Ubuntu Linux kernel repo

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-<release>.git. To download a local copy of the repo, use this command:

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

This will take some time depending on your connection. There is several hundred megabytes of data to download.

Alternately, if you plan on working on more than one kernel release you can save space and time by downloading the upstream kernel tree. Then, other releases can be downloaded with the --reference option which will avoid downloading redundant objects:

git clone git://kernel.ubuntu.com/ubuntu/linux-2.6
git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git
git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-karmic.git
git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-lucid.git

Change into the directory:

```
cd ubuntu-jaunty
```

By default you will have the latest version of the kernel tree, the master tree. You can get a copy of the kernel version you want to work on. To determine which the latest official release is:

```
git tag -l Ubuntu-*
```

This results in something like this:

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

For example, with the exact above output you could checkout the latest released version of the kernel:

```
git checkout Ubuntu-2.6.27-7.14
```

Once this is complete, you can keep your tree up-to-date by running this command:

```
git fetch
```

** Warning ** 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.

Commit templates

In debian/commit-templates/ there are several templates that must 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.

An example commit log will look like such:

  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>

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
*do work*
git send-pack kernel.ubuntu.com:/srv/kernel.ubuntu.com/git/<user>/my-git-tree.git master

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 c-76-105-148-120)

-  ⇤ ← Revision 32 as of 2008-01-30 18:42:12 → 
  Size: 6774
  Editor: 63
  Comment:
+   ← Revision 68 as of 2010-06-08 07:55:04 → ⇥
  Size: 9864
  Editor: 91
  Comment: sp
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
+## page was renamed from KernelGitGuide
-Line 2:
+Line 5:
-Git is the new SCM used by the Linux kernel developers. 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.

= Where is it? =

http://kernel.ubuntu.com/
+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.
 Line 10:
- * hardy: git://kernel.ubuntu.com/ubuntu/ubuntu-hardy.git
 * gutsy: git://kernel.ubuntu.com/ubuntu/ubuntu-gutsy.git
 * feisty: git://kernel.ubuntu.com/ubuntu/ubuntu-feisty.git
 * edgy: git://kernel.ubuntu.com/ubuntu/ubuntu-edgy.git
 * dapper: git://kernel.ubuntu.com/ubuntu/ubuntu-dapper.git

(actually there are a few more and of special note are the -updates git trees. To find out what else is available try browsing http://kernel.ubuntu.com/git and searching for ubuntu)

= Getting GIT =

To obtain the git binaries, simply install the `git-core` package from dapper, e.g.:
{{{
sudo apt-get install git-core
}}}
+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 [[KernelTeam/TopicBranches|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 obtain the git binaries, simply install the `git-core` package:
    {{{
sudo apt-get install git-core}}}

'''Use apt-get because other tools such as aptitude will autoremove packages that have no install links.'''
-Line 28:
+Line 42:
-The Ubuntu Linux kernel git repository is located at git://kernel.ubuntu.com/ubuntu/ubuntu-<release>.git. To download a local copy of the repo, use this command:
{{{
  git clone git://kernel.ubuntu.com/ubuntu/ubuntu-hardy.git ubuntu-hardy
}}}

This will take some time depending on your connection. There's around 220 MiB of data to download currently (and this always increases).
+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-<release>.git.  To download a local
copy of the repo, use this command:

    {{{
git clone git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git
}}}

This will take some time depending on your connection. There is several
hundred megabytes of data to download.

Alternately, if you plan on working on more than one kernel release you can save space
and time by downloading the upstream kernel tree.  Then, other releases can
be downloaded with the --reference option which will avoid downloading redundant objects:

    {{{
git clone git://kernel.ubuntu.com/ubuntu/linux-2.6
git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git
git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-karmic.git
git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-lucid.git
}}}

Change into the directory:

    {{{
cd ubuntu-jaunty}}}

By default you will have the latest version of the kernel tree, the
master tree.  You can get a copy of the kernel version you want to work
on. To determine which the latest official release is:

    {{{
git tag -l Ubuntu-*}}}

This results in something like this:

    {{{
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}}}

For example, with the exact above output you could checkout the latest
released version of the kernel:

    {{{
git checkout Ubuntu-2.6.27-7.14}}}
-Line 36:
+Line 93:
-{{{
  git pull
}}}
+    {{{
git fetch}}}
-Line 41:
+Line 97:
-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 rebased and then pushed on to keep them on top. This will cause git pull to fail. Hence, there are two ways to track the kernel git tree, depending on whether you have local changes or not.
+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:
-Line 44:
+Line 104:
-{{{
  git fetch -f origin
  git checkout origin
  git branch -f master origin
  git checkout master
}}}
+    {{{
git fetch
git reset --hard origin/master
}}}
-Line 53:
+Line 110:
-{{{
  # Save away local commits
  git log origin..HEAD | awk '/^commit/{print $2}' | tac > local-commits
  git branch new-head
  git checkout new-head
  # This will stop on first error. Cleaning up failures is an excercize for the user
  for cmt in `cat local-commits`; do git-cherry-pick $cmt || exit; done
  git branch -f master new-head
  git checkout master
  git branch -D new-head
}}}
+    {{{
git fetch
git rebase --onto origin/master origin/master@{1}
}}}
-Line 66:
+Line 117:
-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 [mailto:kernel-team@lists.ubuntu.com 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 [mailto:kernel-team@lists.ubuntu.com kernel-team] mailing list.
+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 [[mailto:kernel-team@lists.ubuntu.com|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 [[mailto:kernel-team@lists.ubuntu.com|kernel-team]] mailing list.
-Line 71:
+Line 122:
-In ''debian/commit-templates/'' there are several templates that must be used when commiting 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
+In ''debian/commit-templates/'' there are several templates that must 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
-Line 86:
+Line 137:
-  Signed-off-by: Joe Cool Hacker <jch@reet.com>
+  Signed-off-by: Joe Cool Hacker <jch@ubuntu.com>
-Line 98:
+Line 149:
-If you are creating a new file, it is helpful to run it through ''cleanfile'' and/or ''Linent'' before creating a patch[[BR]]
If you have generated a patch, it helps running it through ''checkpatch.pl'' and ''cleanpatch'' if necessary[[BR]]
+If you are creating a new file, it is helpful to run it through ''cleanfile'' and/or ''Linent'' before creating a patch<<BR>>
If you have generated a patch, it helps running it through ''checkpatch.pl'' and ''cleanpatch'' if necessary<<BR>>
-Line 110:
+Line 161:
-git-clone -l -n -s /srv/kernel.ubuntu.com/git/ubuntu/ubuntu-hardy.git
vi ubuntu-hardy/.git/description
+git clone -l -n -s /srv/kernel.ubuntu.com/git/ubuntu/ubuntu-jaunty.git
vi ubuntu-jaunty/.git/description
-Line 113:
+Line 164:
-mv ubuntu-hardy/.git /srv/kernel.ubuntu.com/git/<user>/my-git-tree.git
+mv ubuntu-jaunty/.git /srv/kernel.ubuntu.com/git/<user>/my-git-tree.git
-Line 118:
+Line 169:
-Now you need to run ''git-update-server-info'' in your tree so that it is available over http transport
+Now you need to run ''git update-server-info'' in your tree so that it is available over http transport
-Line 121:
+Line 172:
-git-update-server-info
+git update-server-info
-Line 128:
+Line 179:
-git clone git://kernel.ubuntu.com/ubuntu/ubuntu-hardy.git my-tree
+git clone git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git my-tree
-Line 133:
+Line 184:
-Suggested method for keeping this tree synced with the ubuntu tree, instead of git-pull, is to do:
+Suggested method for keeping this tree synced with the ubuntu tree, instead of git pull, is to do:
-Line 137:
+Line 188:
-git-fetch origin
git-rebase origin
+git fetch origin
git rebase origin
-Line 143:
+Line 194:
+= 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.
-Line 144:
+Line 233:
-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/tutorial.html.
+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.
-Line 147:
+Line 238:
-CategoryKernel
+CategoryKernel CategoryDocumentation

Ubuntu Wiki