---
name: "dgit-maint-gbp"
section: "7"
platform: "linux"
package: "dgit"
version: "12.16"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/dgit-maint-gbp"
---

# dgit-maint-gbp(7)

tutorial for package maintainers already using git-buildpackage(1)

## NAME

dgit - tutorial for package maintainers already using [git-buildpackage(1)](/git-buildpackage/1.md)

## INTRODUCTION

This document explains how **dgit** can be incorporated into a [**git-buildpackage**(1)](/git-buildpackage/1.md) package-maintenance workflow.  This should be read jointly with [**git-buildpackage**(1)](/git-buildpackage/1.md)'s documentation.  Some reasons why you might want to incorporate **dgit** into your existing workflow:

- •

  Benefit from dgit's safety catches.  In particular, ensure that your upload always matches exactly your git HEAD.

- •

  Provide a better, more detailed git history to downstream dgit users, such as people using dgit to do an NMU (see [**dgit-nmu-simple**(7)](/dgit-nmu-simple/7.md) and [**dgit-user**(7)](/dgit-user/7.md)).

Note that we assume a patches-unapplied repository: the upstream source committed to the git repository is unpatched. [**git-buildpackage**(1)](/git-buildpackage/1.md) can work with patched-applied repositories, but is normally used with patches-unapplied.

## GIT CONFIGURATION

If you have configured an *export-dir* in your gbp.conf, you should tell dgit about it:

```
    % git config --global dgit.default.build-products-dir /home/spwhitton/build-area
```

If you run

```
    % git config dgit.default.quilt-mode gbp
```

in your repository, you can omit *--gbp* wherever it occurs below.

Note that this does require that you always work from your gbp master branch, never the dgit patches-applied branch.

## BUILDING

You can perform test builds like this:

```
    % dgit [--include-dirty] gbp-build [OPTIONS]
```

where *--include-dirty* is needed for testing uncommitted changes, and *OPTIONS* are any further options to be passed on to [**gbp-buildpackage**(1)](/gbp-buildpackage/1.md).

If you are doing a source-only upload, you do not need to prepare a *\_source.changes*, as **dgit push-source** will take of that on your behalf.

If you need to include binaries with your upload, you will probably want to use [**sbuild**(1)](/sbuild/1.md), [**pbuilder**(1)](/pbuilder/1.md) or **cowbuilder**(1):

```
    % dgit --rm-old-changes --gbp sbuild
```

replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.

We use *--rm-old-changes* to ensure that there is exactly one changes file corresponding to this package, so we can be confident we're uploading what we intend (though **dgit push** will do some safety checks).

Note that none of the commands in this section are required to upload with dgit.  You can invoke [**gbp-buildpackage**(1)](/gbp-buildpackage/1.md), [**pbuilder**(1)](/pbuilder/1.md), **cowbuilder**(1) and [**sbuild**(1)](/sbuild/1.md) directly.  However, the defaults for these tools may leave you with something that dgit will refuse to upload because it doesn't match your git HEAD.

As a general rule, leave all signing and tagging to dgit.

## UPLOADING

Don't use *--git-tag*: **dgit push-source**, **dgit push-built**, and **dgit push** will do this for you. To do a source-only upload:

```
    % dgit --gbp push-source
```

or if you need to include binaries,

```
    % dgit --gbp push-built
```

This will push your git history to the dgit-repos, but you probably want to follow it up with a push to salsa.

You will need to pass *--trust-changelog* if the previous upload was not performed with dgit.

If this is first ever dgit push of the package to this suite, consider passing *--deliberately-not-fast-forward* instead of *--trust-changelog*.  This avoids introducing a new origin commit into the dgit view of your git history.  (This origin commit would represent the most recent non-dgit upload of the package, but this should already be represented in your git history.)

Alternatively, you can use [**git-debpush**(1)](/git-debpush/1.md).  For the first upload you should pass the **--gbp** quilt mode option (see [**git-debpush**(1)](/git-debpush/1.md)).

## INCORPORATING NMUS

**dgit pull** can't yet incorporate NMUs into patches-unapplied gbp branches.  You can just apply the NMU diff the traditional way.  The next upload will require *--trust-changelog*.

## SEE ALSO

[**dgit**(1)](/dgit/1.md), [**dgit**(7)](/dgit/7.md)

## AUTHOR

This tutorial was written and is maintained by Sean Whitton \<spwhitton@spwhitton.name\>.