1dgit-maint-debrebase(7)              dgit              dgit-maint-debrebase(7)
2
3
4

NAME

6       dgit - tutorial for package maintainers, using a workflow centered
7       around git-debrebase(1)
8

INTRODUCTION

10       This document describes elements of a workflow for maintaining a non-
11       native Debian package using dgit.  We maintain the Debian delta as a
12       series of git commits on our master branch.  We use git-debrebase(1) to
13       shuffle our branch such that this series of git commits appears at the
14       end of the branch.  All the public git history is fast-forwarding,
15       i.e., we do not rewrite and force-push.
16
17       Some advantages of this workflow:
18
19       ·   Manipulate the delta queue using the full power of git-rebase(1),
20           instead of relying on quilt(1), and without having to switch back
21           and forth between patches-applied and patches-unapplied branches
22           when committing changes and trying to build, as with gbp-pq(1).
23
24       ·   If you are using 3.0 (quilt), provide your delta queue as a
25           properly separated series of quilt patches in the source package
26           that you upload to the archive (unlike with dgit-maint-merge(7)).
27
28       ·   Avoid the git tree being dirtied by the application or
29           unapplication of patches, as they are always applied.
30
31       ·   Benefit from dgit's safety catches.  In particular, ensure that
32           your upload always matches exactly your git HEAD.
33
34       ·   Provide your full git history in a standard format on dgit-repos,
35           where it can benefit downstream dgit users, such as people using
36           dgit to do an NMU (see dgit-nmu-simple(7) and dgit-user(7)).
37
38       ·   Minimise the amount you need to know about 3.0 (quilt) in order to
39           maintain Debian source packages which use that format.
40
41       This workflow is appropriate for packages where the Debian delta
42       contains multiple pieces which interact, or which you don't expect to
43       be able to upstream soon.  For packages with simple and/or short-lived
44       Debian deltas, use of git-debrebase(1) introduces unneeded complexity.
45       For such packages, consider the workflow described in
46       dgit-maint-merge(7).
47

INITIAL DEBIANISATION

