KernelGitGuide
8673
Comment:
|
← Revision 73 as of 2010-06-28 23:55:41 ⇥
7080
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
= Summary = 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. |
#redirect Kernel/Dev/KernelGitGuide ## page was renamed from KernelGitGuide |
Line 4: | Line 4: |
= Where is it? = | 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 6: | Line 6: |
http://kernel.ubuntu.com/ | |
Line 8: | Line 7: |
= Current GIT Trees = | == Current GIT Trees == |
Line 10: | Line 9: |
* jaunty: git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git * intrepid: git://kernel.ubuntu.com/ubuntu/ubuntu-intrepid.git * 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 |
All of the current live Ubuntu kernel repositories are at the URL below: |
Line 18: | Line 11: |
(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 |
{{{ http://kernel.ubuntu.com/git-repos/ |
Line 27: | Line 15: |
'''Use apt-get because other tools such as aptitude will autoremove packages that have no install links.''' | There is a tree for each of the currently supported releases as well as any open development and upcoming releases: |
Line 29: | Line 17: |
'''Note that the `git` package is an entirely different tool which will not do what you want.''' | || 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 || |
Line 31: | Line 24: |
= Getting the Ubuntu Linux kernel repo = 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-jaunty.git ubuntu-jaunty }}} |
|
Line 37: | Line 25: |
This will take some time depending on your connection. There's around 220 MiB of data to download currently (and this always increases). If you already have an upstream kernel tree, you can use the --reference option to avoid downloading redundant objects: {{{ git clone --reference linux-2.6/ git://kernel.ubuntu.com/ubuntu/ubuntu-jaunty.git }}} This will reduce the amount of data to download to around 6 MiB. |
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. |
Line 43: | Line 27: |
Change into the directory: | To find out what else is available try browsing http://kernel.ubuntu.com/git and searching for ubuntu). |
Line 45: | Line 30: |
{{{ cd ubuntu-jaunty }}} |
<<Include(Kernel/Action/InstallGit)>> |
Line 49: | Line 32: |
Get a copy of the kernel version you want to work on. To determine which the latest official release is: | <<Include(Kernel/Action/GitTheSource)>> |
Line 51: | Line 34: |
{{{ git tag | grep Ubuntu* }}} |
== Maintaining local changes == |
Line 55: | Line 36: |
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, this would be a correct choice: {{{ 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 pull }}} '''** 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 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 80: | Line 43: |
{{{ git fetch -f origin git checkout origin git branch -f master origin git checkout master |
{{{ git fetch git reset --hard origin/master |
Line 88: | Line 49: |
{{{ # Save away local commits git rev-list --reverse origin..HEAD > local-commits git branch new-head origin git checkout new-head # This will stop on first error. Cleaning up failures is an exercise for the user for cmt in `cat local-commits`; do git-cherry-pick $cmt || break; done git branch -f master new-head git checkout master git branch -D new-head }}} Alternatively, you can accomplish the same thing in the following way. '''No Local Changes''' {{{ git fetch -f origin git reset --hard origin }}} '''Preserve Local Changes''' {{{ # save current state in case something goes wrong git branch -f save # save the state you based your changes on # this needs to be done *before* the fetch git branch -f old-head origin git fetch -f # apply your local changes on top of the new upstream head git rebase --onto origin old-head # remove temporary branch git branch -d old-head |
{{{ git fetch git rebase --onto origin/master origin/master@{1} |
Line 123: | Line 55: |
= 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 [[mailto:kernel-team@lists.ubuntu.com|kernel-team]] mailing list. |
== 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 [[mailto:kernel-team@lists.ubuntu.com|kernel-team]] mailing list. |
Line 126: | Line 58: |
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. | 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 128: | Line 60: |
= Commit templates = 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 }}} Note that the -e (edit) option must follow the -F option, else git will not let you edit the commit-template before committing. |
<<Include(Kernel/Action/CommitTemplates)>> |
Line 135: | Line 62: |
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 = |
== Patch acceptance criteria == |
Line 160: | Line 75: |
= Developers with access to kernel.ubuntu.com = | == Developers with access to kernel.ubuntu.com == |
Line 167: | Line 82: |
{{{ git-clone -l -n -s /srv/kernel.ubuntu.com/git/ubuntu/ubuntu-jaunty.git |
{{{ git clone -l -n -s /srv/kernel.ubuntu.com/git/ubuntu/ubuntu-jaunty.git |
Line 176: | Line 91: |
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 179: | Line 94: |
git-update-server-info | git update-server-info |
Line 185: | Line 100: |
{{{ | {{{ |
Line 187: | Line 102: |
*do work* git send-pack kernel.ubuntu.com:/srv/kernel.ubuntu.com/git/<user>/my-git-tree.git master |
git remote add zinc ssh://kernel.ubuntu.com/srv/kernel.ubuntu.com/git/<user>/my-git-tree.git <do work> git push zinc maser |
Line 191: | Line 107: |
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 193: | Line 109: |
{{{ | {{{ |
Line 195: | Line 111: |
git-fetch origin git-rebase origin |
git fetch origin git rebase origin |
Line 203: | Line 119: |
{{{ | {{{ |
Line 208: | Line 124: |
== .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 211: | Line 158: |
For a list of quick git recipes and examples, see KernelTeam/GitCheatSheet. |
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 install git
Obtaining the kernel sources for an Ubuntu release using git
The source for each release is maintained in its own git repository on Launchpad.
The git repository is listed in the Vcs-Git: header in the source package and is of the following form:
git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/<source package>/+git/<series>
For example, the standard Jammy kernel is available at:
git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy
There is a tree for each of the currently supported releases as well as any open development and upcoming releases. For example:
focal
git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/focal
jammy
git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy
noble
git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/noble
Replace your intended Ubuntu series in the above URL, and pull the source for the kernels you need.
The distro kernel is always on the master branch in these repositories. Each release also has a master-next branch containing the commits that will go into the master branch and become the next SRU release for that series.
A number of releases also have other source packages which represent other related but divergent kernels for other purposes. For example, there is a specialized AWS kernel available in the linux-aws source package. (Previously these sorts of things were done in Topic Branches and some older kernels and projects still use them.)
If you cannot use the git protocol (perhaps because of a firewall), you can use the slower https protocol. For example:
Obtaining a copy
To obtain a local copy you can simply git clone the repository for the release you are interested in. The git command is part of the git package.
For example to obtain the Jammy tree:
git clone git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy
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, and use it as a reference. Note that once these two trees are tied together you cannot simply delete or move the virgin Linus tree without manually updating .git/objects/info/alternates in your Ubuntu kernel tree:
git clone git://kernel.ubuntu.com/ubuntu/linux.git git clone --reference linux git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy git clone --reference linux git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/noble
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.
If you are an advanced git user, you can also add each Ubuntu series as a remote so that you can have all kernel series you need in a single directory. For example,
git remote add jammy git://git.launchpad.net/~ubuntu-kernel/ubuntu/+source/linux/+git/jammy git fetch jammy git checkout -b jammy --track jammy/master git checkout -b jammy-next --track jammy/master-next
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, use the git tag command below:
$ git tag -l Ubuntu-* Ubuntu-5.4.0-47.51 Ubuntu-5.4.0-48.52 Ubuntu-5.4.0-49.53 Ubuntu-5.4.0-51.56 Ubuntu-5.4.0-52.57 ...
To look at the Ubuntu-5.4.0-52.57 version you can simply checkout a new branch pointing to that version:
git checkout -b temp Ubuntu-5.4.0-52.57
You may then manipulate the release - for example, by 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.
KernelTeam/KernelGitGuide (last edited 2010-06-28 23:55:41 by c-76-105-148-120)