XSF uses git
The XSF source code repositories are hosted at git.debian.org. Access is via the pkg-xorg project on Alioth. You can view them on http://git.debian.org.
Git Archive Policy
We will have two basic classes of branches. 'upstream*' which will hold our local copy of the upstream version of interest, and 'debian*' which will hold the debian directory and the packaging information in addition to the full source tree from upstream. These will essentially act as topic branches. Changes to the code we get from upstream will go in to the upstream* branches. Changes to the packaging will go to the debian* branches. Patches to the upstream source may be done originally in the debian* branch and pushed or pulled to the upstream* branch, but since we'll be pulling our changes from freedesktop.org most of the time, this shouldn't be a problem. The goal of these branches is to cleanly separate work on the code and the packaging so that we can cleanly pull specific sets of changes from a single branch. (See http://lists.debian.org/debian-x/2007/01/msg00253.html for a little more.)
Each branch class will have sub-branches. For example, there will be 'debian-unstable' which is for the work going on in unstable, and 'debian-experimental' for work going in to experimental. There will be corresponding branches for the upstream branch class. In addition, there will be branches for releases (-etch, -lenny, etc) for targeted updates to stable or testing releases. We will use the codenames for those branches rather than version numbers. Note that there is no designated master branch, although you may want to set one up locally. Additional topic-specific branches may also be created if desired, although you are encouraged to create these in your home directory on alioth or somewhere similar, rather than in the mainline repositories.
Changes to the packaging will be made in the debian branches. The upstream branch will correspond to the upstream release we are shipping. The upstream branch will be updated directly from pulling in the repositories at freedesktop.org, and then pushed to alioth. The upstream branch will not be kept in direct sync with the latest HEAD from freedesktop.org, but instead it will correspond to what we will be packaging and shipping in the Debian archive.
Some sets of packages, such as xbase-clients, are bundles of several individual packages from upstream. Because these apps are relatively stable and not undergoing changes, and because git does not currently support moving the sources in to a subdirectory (such as a per-app subdirectory) and then merging, we will instead simply copy and commit the upstream code from release tarballs directly in to the debian branches of interest. If a bundled app does see a great deal of upstream work, it should be split out and made in to a proper git repository so that we can have its full history available.
Changes pulled from upstream trees may be cherry-picked in to the upstream branch, and then pulled to the debian branch. Changes that will be applied upstream may be directly applied to the master branch as well. Changes that are meant to be preserved across upstream releases and not pushed upstream, such as changes required for driver DFSG-compliance, will be kept in the debian branch in an external patching system that will be collectively used by the whole team. Currently, this is quilt, although we are evaluating stgit.
The goal of this is to provide flexibility and harness the full power of git. If you want to work on bleeding edge code, and want it to be packaged, you can merely pull in the debian branch of interest in to your code. In addition, it allows anyone to simply clone the repository and build the package from the master branch without fetching the code from the upstream repositories as well. Finally, it allows us to cherry-pick changes from upstream without putting them in to quilt or stgit, which requires extra labor and isn't as useful if the code does not have to be an extra patch across new upstream versions.
Currently, the Debian Xorg packages use xsfbs, which is a collection of useful make and shell functions. There will be a single xsfbs repository. Each package that uses xsfbs will pull from this single repository. We can not currently guarantee that every package will use an up to date xsfbs pull (i.e. there is no git equivalent of svn:externals) so it is up to the maintainers to ensure that the packages carry an up to date version of xsfbs.
Run git clone http://git.debian.org/git/pkg-xorg/doc-hackers.git/ for anonymous checkout. Run git clone ssh://email@example.com/git/pkg-xorg/doc-hackers.git/ if you are a member of the pkg-xorg project on Alioth.
Pull the xorg-docs with git clone http://git.debian.org/git/pkg-xorg/doc/xorg-docs.git for anonymous checkout. Use git clone ssh://firstname.lastname@example.org/git/pkg-xorg/doc/xorg-docs.git if you are a member of the alioth project.
If you want to edit the Debian packaging that's destined for unstable, check out the Debian branch by running git checkout debian-unstable. Make your edits, then run git commit -a. This will commit all changes to your local repository. If you want to commit only specific changes, see the git documentation about the index file. Running git commit will launch your editor, and allow you to enter a commit message. Enter it, and save and quit. If you want to confirm that you your change was committed, run git log or git diff HEAD^ HEAD. At this point, you've only committed your change locally. You still need to push it to the alioth repository. A nice feature of git is that you can commit several changes locally and then push them remotely all in one batch when you're ready. Assuming you've made all your commits now, simply run git push origin. origin is the name of the file in .git/remotes that points to alioth (have a look at it yourself, it's just plain text and is very understandable). You should see git commit your changes to the remote repo.
Updating a package to a new upstream version
- If you want to update the package to a new upstream version in a package that you plan to upload to unstable, check out the upstream-unstable branch:
git checkout upstream-unstable
If you do not have a local branch upstream-unstable you can checkout a remote branch using:
git checkout -b upstream-unstable origin/upstream-unstable
You can see local branches with:
There shouldn't be a debian directory in this branch. Update your sources. If you're updating from an upstream that uses git (like X.org) you should merge the specific tagged version that you want in to the upstream-unstable branch:
git fetch upstream git pull . tag foobar
To get the above to work, you need add the "upstream" remote once:
git remote add upstream git://anongit.freedesktop.org/git/xorg/driver/xf86-video-ati
Then checkout the debian-unstable branch:
git checkout debian-unstable
Pull the updated version from upstream-unstable branch into the current branch (debian-unstable):
git pull . upstream-unstable
- If the old and new upstream releases are on separate branches, the above will fail with merge conflicts. Instead, first checkout the new upstream version:
git checkout -b debian-unstable-new new-tag
Then pretend to merge in the old upstream:
git merge -s ours upstream-unstable
And finally, pull in the packaging with:
git merge debian-unstable
Then reset the upstream-unstable branch to the new release, and update debian-unstable to the debian-unstable-new branch containing the merge.
- Update the packaging, test, and commit your changes. If you are packaging a snapshot of a repository, you can use the following snippet to generate a suitable changelog sub-entries from the upstream-experimental branch:
git log --pretty=format:'- %h... %s%n' remotes/origin/upstream-experimental.. | fold -s -w 74 | sed -e 's/^\([^-]\)/ \1/' -e 's/^- / - /' -e '/^$/d'
- If you're ready to release this version, you should create a tag:
git tag -a yourtagname
Note that some external scripts like xsf-tag may generate a nice tag automatically for you.
- Finally, push both branches changes to alioth, including the new tag:
git push origin upstream-unstable git push origin debian-unstable git push origin yourtagname
If you are working in experimental, you want to replace upstream-unstable and debian-unstable with upstream-experimental and debian-experimental everywhere above:
You probably want to sync the experimental branches to the unstable ones before doing any change, for instance because the latter contain a more recent upstream release:
git checkout debian-experimental git pull . debian-unstable git checkout upstream-experimental git pull . upstream-unstable
On the contrary, if some work has been done in experimental and you want to upload to unstable, you should probably pull the changes from experimental into the unstable branches:
git checkout debian-unstable git pull . debian-experimental git checkout upstream-unstable git pull . upstream-experimental
Updating when upstream does not use git
If the upstream maintainer of the package does not use git, you have to manually fetch the new version in git. If you only have a tarball, just unpack it and copy it over, making sure you use git add to add any new files. Commit these changes:
git add newfile1 newfile2 ... git commit -a -m "my message describing the new upstream that I updated to"
If upstream uses svn, you may want to consider using git-svn to make things easier.
Git is incredibly well documented. Here's a few places to look when you're confused or curious.
- The git manpages. There's one for every command. The manpage for the "git foo" command can be reached with "man git-foo" or "git-foo --help".
- The git documentation. This is in the git-doc package. You really want to read a lot of this.
The git wiki located at http://git.or.cz/gitwiki
Keith Packard's blog entry on why he chose git for X.org: http://keithp.com/blog/Repository_Formats_Matter/
This article has a fair amount of flamebait, but technically it's a very good overview, particularly if you're coming from SVN or SVK: http://utsl.gen.nz/talks/git-svn/intro.html
Linus gave a tech talk at Google on git, which goes in to good strategies for making use of the distributed nature of git: http://www.youtube.com/watch?v=4XpnKHJAok8
If you have any questions, feel free to pop in to #debian-x on oftc, or ask on email@example.com.
For non-XSF-specific help with Git, try the official Git IRC channel, #git on Freenode, or ask on the Git mailing list, firstname.lastname@example.org
XStrikeForce/svn-usage describes our use of subversion, which we used prior to switching to git. That repository is still accessible and contains the monolithic source trees which were not converted to git. However, writing to it should only be done by those making stable security updates to the monolithic packages.