Differences between revisions 25 and 26
Revision 25 as of 2013-05-26 19:59:28
Size: 10098
Editor: ?GeertStappers
Comment: Link to ssh-fingerprint of the git server
Revision 26 as of 2014-05-19 21:38:58
Size: 10110
Editor: ?EmmanuelBourg
Comment: Add a reference to pkg-java-svn2git
Deletions are marked like this. Additions are marked like this.
Line 22: Line 22:

The process described below has been automated by a script available at http://anonscm.debian.org/gitweb/?p=pkg-java/pkg-java-svn2git.git
Line 56: Line 58:
The master copy of this file is on git.debian.org (created with command above):
TODO: Thomas, can you update the master copy or do we get write access?
The master copy of this file is available in the pkg-java-svn2git repository on git.debian.org.

Guidelines for Packages Maintained on git.debian.org:/git/pkg-java

This chapter adds additional guidelines for packages maintained in Alioth's git repositories. Please read the page Java/JavaVcs first if you have not done yet. Most of the guidelines are inspired by git-buildpackage.

Git repositories can be created in the directory /git/pkg-java or in a subdirectory at git.debian.org. The WWW interface is available at http://anonscm.debian.org/gitweb/. Using the /git/pkg-java/setup-repository script is RECOMMENDED for creating a new repository because it uses the correct options and sets up the mailing lists.

Contrary to subversion the upstream code SHOULD be imported. Every new upstream version SHOULD be tagged as upstream/VERSION after cleaning it up. Using pristine-tar is RECOMMENDED. The pristine-tar branch SHOULD be called pristine-tar. Having an explicit upstream branch is OPTIONAL but it SHOULD be called upstream if it exists.

Every repository should have a master branch with the upstream code, the Debian code and patches. The newest version of README.source MUST be available in the master branch. The patches SHOULD be unapplied before committing changes.

You MAY push upstream tags to Alioth if upstream uses git. But you SHOULD always create an explicit tag upstream/VERSION even if it is identical to some upstream tag. You MAY skip adding a get-orig-source target in debian/rules if you create the upstream/VERSION tag directly in git without any intermediate tarball. You MUST document the workflow for upstream updates in README.source in such cases. The tarball used in the successful upload SHOULD be committed with pristine-tar.

Every successful upload MUST be tagged as debian/VERSION.

Branches and tag schemas not mentioned here MUST be documented in README.source. Any required tools except git-buildpackage and pristine-tar MUST be documented in README.source.

QUESTION: do we need guidelines about .gitignore, .gitattributes, and .gbp.conf?

Converting an SVN repository to Git

The process described below has been automated by a script available at http://anonscm.debian.org/gitweb/?p=pkg-java/pkg-java-svn2git.git

Create the git repository on git.debian.org

