KernelGitGuide
1331
Comment: New page describing our kernel git repo
|
8068
|
Deletions are marked like this. | Additions are marked like this. |
Line 2: | Line 2: |
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. | 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 4: | Line 4: |
= Getting GIT = To obtain the git binaries, please go to [http://www.kernel.org/pub/software/scm/git-core kernel.org] and download the latest source. Folow the build instructions included, and make sure to install them in a location in your PATH. |
= Current GIT Trees = All of the current live Ubuntu kernel repositories are at the URL below: {{{ http://kernel.ubuntu.com/git/ }}} There is a tree for each of the currently supported releases as well as any open development and upcoming releases: || karmic || git://kernel.ubuntu.com/ubuntu/ubuntu-karmic.git || || 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 || 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.''' |
Line 8: | Line 38: |
The Ubuntu Linux kernel git repository is located at rsync://rsync.kernel.org/pub/scm/linux/kernel/git/bcollins/ubuntu-2.6.git. To download a local copy of the repo, use this command: {{{ git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/bcollins/ubuntu-2.6.git ubuntu-2.6 |
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}}} This will take some time depending on your connection. There is several hundred megabytes of data to download. 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. Change into the directory: {{{ cd ubuntu-jaunty}}} By default your 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 | grep 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 |
Line 13: | Line 99: |
This will take some time depending on your connection. There's around 110Megs of data to download currently (and this always increases). Once this is complete, you can keep your tree up-to-date by running this command: {{{ git pull |
'''Preserve Local Changes''' {{{ git fetch git rebase --onto origin/master origin/master@{1} |
Line 20: | Line 105: |
= 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. 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. = 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. 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<<BR>> If you have generated a patch, it helps running it through ''checkpatch.pl'' and ''cleanpatch'' if necessary<<BR>> 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. |
|
Line 21: | Line 192: |
Please read the documentation included with the git source for more details on using git. | 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. |
Line 23: | Line 194: |
If you are an Ubuntu kernel developer with access to people.ubuntu.com, you can follow the KernelDeveloperGuide to get more information. | |
Line 25: | Line 195: |
CategoryKernel | CategoryKernel CategoryDocumentation |
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/
There is a tree for each of the currently supported releases as well as any open development and upcoming releases:
karmic
git://kernel.ubuntu.com/ubuntu/ubuntu-karmic.git
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
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. 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. 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.
Change into the directory:
cd ubuntu-jaunty
By default your 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 | grep 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 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.
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.
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.
KernelTeam/KernelGitGuide (last edited 2010-06-28 23:55:41 by c-76-105-148-120)