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.

Basic tutorial

Updating a package to a new upstream version

   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:

   git branch

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

   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.

   git log --pretty=format:'- %h... %s%n' remotes/origin/upstream-experimental.. | fold -s -w 74 | sed -e 's/^\([^-]\)/      \1/' -e 's/^- /    - /' -e '/^$/d'

   git tag -a yourtagname

Note that some external scripts like xsf-tag may generate a nice tag automatically for you.

   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.

More Information