Introduction
Welcome to &gbp;, a system that integrates the
Debian package build
system with Git. The current version of this manual can be found
here.
What can these tools do for you:
Import an existing &debian; package into &git;Import new upstream versions, NMUs etc. with optional filtersAutomatic upstream tarball generationMaintain a consistent branch and tag naming across
repositories or across a team of developersAutomatically sign tagsAutomatically push changes to remote repositoriesMake sure you have committed all changes to the right
branch before releasingExport to a clean build area before buildingAutomatic debian/changelog generationAutomatic generation of snapshot releases for local testingSimple patch management
All of this is (hopefully) being done without restricting the user to certain usage patterns.
Repository Layout and TerminologyIt is recommended to have the Debian packaging on a seprate
branch than the upstream source this, of course, has
no meaning for Debian native packages.
This is necessary to be able to import
and merge in new upstream versions via &gbp-import-orig;.
To distinguish these two branches the following terminology
corresponding to the command
line and config file options is used:
The (the default branch
name used in the &git; repository is master) holds
your current development work. That's the branch you usually cut your
releases from and the default branch new upstream releases are merged
onto. The (the default
branch name used in the &git; repository is
upstream) holds the upstream releases. This can
either be a branch you import to or a branch of an upstream repository
you pull from. The (the default
branch name used in the &git; repository is
pristine-tar) holds the necessary additional
information to recreate the original tarball from the
. In order to use this feature you need
to install the &pristine-tar; package. There can be one or more . Every patch-queue branch is related to a
. If the is called
master the corresponding patch-queue branch is
called patch-queue/master. The patch-queue branch is
the debian branch plus the contents of
debian/patches applied. These branches are managed
with &gbp-pq;.
You're completely
free to pick any repository layout and the branch names above are only
&gbp;'s defaults. They can be changed at any point in time
and you can work with an arbitrary number of branches.
For example branches like nmu,
backports or stable might
(temporarily or permanent) become your
and branches like dfsg or
snapshots might become your
- it doesn't matter if these branches
are maintained with &gbp-import-orig; or not.
A recommended branch layout is described in .
Since &gbp-buildpackage; only works with local &git;-repositories
you have to use git push in order to publish your
changes to remote repositories like git.debian.org, this can also be
automized with &gbp-buildpackage;'s
hook.Workflow
A typical, simple workflow consists of the following steps:
Import a new Debian package via &gbp-import-dsc;. This
imports the &debian; Package on the
and the upstream sources on the .Develop, test, commit changes. During this time you can
always build the package with &gbp-buildpackage;. In case you have
uncommitted changes in your source tree you can use the
option.Optionally you can create the Debian changelog entries
using &gbp-dch; and create snapshot releases for testing using its
option.Once satisfied you can build the final package with
&gbp-buildpackage; . This additionally
creates a tag within &git; so you can switch back to that version later
at any time. The format of the tags can be specified, tags can
be &gpg; signed.When a new upstream version is released and upstream
isn't using &git; you can import the new version via &gbp-import-orig;
onto the . &gbp-import-orig; will
by default try to merge the new upstream version onto the
. You can skip the merge with
. After resolving any potential conflicts
go back to the second step. These steps will be explaind in more details in the following sections.