3 dgit - tutorial for package maintainers already using git-buildpackage(1)
7 This document explains how B<dgit> can be incorporated into a
8 git-buildpackage(1) package-maintenance workflow. This should be read
9 jointly with git-buildpackage(1)'s documentation. Some reasons why
10 you might want to incorporate B<dgit> into your existing workflow:
16 Benefit from dgit's safety catches. In particular, ensure that your
17 upload always matches exactly your git HEAD.
21 Provide a better, more detailed git history to downstream dgit users,
22 such as people using dgit to do an NMU (see dgit-nmu-simple(7) and
27 Note that we assume a patches-unapplied repository: the upstream
28 source committed to the git repository is unpatched.
29 git-buildpackage(1) can work with patched-applied repositories, but is
30 normally used with patches-unapplied.
32 =head1 GIT CONFIGURATION
38 % git config dgit.default.quilt-mode gbp
42 in your repository, you can omit I<--gbp> wherever it occurs below.
44 Note that this does require that you always work from your gbp master
45 branch, never the dgit patches-applied branch.
49 You can perform builds like this:
53 % dgit [--allow-dirty] gbp-build [OPTIONS]
57 where I<--allow-dirty> is needed for testing uncommitted changes, and
58 I<OPTIONS> are any further options to be passed on to
61 If you are doing a source-only upload, you do not need to prepare a
62 I<_source.changes>, as B<dgit push-source> will take of that on your
65 If you need to include binaries with your upload, you will probably
66 want to use sbuild(1), pbuilder(1) or cowbuilder(1):
70 % dgit --rm-old-changes --gbp sbuild
74 replacing 'sbuild' with 'pbuilder' or 'cowbuilder' if appropriate.
76 We use I<--rm-old-changes> to ensure that there is exactly one changes
77 file corresponding to this package, so we can be confident we're
78 uploading what we intend (though B<dgit push> will do some safety
81 Note that none of the commands in this section are required to upload
82 with dgit. You can invoke gbp-buildpackage(1), pbuilder(1),
83 cowbuilder(1) and sbuild(1) directly. However, the defaults for these
84 tools may leave you with something that dgit will refuse to upload
85 because it doesn't match your git HEAD.
87 As a general rule, leave all signing and tagging to dgit.
91 Don't use I<--git-tag>: B<dgit push> will do this for you. To do a
96 % dgit --gbp push-source
100 or if you need to include binaries,
108 This will push your git history to the dgit-repos, but you probably
109 want to follow it up with a push to salsa.
111 You will need to pass I<--overwrite> if the previous upload was not
114 If this is first ever dgit push of the package, consider passing
115 I<--deliberately-not-fast-forward> instead of I<--overwrite>. This
116 avoids introducing a new origin commit into the dgit view of your git
117 history. (This origin commit would represent the most recent non-dgit
118 upload of the package, but this should already be represented in your
121 =head1 INCORPORATING NMUS
123 B<dgit pull> can't yet incorporate NMUs into patches-unapplied gbp
124 branches. You can just apply the NMU diff the traditional way. The
125 next upload will require I<--overwrite>.
133 This tutorial was written and is maintained by Sean Whitton <spwhitton@spwhitton.name>.