This section describes how to create a git repository for a package as well as convert from the svn layout.

Global git Configuration

First, you'll need to setup your global git configiration file (~/.gitconfig) with your name and email address. This is so commit messages show up with your name and email address automatically.

$ git config --global "<your name>"
$ git config --global "<your email address>"

Creating a git repository

These steps involve creating a brand new git repository for your package. If you are converting from svn, please see the "Converting from svn repository" page.

Here's a simple way to create a git repository using the supplied setup-repository script in the /git/pkg-games directory on the alioth servers.

$ ssh <username>
$ cd /git/pkg-games
$ ./setup-repository <package> '<package description>'

The script will handle everything for you so for automatic setup nothing else is needed.

If you want to manually create the repository, the rest of this section describes how to do so.

$ ssh <username>
$ cd /git/pkg-games
$ mkdir <package>.git
$ cd <package>.git
$ git --bare init --shared

Now edit the 'description' file in the directory you just created to one that is appropriate for the package.

$ echo "Packaging for <package>" >description

Let's also enable the use of 'hooks/post-update'.

$ mv hooks/post-update.sample hooks/post-update

The following will enable the games team to receive commit mails and irc notifications about commits. Please do the following.

$ git config --add hooks.mailinglist ""
$ git config --add hooks.cia-project debian-pkg-games
$ cat >hooks/post-receive <<END
exec /home/groups/pkg-games/bin/post-receive
$ chmod a+x hooks/post-receive

Please see the documentation about mr below, and add the new repository to list of games team repositories in the .mrconfig file. /

Uploading a package to the repository

Now let's import the package into a git repository. This is easy using 'gbp import-dsc' from the 'git-buildpackage' package. This is done from your local machine of course.

$ gbp import-dsc --pristine-tar <package>.dsc

(The --pristine-tar option is optional; if you have pristine-tar installed this will store enough information in the git repository to reproduce the pristine upstream tarball later.)

A directory with the name of the source package should have been made. Change into that directory.

$ cd <package>

Ensure the tags that are created reflect if a package has been released. git buildpackage creates tags for the debian branch and the upstream branch. If the tag created for the debian branch reflects an unreleased version, you'll have to delete that "debian" tag.

$ git tag -l | sort -V
$ git tag -d 'debian/<unreleased version>'

Push the repository up to the repository on alioth:

$ git remote add alioth git+ssh://<username><package>.git
$ git push alioth master
$ git push alioth upstream
$ git push alioth pristine-tar
$ git push alioth --tags

(Again the pristine-tar step is optional.)

And, finally, add a new section for the new repo in the .mrconfig file from from our SVN trunk and commit it. Note that the .mrconfig file now lives outside of the trunk in the very root of the pkg-games SVN. You might also want to do this update by hand in order to keep the stanzas in .mrconfig in alphabetical order.

$ (echo "[<package>]" ; \
echo "checkout = git clone git://<package>.git"; \
echo) >> /path/to/SVN/checkout/mrconfig/.mrconfig
$ svn ci -m "Add <package>'s git repo to the .mrconfig file" /path/to/SVN/checkout/mrconfig/.mrconfig

Accessing a repository

To get a repository, do the following.

$ git clone git+ssh://<username><package>.git

You can also enjoy read-only access by using the following.

$ git clone git://<package>.git
$ git clone<package>.git

It is generally a good idea to track certain branches that have been pushed (namely 'upstream' and 'pristine-tar'). To track them, do the following.

$ git checkout -b upstream origin/upstream
$ git checkout -b pristine-tar origin/pristine-tar #Do this if a pristine-tar branch was pushed

If you want to track more, see what branches are available.

$ git branch -r

You might see branches labelled 'tags/<some_version>'. These are really the "remotes" objects of the tags that were imported into the git repository when it was converted from svn. Although you can track these as well, it's better if you do a git checkout of the specific tags instead as follows.

$ git checkout remotes/tags/<some_tag>

See the page Converting from svn repository for more details.

To view a summary of the repository on your favorite web browser, go to the following address.<package>.git


You can use the 'git-buildpackage' command:

 $ git-buildpackage

Sometimes the upstream build system will remove files from the source archive. You can ignore this:

 $ git-buildpackage --git-ignore-new

If you use ccache, you'll note that 'git-buildpackage' calls 'debuild' which itself resets the CC, CXX and PATH environment variables. Normally you use the --preserve-envvar=PATH or --prepend-path=/usr/local/bin options, but debuild ignores them unless they are specified first and 'git-buildpackage' doesn't pass them first (TODO: bugreport this). You can work-around this by calling debuild directly:

 debuild --prepend-path=/usr/local/bin -i'\.git' -I.git

Alternatively check the --git-builder option.

Committing changes

To commit a change, first commit into your local repository.

$ git commit -m "<some comment>"

You could also do a commit of all files that were changed using the '-a' option.

$ git commit -a -m "<some comment>"

Push your changes.

$ git push #If you cloned the repository
$ git push alioth #If you created the repository using the above example


To keep updated simply do the following

$ git pull #If you cloned the repository
$ git pull alioth #If you created the repository using the above exmple


To tag a release, you could build it using 'git-buildpackage' with the '--git-tag' option.

$ git buildpackage --git-tag --git-pristine-tar

You can also tag a release without rebuilding by supplying a different build command using the --git-builder option. In this case, we'll just perform a cleanup.

$ git buildpackage --git-tag --git-pristine-tar --git-builder='fakeroot debian/rules clean'

