Differences between revisions 32 and 33
Revision 32 as of 2008-05-18 17:24:59
Size: 13548
Editor: ?AndresMejia
Comment:
Revision 33 as of 2008-05-18 18:06:46
Size: 14361
Editor: ?AndresMejia
Comment: Add another possible problem
Deletions are marked like this. Additions are marked like this.
Line 326: Line 326:
=== 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 [http://bugs.debian.org/481806].

?TableOfContents

Git

The repositories for the packaging in git is stored in a different manner than they are under svn. Each package has its own git repository (and thus its own directory) under the /git/pkg-games directory on the alioth servers.

This guide assumes that you are uploading the packaging files for a package for the first time.

A separate section will describe how to import the packaging that was stored in the svn repository in the future.

Environment variables

These are some environment variables that git uses when you commit changes. It's best to set these environment variables so that git doesn't rely on your system's username or hostname. Place this snippet in your ~/.bashrc configuration file.

# Git variables
export GIT_AUTHOR_NAME='<your name>'
export GIT_AUTHOR_EMAIL='<your email>'
export GIT_COMMITTER_NAME='<your name>'
export GIT_COMMITTER_EMAIL='<your email>'

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" section below.

First, create a repository in the /git/pkg-games directory on the alioth servers.

$ ssh <username>@git.debian.org
$ 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'.

$ chmod a+x 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 "pkg-games-commits@lists.alioth.debian.org"
$ git-config --add hooks.cia-project debian-pkg-games
$ cat >hooks/post-receive <<END
#!/bin/sh
exec /usr/local/bin/git-commit-notice
END
$ chmod a+x hooks/post-receive

Now we're done creating a repository for the package. You could also use the 'setup-repository' script that's in the pkg-games directory. That script is really a symlink to the script that's used in the collab-maint directory. This however will not setup the hook scripts.

./setup-repository <package> '<package description>'

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 'git-import-dsc' from the 'git-buildpackage' package. This is done from your local machine of course.

$ git-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
$ git-tag -d 'debian/<unreleased version>'

Finally, push the repository up to the repository on alioth.

$ git-remote add alioth git+ssh://<username>@git.debian.org/git/pkg-games/<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.)

Accessing a repository

To get a repository, do the following.

$ git-clone git+ssh://<username>@git.debian.org/git/pkg-games/<package>.git

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

$ git-clone git://git.debian.org/git/pkg-games/<package>.git
$ git-clone http://git.debian.org/git/pkg-games/<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 section "Converting from svn repository" below for more details.

To view a summary of the repository on your favourite web browser, go to the following address.

http://git.debian.org/?p=pkg-games/<package>.git

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

Updating

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

Tagging

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

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

(As usual, the --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, then tag that object.

$ git-rev-list --pretty --since="1 month" --all #'1 month' is just an example of course
$ git-tag debian/<revision> <commit object> -m "Debian release <revision>"

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

Converting from svn repository

To convert from the svn repository, first setup the git repository on the alioth servers as described above. Afterwards, do the following on your local machine.

$ mkdir <package>
$ cd <package>
$ git-svn init --no-metadata \
    --trunk svn://svn.debian.org/svn/pkg-games/packages/trunk/<package> \
    --branches svn://svn.debian.org/svn/pkg-games/packages/branches/<package> \
    --tags svn://svn.debian.org/svn/pkg-games/packages/tags/<package>
$ git-svn fetch

Notes:

  • Doing git-svn fetch will take some time depending on how many commits were done in the svn repository.

  • If the svn repository doesn't contain a branches or tags section for the package, then you can omit the --branches or --tags options.

After fetching from the svn repository, it's now time to import the contents of the orig source.

$ git-symbolic-ref HEAD refs/heads/upstream
$ git-rm --cached -r .
$ git-commit --allow-empty -m 'initial upstream branch'
$ git-checkout -f master
$ git-merge upstream
$ git-import-orig --pristine-tar --no-dch <path_to_orig_tarball>

Note: Using the --pristine-tar option is optional.

After this step, push the contents of your local repository.

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

Note: Using a 'pristine-tar' branch is created only if you used the --pristine-tar option above.

This step here is a way to push the tags and branches that were imported from svn (an explanation about this is below). Do this to push all tags and branches that were imported.

$ for REMOTES in `find .git/refs/remotes -type f ! -regex '.*trunk$' \
      ! -regex '.*trunk@[0-9]*$' ! -regex '.*\/alioth\/.*'`; \
      do git-push alioth $(echo $REMOTES | sed 's|\.git/refs/||'); done

Once you have pushed all changes to the shared repository, move the packaging directory from trunk in svn so that no one continues to work on it there.

First create a directory under branches for you package if one doesn't exist already.

$ svn mkdir svn+ssh://svn.debian.org/svn/pkg-games/packages/branches/<package> -m "Creating branches section for <package>"

Finally, move the packaging directory in trunk to the branches section and leave an appropriate message.

$ svn mv svn+ssh://svn.debian.org/svn/pkg-games/packages/trunk/<package> \
      svn+ssh://svn.debian.org/svn/pkg-games/packages/branches/<package>/<package>-svn-save \
      -m "Moving <package> from trunk to branch. Please use git repository instead."

Cloning and pulling

Anyone pulling from a converted repository will have two steps to perform. The first step is the usual cloning.

$ git-clone git+ssh://<username>@git.debian.org/git/pkg-games/<package>.git

And then the next step involves pulling the "remotes" branches and tags that were pushed.

$ cd <package>
$ git-pull origin +refs/remotes/*:refs/remotes/*

Note about tags and branches

Tags and branches are preserved using what's called "git remotes". This means that there are no real git tags and branches visible, but that the SVN trunk, tags and branches are tracked as separate repositories. Downside is that you need to switch to to the remotes individually before you can update them.

All tags and branches are listed under .git/refs/remotes/ and can be checked out, but it is somewhat confusing as all old schemes for using tags and branches are there too...

So to checkout a branch do the following.

$ git-checkout remotes/<some_branch>

And for tags.

$ git-checkout remotes/tags/<some_tag>

mr

The mr command can be used to checkout, update, and commit to multiple repositories. In the pkg-games svn repository, is a packages/trunk/.mrconfig file that configures mr for all the repositories used by the games team.

New git repositories should be added to this .mrconfig file.

To use it, install the mr package, and create a ~/.mrconfig file letting mr know about the pkg-games svn repository. In this example, it will be checked out to ~/src/packages/games, but you can modify to suit. If you already have a pkg-games svn checkout, you can change the directory to point to that.

[src/packages/games]
chain = true
checkout = svn co svn+ssh://svn.debian.org/svn/pkg-games/packages/trunk games

Then run "mr checkout", which will checkout the svn repository into ~/src/packages/games.

A second "mr checkout" (necessary because of bug #447553) will checkout the additional git repositories, into subdirectories of ~/src/packages/games/.

Now you can use mr to act on all configured repositories at once.

Update all repositories:

% mr update

Get status of all checkouts:

% mr status

List all repositories that mr knows about:

% mr list

Or even commit changes in each repository:

% mr commit

If you've added a new git repository in ~/src/packages/games/<foo> and are in that directory, you can have mr automatically add it to the pkg-games .mrconfig file by running "mr register". (Don't forget to commit the file.)

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 [http://bugs.debian.org/481806].

See Also