( Verify the ssh-fingerprint through http://db.debian.org/machines.cgi )

$ ssh <login>@git.debian.org
<login>@vasks:~$ cd /git/pkg-java
<login>@vasks:/git/pkg-java$ ./setup-repository <package>
Initialized empty shared Git repository in /srv/git.debian.org/git/pkg-java/<package>.git/
Repo <package>.git has been created
Commit messages for <package>.git have been forwarded to pkg-java-commits@lists.alioth.debian.org and <package>_cvs@packages.qa.debian.org

Update the authors file

You'll need an authors file to have pretty full names and email adresses in the Git log. You can start with this list. Please add more pkg-java authors.

drazzib = Damien Raude-Morvan <drazzib@debian.org>
gg0-guest = gg0 <gg0@unknown.com>
ludovicc-guest = Ludovic Claude <ludovic.claude@laposte.net>
mkoch = Michael Koch <konqueror@gmx.de>
twerner = Torsten Werner <twerner@debian.org>
tmancill = Tony Mancill <tmancill@debian.org>
fourmond = Vincent Fourmond <fourmond@debian.org>
pcc-guest = Peter Collingbourne <peter@pcc.me.uk>
ewl-guest = Eric Lavarde <deb@zorglub.s.bawue.de>
nomadium-guest = Miguel Landaeta <miguel@miguel.cc>
fnatter-guest = Felix Natter <fnatter@gmx.net>

Somebody with SVN installed might run this line to find more authors:

svn log "svn://svn.debian.org/svn/pkg-java/" | awk -F'|' '/^r[0-9]+/ { print $2 }' | sort -u >/tmp/pkg-java-authors

The master copy of this file is available in the pkg-java-svn2git repository on git.debian.org.

Convert the svn repo to a (local!) git repo

You can then convert a pkg-java SVN repo with something like (requires the git-svn package):

$ git svn clone  --authors-file=/tmp/pkg-java-authors --no-metadata \
    --trunk=trunk/maven-repo-helper \
    --tags=tags/maven-repo-helper \
$ mv pkg-java <package> # the default directory name is "pkg-java"

You must give your own Alioth username and pkg-java-authors file and replace "maven-repo-helper" (package name).

Fix branches in the new git repo

Run a script which will convert bogus branches to git tags. You don't need to understand all of this.

$ cd <package> # cd to git repo

Run this script inside the repo:

for branch in `git branch -r`; do
    if [ `echo $branch | egrep "tags/.+$"` ]; then
        version=`basename $branch`
        subject=`git log -1 --pretty=format:"%s" $branch`
        GIT_COMMITTER_DATE=`git log -1 --pretty=format:"%ci" $branch` \
            git tag -f -m "$subject" "debian/$version" "$branch^"

        git branch -d -r $branch

Push the local git repo to git.debian.org

You need to watch out with this step! While the previous steps were local, in this step you can break things! Make sure to use the right remote URL! Run git push with --dry-run first and check the output!

$ cd <package> # cd to git repo
$ git remote add origin git+ssh://<login>@git.debian.org/git/pkg-java/<package>.git
$ git push --tags -u origin master

The git push ... output should look like this:

Counting objects: 134, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (108/108), done.
Writing objects: 100% (134/134), 22.29 KiB, done.
Total 134 (delta 58), reused 0 (delta 0)
To git+ssh://fnatter-guest@git.debian.org/git/pkg-java/freeplane.git
 * [new branch]      master -> master
 * [new tag]         debian/1.1.1-1 -> debian/1.1.1-1
 * [new tag]         debian/1.1.3-1 -> debian/1.1.3-1
 * [new tag]         debian/1.1.3-2 -> debian/1.1.3-2
Branch master set up to track remote branch master from origin.

Using git-buildpackage

This chapter gives some instruction about using git-buildpackage. The full manual can be found at https://honk.sigxcpu.org/piki/projects/git-buildpackage/.

Create the git repository on git.debian.org

<login>@vasks:~$ cd /git/pkg-java
<login>@vasks:/git/pkg-java$ ./setup-repository <package>
Initialized empty shared Git repository in /srv/git.debian.org/git/pkg-java/<package>.git/
Repo <package>.git has been created
Commit messages for <package>.git have been forwarded to pkg-java-commits@lists.alioth.debian.org and <package>_cvs@packages.qa.debian.org

Import upstream

You might have to create the upstream branch if you converted from svn: See the commands below Alternatively, if you are only importing source from original tarballs... in http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.import.html#GBP.IMPORT.CONVERT.

git-import-orig --filter "*.jar" --filter "*.war" \
                --filter apache-solr-1.4.0/docs/api \
                --filter apache-solr-1.4.0/dist --filter-pristine-tar \
                --pristine-tar -u1.4.0 ../apache-solr-1.4.0.tgz

Note: Make sure you use the --filter-pristine-tar option if you use --filter options (otherwise your pristine-tar branch will be broken)!

This command

  • filters out (repackages) unwanted files from the upstream tarball,
  • imports the (filtered) upstream tarball into the git branch "upstream",
  • tags the import with the version number,
  • merges the updated upstream into the packaging branch "master"
  • and creates a pristine-tar import to restore the (filtered) upstream tarball.

The --filter options are translated directly to tar --exclude options. See man tar for details.

--filter-pristine-tar makes sure that the same filtering is also applied to the pristine tarball. Therefor the tarball saved with prisitine-tar isn't pristine anymore, but rather repackaged.

So the shellscript debian/orig-tar.sh from the solr package which manually removes all *.jar and repackages the upstream tarball isn't necessary anymore.

You may want to make two imports with git-import-orig for each new upstream tarball. The first import is without any filtering and saves the original tarball as it for later reference. The second import adds a "+dfsg" suffix to the tarball, filters all jar files and is the one actually uploaded to debian.

You may need to manually remove .git directories from the orig.tar.gz

Typical git workflow

git workflow is quite straightforward:

  • fetch tarball
  • git-import-orig <tarball> (updates upstream and pristine-tar branches)

  • update changelog and other files
  • do package improvements, remove patches applied upstream, etc.
  • debcommit -a (does a local commit in the master branch)
  • git-buildpackage (which uses cowbuilder in my setup)
  • local testing
  • dch -r
  • git commit -a -m "Release ...."
  • git-buildpackage --git-tag --git-sign-tags (produces and tags the release for upload)
  • dput <...>.changes

  • git push --all (pushes all local changes to the repo at git.d.o)
  • git push --tags (pushes the tags)


We use git together with mr (Multiple Repository management tool) to track the git repositories for each package.

Obtaining the master repository

git clone <alioth-username>@git.debian.org:/git/pkg-java/pkg-java.git

NOTE that your public key must be known to alioth in order for this to work, see note below.

Then, to obtain all the team packages, do:

cd pkg-java
# look at .mrconfig
apt-get install mr
mr checkout

To enable parallel checkouts, use

mr -j 5 checkout

To avoid typing your username and your password see this page.

WARNING: as of December 2011, the pkg-java repository uses 5.5 GB of space.

To get the latest sources from all packages, do

mr -j 5 update

CategoryJava CategoryPackageManagement CategoryGit