Differences between revisions 24 and 25
Revision 24 as of 2007-10-22 13:41:07
Size: 8982
Editor: ?JulienCristau
Comment: fix link to keithp's blog entry
Revision 25 as of 2007-11-06 21:39:19
Size: 10658
Editor: BriceGoglin
Comment: improve the git tutorial for KiBi
Deletions are marked like this. Additions are marked like this.
Line 21: Line 21:
=== Here's a basic tutorial: === === Basic tutorial ===
Line 31: Line 31:
    * 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 by running `git checkout upstream-unstable`. 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. If they use svn, you may want to consider using git-svn. 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. Then checkout the debian-unstable branch using `git checkout debian-unstable`. Pull the updated version from upstream-unstable using `git pull . upstream-unstable`. Update the packaging, test, and commit your changes. If you're ready to release this version, run `git tag -a yourtagname` to create a tag. Then run `git checkout upstream-unstable` and push your changes to alioth using "git push origin". Then run `git checkout debian-unstable` and push those changes using `git push origin`. You should include the `--tags` switch in your push of the debian-unstable branch if you made a new tag. === 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
}}}

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 to setup the "upstream" remote in your git config. The `.git/config` file should contain something like:
{{{
   [remote "upstream"]
        url = git://git.freedesktop.org/git/xorg/driver/xf86-video-ati
        fetch = +refs/heads/*:refs/remotes/upstream/*
}}}

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

Update the packaging, test, and commit your changes. If you're ready to release this version, you should create a tag:
{{{
   git tag -a yourtagname
}}}
Note that some external scripts like [http://people.debian.org/~jcristau/debgittag debgittag] 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 do 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.

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

  • Run git clone http://git.debian.org/git/pkg-xorg/doc-hackers.git/ for anonymous checkout. Run git clone ssh://alioth.debian.org/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 git+ssh://yourusername@alioth.debian.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

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 to setup the "upstream" remote in your git config. The .git/config file should contain something like:

   [remote "upstream"]
        url = git://git.freedesktop.org/git/xorg/driver/xf86-video-ati
        fetch = +refs/heads/*:refs/remotes/upstream/*

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

Update the packaging, test, and commit your changes. If you're ready to release this version, you should create a tag:

   git tag -a yourtagname

Note that some external scripts like [http://people.debian.org/~jcristau/debgittag debgittag] 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 do 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

  • If you have any questions, feel free to pop in to #debian-x on oftc, or ask on debian-x@lists.debian.org.

  • For non-XSF-specific help with Git, try the official Git IRC channel, #git on Freenode, or ask on the Git mailing list, git@vger.kernel.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.