49       This section explains how to start using this workflow with a new
50       package.  It should be skipped when converting an existing package to
51       this workflow.
52
53   When upstream tags releases in git
54       Suppose that the latest stable upstream release is 1.2.2, and this has
55       been tagged '1.2.2' by upstream.
56
57           % git clone -oupstream https://some.upstream/foo.git
58           % cd foo
59           % git verify-tag 1.2.2
60           % git reset --hard 1.2.2
61           % git branch --unset-upstream
62
63       The final command detaches your master branch from the upstream remote,
64       so that git doesn't try to push anything there, or merge unreleased
65       upstream commits.  To maintain a copy of your packaging branch on
66       salsa.debian.org in addition to dgit-repos, you can do something like
67       this:
68
69           % git remote add -f origin salsa.debian.org:Debian/foo.git
70           % git push --follow-tags -u origin master
71
72       Now go ahead and Debianise your package.  Make commits on the master
73       branch, adding things in the debian/ directory, or patching the
74       upstream source.  For technical reasons, it is essential that your
75       first commit introduces the debian/ directory containing at least one
76       file, and does nothing else. In other words, make a commit introducing
77       debian/ before patching the upstream source.
78
79       Finally, you need an orig tarball:
80
81           % git deborig
82
83       See git-deborig(1) if this fails.
84
85       This tarball is ephemeral and easily regenerated, so we don't commit it
86       anywhere (e.g. with tools like pristine-tar(1)).
87
88       Comparing upstream's tarball releases
89
90           The above assumes that you know how to build the package from git
91           and that doing so is straightforward.
92
93           If, as a user of the upstream source, you usually build from
94           upstream tarball releases, rather than upstream git tags, you will
95           sometimes find that the git tree doesn't contain everything that is
96           in the tarball.
97
98           Additional build steps may be needed.  For example, you may need
99           your debian/rules to run autotools.
100
101           You can compare the upstream tarball release, and upstream git tag,
102           within git, by importing the tarball into git as described in the
103           next section, using a different value for 'upstream-tag', and then
104           using git-diff(1) to compare the imported tarball to the release
105           tag.
106
107       Using untagged upstream commits
108
109           Sometimes upstream does not tag their releases, or you want to
110           package an unreleased git snapshot.  In such a case you can create
111           your own upstream release tag, of the form upstream/ver, where ver
112           is the upstream version you plan to put in debian/changelog.  The
113           upstream/ prefix ensures that your tag will not clash with any tags
114           upstream later creates.
115
116           For example, suppose that the latest upstream release is 1.2.2 and
117           you want to package git commit ab34c21 which was made on
118           2013-12-11.  A common convention is to use the upstream version
119           number 1.2.2+git20131211.ab34c21 and so you could use
120
121               % git tag -s upstream/1.2.2+git20131211.ab34c21 ab34c21
122
123           to obtain a release tag, and then proceed as above.
124
125   When upstream releases only tarballs
126       Because we want to work in git, we need a virtual upstream branch with
127       virtual release tags.  gbp-import-orig(1) can manage this for us.  To
128       begin
129
130           % mkdir foo
131           % cd foo
132           % git init
133           % git checkout -b upstream
134           % gbp import-orig \
135               --upstream-branch=upstream --debian-branch=master \
136               --upstream-tag='upstream/%(version)s' \
137               --sign-tags --no-pristine-tar \
138               ../foo_1.2.2.orig.tar.xz
139           % git branch -f upstream
140
141       This should leave you on the master branch.  Next, our upstream branch
142       cannot be pushed to dgit-repos, but since we will need it whenever we
143       import a new upstream version, we must push it somewhere.  The usual
144       choice is salsa.debian.org:
145
146           % git remote add -f origin salsa.debian.org:Debian/foo.git
147           % git push --follow-tags -u origin master upstream
148
149       You are now ready to proceed as above, making commits to the debian/
150       directory and to the upstream source.  As above, for technical reasons,
151       it is essential that your first commit introduces the debian/ directory
152       containing at least one file, and does nothing else.  In other words,
153       make a commit introducing debian/ before patching the upstream source.
154
155       A convenient way to ensure this requirement is satisfied is to start by
156       creating debian/gbp.conf:
157
158           [DEFAULT]
159           upstream-branch = upstream
160           debian-branch = master
161           upstream-tag = upstream/%(version)s
162
163           sign-tags = True
164           pristine-tar = False
165           pristine-tar-commit = False
166
167           [import-orig]
168           merge = False
169
170       and commit that:
171
172           % git add debian/gbp.conf && git commit -m "create gbp.conf"
173
174       Note that we couldn't create debian/gbp.conf before now for the same
175       technical reasons which require our first commit to introduce debian/
176       without patching the upstream source.  That's why we had to pass a lot
177       of options to our first call to gbp-import-orig(1).
178

CONVERTING AN EXISTING PACKAGE

180       This section explains how to convert an existing Debian package to this
181       workflow.  It should be skipped when debianising a new package.
182
183       If you have an existing git history that you have pushed to an ordinary
184       git server like salsa.debian.org, we start with that.  If you don't
185       already have it locally, you'll need to clone it, and obtain the
186       corresponding orig.tar from the archive:
187
188           % git clone salsa.debian.org:Debian/foo
189           % cd foo
190           % dgit setup-new-tree
191           % origtargz
192
193       If you don't have any existing git history, or you have history only on
194       the special dgit-repos server, we start with dgit clone:
195
196           % dgit clone foo
197           % cd foo
198
199       Then we make new upstream tags available:
200
201           % git remote add -f upstream https://some.upstream/foo.git
202
203       We now use a git debrebase convert-from-* command to convert your
204       existing history to the git-debrebase(5) data model.  Which command you
205       should use depends on some facts about your repository:
206
207       (A) There is no delta queue.
208           If there do not exist any Debian patches, use
209
210               % git debrebase convert-from-gbp
211
212       (B) There is a delta queue, and patches are unapplied.
213           This is the standard git-buildpackage(1) workflow: there are Debian
214           patches, but the upstream source is committed to git without those
215           patches applied.  Use
216
217               % git debrebase convert-from-gbp
218
219           If you were not previously using dgit to upload your package (i.e.
220           you were not using the workflow described in dgit-maint-gbp(7)),
221           and you happen to have run dgit fetch sid in this clone of the
222           repository, you will need to pass --fdiverged to this command.
223
224       (C) There is a delta queue, and patches are applied.
225           Use
226
227               % git debrebase convert-from-dgit-view
228
229       Finally, you need to ensure that your git HEAD is dgit-compatible,
230       i.e., it is exactly what you would get if you deleted .git, invoked
231       dpkg-buildpackage -S, and then unpacked the resultant source package.
232
233       To achieve this, you might need to delete debian/source/local-options.
234       One way to have dgit check your progress is to run dgit build-source.
235

