# Introduction

Welcome to git-buildpackage (short &gbp;), a system that integrates the Debian package build system with Git. The most recent version of this manual can be found &manual;.

This is what &gbp; can do for you:

- Initially import an existing &debian; package into &git;

- Incrementally import new versions of a Debian package into &git; e.g. for importing NMUs or to maintain downstream modifications

- Import new upstream versions from tarballs with optionally filters applied

- Recreate the upstream tarball from information stored in &git;

- Maintain a consistent branch and tag naming within a &git repository, across repositories or across a team of developers

- Automatically sign generated tags

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

- Execute hooks at various points of the package build process e.g. to automatically push changes to remote repositories

- Integrate the build process with cowbuilder or other builders

- Export to a clean build area before building the package

- Generate debian/changelog automatically

- Manage your quilt patches when using 3.0 (quilt) source format

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 separate 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 `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 &git; 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; 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 permanently) 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 gbp.branch.naming.

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 be automated with &gbp-buildpackage;'s `post-tag` hook.

## Workflow

A typical, simple workflow consists of the following steps:

1. Initially import a &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 explained in more details in the following sections.