Importing already existing Debian packages

Importing an already existing Debian package into a Git repository is as easy as:

gbp import-dsc package_0.1-1.dsc
    

If you want to be able to exactly recreate the original tarball (orig.tar.gz) from Git, you should also specify the --pristine-tar option. This is recommended.

If you want to import further versions, you can change into your shiny new Git repository and just continue with the same command:

cd package/
gbp import-dsc package_0.1-2.dsc
gbp import-dsc package_0.1-3.dsc
gbp import-dsc package_0.2-1.dsc
    

Or you can import all versions at once using gbp import-dscs:

gbp import-dscs /path/to/history/package_*.dsc
    

You can also import all versions of a package known from the snapshot.debian.org service using the --debsnap option of gbp import-dscs:

gbp import-dscs --debsnap package
    

Importing a new upstream version

Change into your Git repository (which can be empty), make sure it has all local modifications committed, and run either of:

gbp import-orig /path/to/package_0.2.orig.tar.gz
gbp import-orig /path/to/package_0.2.tar.bz2
gbp import-orig /path/to/package-0.2/
    

If you are using debian/watch to keep track of how to retrieve upstream sources, you can also simply use the --uscan option:

gbp import-orig --uscan
    

You can also filter out content you don't want imported:

gbp import-orig --filter='CVS/*' /path/to/package_0.2.orig.tar.gz
    

If you expect a merge conflict, you can delay the merge to the debian-branch via the --no-merge option and pull in the changes from the upstream-branch later.

If you want to be able to exactly recreate the original tarball (orig.tar.gz) from Git, you should also specify the --pristine-tar option. This is recommended.

To customize the commit message used by gbp import-orig, use the --import-msg option. This string is a standard Python format string, into which the version variable is interpolated. (i.e., use %(version)s in your message to get the imported upstream version).

Converting an existing Git repository

If the Git repository wasn't created with gbp import-dsc, you have to tell gbp buildpackage and friends where to find the upstream sources.

git branch upstream theupstream-branch
git branch -D theupstream-branch
    

cat <<EOF > .git/gbp.conf
[DEFAULT]
# this is the upstream-branch:
upstream-branch=theupstream-branch
EOF
    

    COMMIT_ID=`git log --pretty=oneline | tail -1 | awk '{ print $1 }'`
    git branch upstream $COMMIT_ID

    git checkout --orphan upstream
    git rm -rf .
    git commit --allow-empty -m 'Initial upstream branch.'
    git checkout -f master

    git symbolic-ref HEAD refs/heads/upstream
    git rm --cached -r .
    git commit --allow-empty -m 'Initial upstream branch.'
    git checkout -f master

Starting a Debian package from scratch

So far, we assumed you already have a Debian package to start with, but what if you want to start a new package? First, create an empty repository:

mkdir package-0.1
cd package-0.1
git init
    

Then, you import the upstream sources, branch off the upstream-branch branch and add the Debian files (e.g. via dh_make):

gbp import-orig -u 0.1 ../package-0.1.tar.gz
dh_make
    

When upstream uses Git

If upstream already uses git for packaging, there are several ways to handle packaging. Two of them will be described in a bit detail here:

[git-buildpackage]
upstream-tag = v%(version)s
	

	    git clone --no-checkout -o upstream git://git.example.com/libgbp.git
	    cd libgbp
	    git checkout -b debian/sid v1.0
	  

	    gbp buildpackage --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
	  

	    git fetch upstream
	    git merge v1.1
	    gbp dch --debian-branch=debian/sid --snapshot --auto debian/
	    gbp buildpackage --git-ignore-new --git-pristine-tar --git-pristine-tar-commit --git-upstream-tag='v%(version)s'
	  

	    gbp dch --release --auto --git-debian-branch=debian/sid
	    git commit -m"Release 1.1-1" debian/changelog
	    gbp buildpackage --git-upstream-tag='v%(version)s' --git-debian-branch=debian/sid
	  

	    gbp import-orig --upstream-vcs-tag=v0.0.1 foo_0.0.1.orig.tar.gz
	  

Branch layout

By default, gbp uses one branch to keep the Debian packaging called master and a branch to keep the upstream packaging called upstream.

This layout is simple to get started but falls short if one needs to maintain several versions of the package at the same time. Therefore the following layout is recommended:

In case pristine-tar is being used, there will be a single pristine-tar branch that keeps all binary deltas.