GIT CONFIGURATION

237       git-debrebase(1) does not yet support using git merge to merge
238       divergent branches of development (see "OTHER MERGES" in
239       git-debrebase(5)).  You should configure git such that git pull does
240       not try to merge:
241
242           % git config --local pull.rebase true
243
244       Now when you pull work from other Debian contributors, git will rebase
245       your work on top of theirs.
246
247       If you use this clone for upstream development in addition to Debian
248       packaging work, you may not want to set this global setting.  Instead,
249       see the branch.autoSetupRebase and branch.<name>.rebase settings in
250       git-config(5).
251

IMPORTING NEW UPSTREAM RELEASES

253       There are two steps: obtaining git refs that correspond to the new
254       release, and importing that release using git-debrebase(1).
255
256   Obtaining the release
257       When upstream tags releases in git
258
259           % git fetch --tags upstream
260
261       If you want to package an untagged upstream commit (because upstream
262       does not tag releases or because you want to package an upstream
263       development snapshot), see "Using untagged upstream commits" above.
264
265       When upstream releases only tarballs
266
267       You will need the debian/gbp.conf from "When upstream releases only
268       tarballs", above.  You will also need your upstream branch.  Above, we
269       pushed this to salsa.debian.org.  You will need to clone or fetch from
270       there, instead of relying on dgit clone/dgit fetch alone.
271
272       Then, either
273
274           % gbp import-orig ../foo_1.2.3.orig.tar.xz
275
276       or if you have a working watch file
277
278           % gbp import-orig --uscan
279
280   Importing the release
281           % git debrebase new-upstream 1.2.3
282
283       replacing 1.2.3 with upstream/1.2.3 if you imported a tarball.
284
285       This invocation of git-debrebase(1) involves a git rebase.  You may
286       need to resolve conflicts if the Debian delta queue does not apply
287       cleanly to the new upstream source.
288
289       If all went well, you can now review the merge of the new upstream
290       release:
291
292           git diff debian/1.2.2-1..HEAD -- . ':!debian'
293
294       Also, diff with --name-status and --diff-filter=ADR to see just the
295       list of added or removed files, which is useful to determine whether
296       there are any new or deleted files that may need accounting for in your
297       copyright file.
298
299       If you obtained a tarball from upstream, you are ready to try a build.
300       If you merged a git tag from upstream, you will first need to generate
301       a tarball:
302
303           % git deborig
304

EDITING THE DEBIAN PACKAGING

306       Just make commits on master that change the contents of debian/.
307

EDITING THE DELTA QUEUE

309   Adding new patches
310       Adding new patches is straightforward: just make commits touching only
311       files outside of the debian/ directory.  You can also use tools like
312       git-revert(1), git-am(1) and git-cherry-pick(1).
313
314   Editing patches: starting a debrebase
315       git-debrebase(1) is a wrapper around git-rebase(1) which allows us to
316       edit, re-order and delete patches.  Run
317
318           % git debrebase -i
319
320       to start an interactive rebase.  You can edit, re-order and delete
321       commits just as you would during git rebase -i.
322
323   Editing patches: finishing a debrebase
324       After completing the git rebase, your branch will not be a fast-forward
325       of the git HEAD you had before the rebase.  This means that we cannot
326       push the branch anywhere.  If you are ready to upload, dgit push or
327       dgit push-source will take care of fixing this up for you.
328
329       If you are not yet ready to upload, and want to push your branch to a
330       git remote such as salsa.debian.org,
331
332           % git debrebase conclude
333
334       Note that each time you conclude a debrebase you introduce a
335       pseudomerge into your git history, which may make it harder to read.
336       Try to do all of the editing of the delta queue that you think will be
337       needed for this editing session in a single debrebase, so that there is
338       a single debrebase stitch.
339

BUILDING AND UPLOADING

341       You can use dpkg-buildpackage(1) for test builds.  When you are ready
342       to build for an upload, use dgit sbuild, dgit pbuilder or dgit
343       cowbuilder.
344
345       Upload with dgit push or dgit push-source.  Remember to pass --new if
346       the package is new in the target suite.
347
348       In some cases where you used git debrebase convert-from-gbp since the
349       last upload, it is not possible for dgit to make your history fast-
350       forwarding from the history on dgit-repos.  In such cases you will have
351       to pass --overwrite to dgit.  git-debrebase will normally tell you if
352       this will be needed.
353
354       Right before uploading, if you did not just already do so, you might
355       want to have git-debrebase(1) shuffle your branch such that the Debian
356       delta queue appears right at the tip of the branch you will push:
357
358           % git debrebase
359           % dgit push-source
360
361       Note that this will introduce a new pseudomerge.
362
363       After dgit pushing, be sure to git push to salsa.debian.org, if you're
364       using that.
365

