# 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 filters

- Automatic upstream tarball generation

- Maintain a consistent branch and tag naming across repositories or across a team of developers

- Automatically sign tags

- Automatically push changes to remote repositories

- Make sure you have committed all changes to the right branch before releasing

- Export to a clean build area before building

- Automatic debian/changelog generation

- Automatic generation of snapshot releases for local testing

- Simple patch management

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

# Repository Layout and Terminology

It is recommended to have the Debian packaging on a seprate branch than the upstream source [1]. 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 [2] is used:

- The `debian-branch` (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 `upstream-branch` (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 `pristine-tar branch` (the default branch name used in the Git repository is pristine-tar) holds the necessary additional information to recreate the original tarball from the `upstream-branch`. In order to use this feature you need to install the pristine-tar package.

- There can be one or more `patch-queue branches`. Every patch-queue branch is related to a `debian-branch`. If the `debian-branch` 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 `debian-branch` and branches like dfsg or snapshots might become your `upstream-branch` - it doesn't matter if these branches are maintained with gbp import-orig or not.

A recommended branch layout is described in the Section called Branch layout in the Chapter called Importing Sources.

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 `post-tag` hook.

# Workflow

A typical, simple workflow consists of the following steps:

1. Import a new Debian package via gbp 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 gbp 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 gbp dch and create snapshot releases for testing using its `--snapshot` option.

4. Once satisfied you can build the final package with gbp 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 gbp import-orig onto the `upstream-branch`. gbp 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] | this, of course, has no meaning for Debian native packages
[2] | corresponding to the command line and config file options