Differences between revisions 1 and 4 (spanning 3 versions)
Revision 1 as of 2009-09-12 09:53:47
Size: 12134
Editor: jmtd
Comment: import git material from parent
Revision 4 as of 2009-09-12 10:15:31
Size: 13526
Editor: jmtd
Comment: add 'possible problems' from VCS page
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Git == #language en
<<TableOfContents>>
Line 4: Line 6:
=== Global git Configuration === == Global git Configuration ==
Line 11: Line 13:
=== Creating a git repository === == Creating a git repository ==
Line 53: Line 55:
=== Uploading a package to the repository === == Uploading a package to the repository ==
Line 91: Line 93:
=== Accessing a repository === == Accessing a repository ==
Line 125: Line 127:
=== Committing changes === == Committing changes ==
Line 142: Line 144:
=== Updating === == Updating ==
Line 149: Line 151:
=== Tagging === == Tagging ==
Line 186: Line 188:
=== Using pristine-tar === == Using pristine-tar ==
Line 201: Line 203:
=== Converting from svn repository === == Converting from svn repository ==
Line 205: Line 207:
=== Generating patches === == Generating patches ==
Line 229: Line 231:
==== git format-patch ==== === git format-patch ===
Line 235: Line 237:
=== Reverting changes while building === == Reverting changes while building ==
Line 250: Line 252:
=== Reverting commits and files scheduled for commit === == Reverting commits and files scheduled for commit ==
Line 272: Line 274:
=== Adding a new upstream release === == Adding a new upstream release ==
Line 292: Line 294:

== 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 DebianBug:481806.

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 user.name "<your name>"
$ git config --global user.email "<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" section below.

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>@git.debian.org
$ cd /git/pkg-games
$ ./setup-repository <package> '<package description>'

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

$ 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

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

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

And, finally, add a new section for the new repo in the .mrconfig file from from our SVN trunk and commit it:

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

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 for more details.

To view a summary of the repository on your favorite 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 --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

Converting from svn repository

See Converting from svn 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.

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

This will do the following actions :-

  • Upload the contents of the upstream tarball to the upstream branch.
  • (If you are using pristine-tar), uploads the delta between upstream and master to a gziped tarball on the pristine-tar branch.
  • Tags the upstream branch upstream/version
  • Merges the upstream branch into the master branch
  • runs a dch on the master branch to bump the debian version

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.