(As usual, the --git-pristine-tar bit is optional, but it will allow git-buildpackage to extract the pristine .orig.tar.gz.)

You could also manually tag the package. Ensure that you are in the correct branch (should be 'master').

$ git checkout master
$ git tag debian/<revision> -m "Debian release <revision>" #Please use this format

To tag an earlier revision, you'll need to find out it's commit object.

$ git rev-list --pretty --since="1 month" --all #'1 month' is just an example of course

Make note of the commit object and switch to that commit using git checkout. Then tag it and switch back to master.

$ git checkout <commit object>
$ git buildpackage --git-tag --git-pristine-tar --git-builder='fakeroot debian/rules clean' --git-ignore-new
$ git checkout master

Finally, push the tags

$ git push --tags

Using pristine-tar

You can manually use the pristine-tar command to create a pristine-tar branch for generating the orig tarball later. This is useful in case you ommitted using the --git-pristine-tar option when running the git buildpackage tools.

To create a pristine-tar branch, simply do the following.

pristine-tar commit <path_to_orig_tarball> upstream/<package_version>

This assumes you already imported the orig tarball to the git repository. upstream/<package_version> is the tag that was created when the orig tarball was imported using git import-orig. Make sure to specify the tag object.

Then push the new 'pristine-tar' branch.

git push origin pristine-tar #If you cloned the repository
git push alioth pristine-tar #If you created the repository

Generating patches

Here's one way to work with a package to generate patches.

First, create a local branch dedicated for fixes from the master branch and switch to that branch.

$ git checkout master
$ git checkout -b my-fixes

Next, do whatever changes that need to be done and commit them to your "my-fixes" branches. Once you're done with whatever fixes go back to the master branch and generate your patches using git diff.

$ git diff master my-fixes >debian/patches/<some_patch>.patch

Alternatively, you can specify which files to create patches for.

$ git diff master my-fixes -- <path ...> >debian/patches/<some_patch.patch>

If you're using quilt, the entry in the series file should look something like this.

<some_patch>.patch -p1

git format-patch

If you're making major changes to a package, you might want to consider using git format-patch to generate patches. Basically, instead of using git diff to generate the patches, use git format-patch.

$ git format-patch -o debian/patches master my-fixes

Reverting changes while building

There are cases when files have been changed when a package has been built and performing a "clean" operation does not revert all changes back. Here's a command that can be done to revert changes made in such cases. Of course, make sure you are in the master branch or whatever branch you use to commit changes before running this command.

$ git checkout .

It is also possible to revert an individual file by specifying a path argument to git checkout

$ git checkout path/to/file/to/revert

In this case no branch switching occurs and the specified file is reverted to its committed state. Say you have made a commit to your local repository but made a mistake with the commit message, or your email was not set correctly, or you just wish you had not done that commit, git reset is again your friend and you can roll back to be in sync with the last git pull with :-

Reverting commits and files scheduled for commit

If you are working on a package mistakes may be made. If you have files scheduled for commit that were added with git add or git rm and you do not want to commit these files anymore (or want to split the commit in to smaller commits etc), this action can be reverted with :-

$ git reset HEAD <file>

This just removes the specified file from the staging list to be committed on the next commit. If you do not specify a file all files added with git add or git rm will be unstaged.

If you have just committed some changes to your local git tree but want to undo the commit (but not loose changes to your files):-

$ git reset --soft HEAD^

Will remove your commit, leave your files unchanged and back in the state added/removed but not committed.

If you wish to roll back your commit and changes then do :-

$ git reset --hard HEAD~1

This rolls back the head pointer by 1 commit hence the ~1 and permanently looses the changes, DO NOT do this if you have done a git push or the repository will be out of sync and breakage may occur.

Adding a new upstream release

If you are working with an upstream and/or pristine-tar branch then if upstream makes a new release you will want to import. Firstly ensure your tree is clean and all committed and pushed/pulled. Ensure you are on the master branch and that you have the upstream (and if required) the pristine-tar branches created (if not create them with git branch).

$ git checkout master

Next import the upstream tarball, if you are using pristine-tar then specify that option, and if you need to specify the version use the -u option.

$ gbp import-orig [--pristine-tar] [-u version] /path/to/upstream-version.tar.gz

This will do the following actions :-

Afterwards you will need to manually bump the Debian version using 'dch' or 'git-dch'.

Possible problems

git import-orig dch error

When using git import-orig, there is a chance you'll receive an error similar to this one.

dch: fatal error at line 963:
New version specified (1.4.8.dfsg1-1) is less than
the current version number (1.4.8.dfsg1-1)!  Use -b to force.
dch returned 25
Dch failed.
Import of ../../build-area/ogre_1.4.8.dfsg1.orig.tar.gz failed

This will happen if you omit the --no-dch option while running git import-orig and the version in the changelog is at the version of the orig tarball that's being imported.

git import-orig pristine-tar error

It's possible you may receive an error such as this.

pristine-tar: more than one ref matches "upstream":
5f4736c83ea06e9b479a35f25d997b73713306b9 refs/heads/upstream
a8c20d823bc28bb8f6d127e301390bed06e49169 refs/remotes/origin/upstream
/usr/bin/pristine-tar returned 255
Couldn't run '/usr/bin/pristine-tar'

This is caused by git import-orig (or any of the git-buildpackage tools) supplying the parameter "upstream" to use when running pristine-tar commit instead of using the default refs/heads/upstream or supplying a tag object instead and you cloned a git repository. You will have to omit the --pristine-tar option from the git-buildpackage tools and use pristine-tar manually. See 481806.