HANDLING DFSG-NON-FREE MATERIAL

367   Illegal material
368       Here we explain how to handle material that is merely DFSG-non-free.
369       Material which is legally dangerous (for example, files which are
370       actually illegal) cannot be handled this way.
371
372       If you encounter possibly-legally-dangerous material in the upstream
373       source code you should seek advice.  It is often best not to make a
374       fuss on a public mailing list (at least, not at first).  Instead, email
375       your archive administrators.  For Debian that is
376        To: dgit-owner@debian.org, ftpmaster@ftp-master.debian.org
377
378   DFSG-non-free: When upstream tags releases in git
379       Our approach is to maintain a DFSG-clean upstream branch, and create
380       tags on this branch for each release that we want to import.  We then
381       import those tags per "Importing the release", above.  In the case of a
382       new package, we base our initial Debianisation on our first DFSG-clean
383       tag.
384
385       For the first upstream release that requires DFSG filtering:
386
387           % git checkout -b upstream-dfsg 1.2.3
388           % git rm evil.bin
389           % git commit -m "upstream version 1.2.3 DFSG-cleaned"
390           % git tag -s 1.2.3+dfsg
391           % git checkout master
392
393       Now either proceed with "Importing the release" on the 1.2.3+dfsg tag,
394       or in the case of a new package,
395
396           % git branch --unset-upstream
397           % git reset --hard 1.2.3+dfsg
398
399       and proceed with "INITIAL DEBIANISATION".
400
401       For subsequent releases (whether or not they require additional
402       filtering):
403
404           % git checkout upstream-dfsg
405           % git merge 1.2.4
406           % git rm further-evil.bin # if needed
407           % git commit -m "upstream version 1.2.4 DFSG-cleaned" # if needed
408           % git tag -s 1.2.4+dfsg
409           % git checkout master
410           % # proceed with "Importing the release" on 1.2.4+dfsg tag
411
412       Our upstream-dfsg branch cannot be pushed to dgit-repos, but since we
413       will need it whenever we import a new upstream version, we must push it
414       somewhere.  Assuming that you have already set up an origin remote per
415       the above,
416
417           % git push --follow-tags -u origin master upstream-dfsg
418
419   DFSG-non-free: When upstream releases only tarballs
420       The easiest way to handle this is to add a Files-Excluded field to
421       debian/copyright, and a uversionmangle setting in debian/watch.  See
422       uscan(1).  Alternatively, see the --filter option detailed in
423       gbp-import-orig(1).
424

INCORPORATING NMUS

426       In the simplest case,
427
428           % dgit fetch
429           % git merge --ff-only dgit/dgit/sid
430
431       If that fails, because your branch and the NMUers' work represent
432       divergent branches of development, you have a number of options.  Here
433       we describe the two simplest.
434
435       Note that you should not try to resolve the divergent branches by
436       editing files in debian/patches.  Changes there would either cause
437       trouble, or be overwritten by git-debrebase(1).
438
439   Rebasing your work onto the NMU
440           % git rebase dgit/dgit/sid
441
442       If the NMUer added new commits modifying the upstream source, you will
443       probably want to debrebase before your next upload to tidy those up.
444
445       For example, the NMUer might have used git-revert(1) to unapply one of
446       your patches.  A debrebase can be used to strip both the patch and the
447       reversion from the delta queue.
448
449   Manually applying the debdiff
450       If you cannot rebase because you have already pushed to
451       salsa.debian.org, say, you can manually apply the NMU debdiff, commit
452       and debrebase.  The next dgit push will require --overwrite.
453

HINTS AND TIPS

