#language en
<<TableOfContents>>

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 "[[Games/VCS/git/converting-from-svn|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>@git.debian.org
$ 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>@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'.
{{{
$ 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 "pkg-games-commits@lists.alioth.debian.org"
$ git config --add hooks.cia-project debian-pkg-games
$ cat >hooks/post-receive <<END
#!/bin/sh
exec /home/groups/pkg-games/bin/post-receive
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 '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>@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.  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://git.debian.org/git/pkg-games/<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>@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 page [[Games/VCS/git/converting-from-svn|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
}}}

== Building ==

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

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

== 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 :-
 * 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

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

----
CategoryGit