3 dgit - tutorial for package maintainers, using a workflow centered around git-debrebase(1)
7 This document describes elements of a workflow for maintaining a
8 non-native Debian package using B<dgit>. We maintain the Debian delta
9 as a series of git commits on our master branch. We use
10 git-debrebase(1) to shuffle our branch such that this series of git
11 commits appears at the end of the branch. This does not involve
12 rewriting any public git history.
14 Some advantages of this workflow:
20 Manipulate the patch queue using the full power of git-rebase(1),
21 instead of relying on quilt(1), and without having to switch away to
22 another branch, as with gbp-pq(1).
26 Avoid the git tree being dirtied by the application or unapplication
27 of patches, as they are always applied.
31 Benefit from dgit's safety catches. In particular, ensure that your
32 upload always matches exactly your git HEAD.
36 Provide your full git history in a standard format on B<dgit-repos>,
37 where it can benefit downstream dgit users, such as people using dgit
38 to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)).
42 This workflow is appropriate for packages where the Debian delta
43 contains multiple pieces which interact, or which you don't expect to
44 be able to upstream soon. For packages with simple and/or short-lived
45 Debian deltas, use of git-debrebase(1) might introduce unneeded
46 complexity. For such packages, consider the workflow described in
49 =head1 INITIAL DEBIANISATION
51 =head2 When upstream tags releases in git
53 This section explains how to start using this workflow with a new
54 package. It should be skipped when converting an existing package to
57 Suppose that the latest stable upstream release is 1.2.2, and this has
58 been tagged '1.2.2' by upstream.
62 % git clone -oupstream https://some.upstream/foo.git
64 % git verify-tag 1.2.2
65 % git reset --hard 1.2.2
66 % git branch --unset-upstream
70 The final command detaches your master branch from the upstream
71 remote, so that git doesn't try to push anything there, or merge
72 unreleased upstream commits. To maintain a copy of your packaging
73 branch on B<salsa.debian.org> in addition to B<dgit-repos>, you can do
78 % git remote add -f origin salsa.debian.org:Debian/foo.git
79 % git push --follow-tags -u origin master
83 Now go ahead and Debianise your package. Just make commits on the
84 master branch, adding things in the I<debian/> directory. If you need
85 to patch the upstream source, see "EDITING THE PATCH QUEUE", below.
86 Note that there is no need to maintain a separate 'upstream' branch,
87 unless you also happen to be involved in upstream development. We
88 work with upstream tags rather than any branches, except when
89 forwarding patches (see FORWARDING PATCHES UPSTREAM, below).
91 Finally, you need an orig tarball:
99 See git-deborig(1) if this fails.
101 This tarball is ephemeral and easily regenerated, so we don't commit
102 it anywhere (e.g. with tools like pristine-tar(1)).
104 =head3 Verifying upstream's tarball releases
108 It can be a good idea to compare upstream's released tarballs with the
109 release tags, at least for the first upload of the package. If they
110 are different, you might need to add some additional steps to your
111 I<debian/rules>, such as running autotools.
113 A convenient way to perform this check is to import the tarball as
114 described in the following section, using a different value for
115 'upstream-tag', and then use git-diff(1) to compare the imported
116 tarball to the release tag. If they are the same, you can use
117 upstream's tarball instead of running git-deborig(1).
121 =head2 When upstream releases only tarballs
123 We need a virtual upstream branch with virtual release tags.
124 gbp-import-orig(1) can manage this for us. To begin
134 Now create I<debian/gbp.conf>:
139 upstream-branch = upstream
140 debian-branch = master
141 upstream-tag = %(version)s
145 pristine-tar-commit = False
152 gbp-import-orig(1) requires a pre-existing upstream branch:
156 % git add debian/gbp.conf && git commit -m "create gbp.conf"
157 % git checkout --orphan upstream
159 % git commit --allow-empty -m "initial, empty branch for upstream source"
160 % git checkout -f master
164 Then we can import the upstream version:
168 % gbp import-orig --merge-mode=replace ../foo_1.2.2.orig.tar.xz
172 Our upstream branch cannot be pushed to B<dgit-repos>, but since we
173 will need it whenever we import a new upstream version, we must push
174 it somewhere. The usual choice is B<salsa.debian.org>:
178 % git remote add -f origin salsa.debian.org:Debian/foo.git
179 % git push --follow-tags -u origin master upstream
183 You are now ready to proceed as above, making commits to the
184 I<debian/> directory.
186 =head1 CONVERTING AN EXISTING PACKAGE
188 This section explains how to convert an existing Debian package to
189 this workflow. It should be skipped when debianising a new package.
191 =head2 No existing git history
197 % git remote add -f upstream https://some.upstream/foo.git
201 =head2 Existing git history using another workflow
203 First, if you don't already have the git history locally, clone it,
204 and obtain the corresponding orig.tar from the archive:
208 % git clone salsa.debian.org:Debian/foo
214 If your tree is patches-unapplied, you will need to make a commit
215 corresponding to each of the quilt patches. gbp-pq(1) can do this for
222 % git merge --ff-only patch-queue/master
227 Then make new upstream tags available:
231 % git remote add -f upstream https://some.upstream/foo.git
235 =for dgit-test dpkg-source-ignores begin
237 Now you simply need to ensure that your git HEAD is dgit-compatible,
238 i.e., it is exactly what you would get if you ran
239 B<dpkg-buildpackage -i'(?:^|/)\.git(?:/|$)' -I.git -S>
240 and then unpacked the resultant source package.
242 =for dgit-test dpkg-source-ignores end
244 To achieve this, you might need to delete
245 I<debian/source/local-options>. One way to have dgit check your
246 progress is to run B<dgit build-source>.
248 The first dgit push will require I<--overwrite>. If this is the first
249 ever dgit push of the package, consider passing
250 I<--deliberately-not-fast-forward> instead of I<--overwrite>. This
251 avoids introducing a new origin commit into your git history. (This
252 origin commit would represent the most recent non-dgit upload of the
253 package, but this should already be represented in your git history.)
255 =head1 IMPORTING NEW UPSTREAM RELEASES
257 =head2 Obtaining the release
259 =head3 When upstream tags releases in git
267 =head3 When upstream releases only tarballs
269 You will need the I<debian/gbp.conf> from "When upstream releases only
270 tarballs", above. You will also need your upstream branch. Above, we
271 pushed this to B<salsa.debian.org>. You will need to clone or fetch
272 from there, instead of relying on B<dgit clone>/B<dgit fetch> alone.
278 % gbp import-orig --no-merge ../foo_1.2.3.orig.tar.xz
282 or if you have a working watch file
286 % gbp import-orig --no-merge --uscan
290 =head2 Importing the release
294 % git debrebase new-upstream-v0 1.2.3
295 % dch -v1.2.3-1 New upstream release.
296 % git add debian/changelog && git commit -m changelog
300 You can now review the merge of the new upstream release:
304 git diff debian/1.2.2-1..HEAD -- . ':!debian'
308 Pass I<--stat> just to see the list of changed files, which is useful
309 to determine whether there are any new or deleted files to may need
310 accounting for in your copyright file.
312 If you obtained a tarball from upstream, you are ready to try a build.
313 If you merged a git tag from upstream, you will first need to generate
322 =head1 EDITING THE PATCH QUEUE
324 =head2 Adding new patches
326 Adding new patches is straightforward: just make commits touching only
327 files outside of the I<debian/> directory. You can also use tools
328 like git-revert(1), git-am(1) and git-cherrypick(1).
330 =head2 Editing patches: starting a debrebase
332 git-debrebase(1) is a wrapper around git-rebase(1) which allows us to
333 edit, re-order and delete patches. Run
341 to start an interactive rebase. You can edit, re-order and delete
342 commits just as you would during B<git rebase -i>. Alternatively, you
343 can perform a non-interactive rebase like this:
347 % git debrebase -- [git-rebase options...]
355 % git debrebase -- --autosquash
359 A third alternative is to have git-debrebase(1) shuffle all the Debian
360 changes to the end of your branch, and then manipulate them yourself
361 using git-rebase(1). For example,
365 % git debrebase launder
366 % git rebase -i HEAD^5 # there are 4 Debian patches
370 =head2 Editing patches: finishing a debrebase
372 After completing the git rebase, your branch will not be a
373 fast-forward of the git HEAD you had before the rebase. This means
374 that we cannot push the branch anywhere. If you are ready to upload,
375 B<dgit push> or B<dgit push-source> will take care of fixing this up
378 If you are not yet ready to upload, and want to push your branch to a
379 git remote such as B<salsa.debian.org>,
383 % git debrebase stitch
387 Note that each time you stitch a debrebase you introduce a pseudomerge
388 into your git history, which may make it harder to read. Try to do
389 all of the editing of the patch queue that you think will be needed
390 for this upload in a single debrebase, so that there is a single
393 A strategy is to debrebase only right before you upload. Before that
394 point, instead of editing the existing patch series, you append fixup
395 commits (and reversions of commits) that alter the upstream source to
396 the required state. You can freely push and pull from
397 B<salsa.debian.org> during this. Just before uploading, you debrebase
398 to tidy everything up.
400 =head1 BUILDING AND UPLOADING
402 Use B<dgit build>, B<dgit sbuild>, B<dgit push> and B<dgit
403 push-source> as detailed in dgit(1). If any command fails, dgit will
404 provide a carefully-worded error message explaining what you should
405 do. If it's not clear, file a bug against dgit. Remember to pass
406 I<--new> for the first upload.
408 After dgit pushing, be sure to git push to B<salsa.debian.org>, if
411 As an alternative to B<dgit build> and friends, you can use a tool
412 like gitpkg(1). This works because like dgit, gitpkg(1) enforces that
413 HEAD has exactly the contents of the source package. gitpkg(1) is
414 highly configurable, and one dgit user reports using it to produce and
415 test multiple source packages, from different branches corresponding
416 to each of the current Debian suites.
418 If you want to skip dgit's checks while iterating on a problem with
419 the package build (for example, you don't want to commit your changes
420 to git), you can just run dpkg-buildpackage(1) or debuild(1) instead.
422 =head2 Laundering the patch queue before uploading
424 Just before you B<dgit push> or B<dgit push-source>, you might want to
425 have git-debrebase(1) shuffle your branch such that the Debian patch
426 queue appears at the end:
430 % git debrebase launder
435 Note that this will introduce a new pseudomerge.
437 =head1 HANDLING DFSG-NON-FREE MATERIAL
439 =head2 When upstream tags releases in git
441 We create a DFSG-clean tag to import to master:
445 % git checkout -b pre-dfsg 1.2.3
447 % git commit -m "upstream version 1.2.3 DFSG-cleaned"
448 % git tag -s 1.2.3+dfsg
449 % git checkout master
450 % git branch -D pre-dfsg
454 Before invoking B<git debrebase new-upstream-v0>, you should first
455 determine whether it would be legally dangerous for the non-free
456 material to be publicly accessible in the git history on
459 If it would be dangerous, there is a big problem;
460 in this case please consult your archive administrators
461 (for Debian this is the dgit administrator dgit-owner@debian.org
462 and the ftpmasters ftpmaster@ftp-master.debian.org).
464 =head2 When upstream releases only tarballs
466 The easiest way to handle this is to add a B<Files-Excluded> field to
467 I<debian/copyright>, and a B<uversionmangle> setting in
468 I<debian/watch>. See uscan(1). Alternatively, see the I<--filter>
469 option detailed in gbp-import-orig(1).
471 =head1 FORWARDING PATCHES UPSTREAM
479 Create a new branch based off upstream's master branch.
483 git-cherry-pick(1) commits from your master branch onto your new
488 Push the branch somewhere and ask upstream to merge it, or use
489 git-format-patch(1) or git-request-pull(1).
493 For example (and it is only an example):
497 % # fork foo.git on GitHub
498 % git remote add -f fork git@github.com:spwhitton/foo.git
499 % git checkout -b fix-error upstream/master
500 % git config branch.fix-error.pushRemote fork
501 % git cherry-pick master^2
503 % # submit pull request on GitHub
507 Note that when you merge an upstream release containing your forwarded
508 patches, a debrebase will transparently handle "dropping" the patches
509 that have been forwarded, "retaining" the ones that haven't.
511 =head1 INCORPORATING NMUS
519 If the NMUer added new commits modifying the upstream source, you will
520 probably want to debrebase before your next upload to tidy those up.
522 For example, the NMUer might have used git-revert(1) to unapply one of
523 your patches. A debrebase will strip both the patch and the reversion
524 from the patch series.
532 This tutorial was written and is maintained by Sean Whitton
533 <spwhitton@spwhitton.name>. It contains contributions from other dgit
534 contributors too - see the dgit copyright file.