# 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 at gbp.sigxcpu.org/manual.

This is what gbp can do for you:

- Import existing Debian™ packages 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 or git tags, or both at the same time

- Automatically apply debian/copyright filters for DFSG-clean imports

- Recreate (bit-for-bit with pristine-tar) 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

- Add, edit and rebase the `debian/patche` without having to use GNU Quilt

- Pull changes from remote repositories like salsa.debian.org

- Publish changes to remote packaging repositories like salsa.debian.org

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

Git-buildpackage utlizises among others uscan, pristine-tar, debchange and debuild (which in turn uses dpkg-buildpackage and lintian). Prior knowledge about these tools transfer easily to git-buildpackage as for example the configuration options have the same names. However, people learning Debian packaging do not need to know these tools as git-buildpackage will by default use these tools correctly on behalf of the user. Leveraging on these tools also means that git-buildpackage has all the capabilities these tools have, and git-buildpackage is equally compliant to all Debian policies as these tools are.

## Repository Layout and Terminology

It is recommended to have the Debian™ packaging on a separate 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 and in DEP-14 debian/latest) 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 and in DEP-14 upstream/latest) holds the upstream releases. Note that this branch is to contain the upstream source code as it was at the time of the upstream release, which was imported into Debian packaging. It is not intended to point to the tip of the upstream development branch. The branch contents is updated by extracting the upstream source tarball into it, or by pulling from an upstream release tag.

- 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 flexible, recommended branch layout compatible with DEP-14 is described in the section the section called “Branch layout”.

Since gbp buildpackage only works with local Git-repositories, you have to use git push or gbp pushin order to publish your changes to remote repositories like salsa.debian.org; this can be automated with gbp buildpackage's `post-tag` hook.

[1] this, of course, has no meaning for Debian™ native packages

[2] corresponding to the command line and config file options