Introduction

Table of Contents
Repository Layout and Terminology
Workflow

Welcome to git-buildpackage, a system that integrates the Debian package build system with Git.

What can these tools do for you:

All of this is (hopefully) being done without restricting the user to certain usage patterns.


Repository Layout and Terminology

The only requirement on the repository layout for using git-buildpackage and friends is, that the branch the debian work is being done on is different from the branch the upstream sources are being maintained on (this, of course, has no meaning for Debian native packages). This is necessary to be able to build upstream tarballs and to merge in new upstream versions. To distinguish these two branches the following terminology [1] is used:

You're completely free to pick any repository layout and the branch names above are only git-buildpackage'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, bpo or stable might (temporarilly or permanent) become your debian-branch and branches like dfsg_free or snapshots might become your upstream-branch - it doesn't matter if these branches are maintend with git-import-orig or not.

Since Git-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 git-buildpackage's post-tag hook.


Workflow

A typical, simple workflow consists of the following steps:

  1. Import a new Debian package via git-import-dsc. This imports the Debian Package on the debian-branch and the upstream sources on the upstream-branch.

  2. Develop, test, commit changes. During this time you can always build the package with git-buildpackage. In case you have uncommitted changes in your source tree you can use the --git-ignore-new option.

  3. Optionally you can create the Debian changelog entries using git-dch and create snapshot releases for testing using it's --snapshot option.

  4. Once satisfied you can build the final package with git-buildpackage --git-tag. 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.

  5. When a new upstream version is released and upstream isn't using Git you can import the new version via git-import-orig onto the upstream-branch. git-import-orig will by default try to merge the new upstream version onto the debian-branch. You can skip the merge with --no-merge. After resolving any potential conflicts go back to the second step.

These steps will be explaind in more details in the following sections.

Notes

[1]

corresponding to the command line and config file options