455   Minimising pseudomerges
456       Above we noted that each time you conclude a debrebase, you introduce a
457       pseudomerge into your git history, which may make it harder to read.
458
459       A simple convention you can use to minimise the number of pseudomerges
460       is to git debrebase conclude only right before you upload or push to
461       salsa.debian.org.
462
463       It is possible, though much less convenient, to reduce the number of
464       pseudomerges yet further.  We debrebase only (i) when importing a new
465       release, and (ii) right before uploading.  Instead of editing the
466       existing delta queue, you append fixup commits (and reversions of
467       commits) that alter the upstream source to the required state.  You can
468       push and pull to and from salsa.debian.org during this.  Just before
469       uploading, you debrebase, once, to tidy everything up.
470
471   The debian/patches directory
472       In this workflow, debian/patches is purely an output of
473       git-debrebase(1).  You should not make changes there.  They will either
474       cause trouble, or be ignored and overwritten by git-debrebase(1).
475
476       debian/patches will often be out-of-date because git-debrebase(1) will
477       only regenerate it when it needs to.  So you should not rely on the
478       information in that directory.  When preparing patches to forward
479       upstream, you should use git-format-patch(1) on git commits, rather
480       than sending files from debian/patches.
481
482   Upstream branches
483       In this workflow, we specify upstream tags rather than any branches.
484
485       Except when (i) upstream releases only tarballs, (ii) we require DFSG
486       filtering, or (iii) you also happen to be involved in upstream
487       development, we do not maintain any local branch corresponding to
488       upstream, except temporary branches used to prepare patches for
489       forwarding, and the like.
490
491       The idea here is that from Debian's point of view, upstream releases
492       are immutable points in history.  We want to make sure that we are
493       basing our Debian package on a properly identified upstream version,
494       rather than some arbitrary commit on some branch.  Tags are more useful
495       for this.
496
497       Upstream's branches remain available as the git remote tracking
498       branches for your upstream remote, e.g. remotes/upstream/master.
499
500   The first ever dgit push
501       If this is the first ever dgit push of the package, consider passing
502       --deliberately-not-fast-forward instead of --overwrite.  This avoids
503       introducing a new origin commit into your git history.  (This origin
504       commit would represent the most recent non-dgit upload of the package,
505       but this should already be represented in your git history.)
506
507   Inspecting the history
508       The git history made by git-debrebase can seem complicated.  Here are
509       some suggestions for helpful invocations of gitk and git.  They can be
510       adapted for other tools like tig(1), git-log(1), magit, etc.
511
512       History of package in Debian, disregarding history from upstream:
513
514           % gitk --first-parent
515
516           In a laundered branch, the delta queue is at the top.
517
518       History of the packaging, excluding the delta queue:
519
520           % gitk :/debian :!/debian/patches
521
522       Just the delta queue (i.e. Debian's changes to upstream):
523
524           % gitk --first-parent -- :/ :!/debian
525
526       Full history including old versions of the delta queue:
527
528           % gitk --date-order
529
530           The "Declare fast forward" commits you see have an older history
531           (usually, an older delta queue) as one parent, and a newer history
532           as the other.  --date-order makes gitk show the delta queues in the
533           right order.
534
535       Complete diff since the last upload:
536
537           % git diff dgit/dgit/sid..HEAD -- :/ :!/debian/patches
538
539           This includes changes to upstream files.
540
541       Interdiff of delta queue since last upload, if you really want it:
542
543           % git debrebase make-patches
544           % git diff dgit/dgit/sid..HEAD -- debian/patches
545
546       And of course there is:
547
548           % git debrebase status
549
550   Alternative ways to start a debrebase
551       Above we started an interactive debrebase by invoking git-debrebase(1)
552       like this:
553
554           % git debrebase -i
555
556       It is also possible to perform a non-interactive rebase, like this:
557
558           % git debrebase -- [git-rebase options...]
559
560       A third alternative is to have git-debrebase(1) shuffle all the Debian
561       changes to the end of your branch, and then manipulate them yourself
562       using git-rebase(1) directly.  For example,
563
564           % git debrebase
565           % git rebase -i HEAD~5      # there are 4 Debian patches
566
567       If you take this approach, you should be very careful not to start the
568       rebase too early, including before the most recent pseudomerge.  git-
569       rebase without a base argument will often start the rebase too early,
570       and should be avoided.  Run git-debrebase instead.  See also "ILLEGAL
571       OPERATIONS" in git-debrebase(5).
572

SEE ALSO

574       dgit(1), dgit(7), git-debrebase(1), git-debrebase(5)
575

AUTHOR

577       This tutorial was written and is maintained by Sean Whitton
578       <spwhitton@spwhitton.name>.  It contains contributions from other dgit
579       contributors too - see the dgit copyright file.
580
581
582
583perl v5.30.1                    Debian Project         dgit-maint-debrebase(7)
Impressum