3 git-debrebase - tool to maintain series of Debian changes to upstream source
7 git-debrebase [<options...>] [-- <git-rebase options...>]
8 git-debrebase [<options...>] <operation> [<operation options...>
10 =head1 QUICK REFERENCE
12 These are most of the commands you will regularly need:
14 git debrebase -i # edit the patch queue
15 git debrebase conclude && git push # push to eg salsa
16 git debrebase conclude && dgit push-source # source-only upload
17 git debrebase [-i] new-upstream 1.2.3-1 # uses tag, eg "v1.2.3"
18 dpkg-buildpackage -uc -b # get test debs, at any time
20 To add patches, or edit the packaging, just make git commits.
21 Ignore anything that may appear in debian/patches.
22 Avoid using "git pull" and "git merge" without "--ff-only".
24 git-debrebase has a special branch format, so see
25 "CONVERTING AN EXISTING PACKAGE" in L<dgit-maint-debrebase(7)>.
27 =head1 GUIDE TO DOCUMENTATION
29 This is the command line reference.
30 There is also a detailed workflow tutorial at
31 L<dgit-maint-debrebase(7)>
32 (on which the above "QUICK REFERENCE" is based).
33 For background, theory of operation,
34 and definitions see L<git-debrebase(5)>.
36 You should read this manpage in conjunction with
37 L<git-debrebase(5)/TERMINOLOGY>,
38 which defines many important terms used here.
40 =head1 PRINCIPAL OPERATIONS
44 =item git-debrebase [-- <git-rebase options...>]
46 =item git-debrebase [-i <further git-rebase options...>]
48 Unstitches and launders the branch.
49 (See L</UNSTITCHING AND LAUNDERING> below.)
51 Then, if any git-rebase options were supplied,
52 edits the Debian delta queue,
53 using git-rebase, by running
55 git rebase <git-rebase options> <breakwater-tip>
57 Do not pass a base branch argument:
58 git-debrebase will supply that.
59 Do not use --onto, or --fork-point.
60 Useful git-rebase options include -i and --autosquash.
62 If git-rebase stops for any reason,
63 you may git-rebase --abort, --continue, or --skip, as usual.
64 If you abort the git-rebase,
65 the branch will still have been laundered,
66 but everything in the rebase will be undone.
68 The options for git-rebase must either start with C<-i>,
69 or be prececded by C<-->,
70 to distinguish them from options for git-debrebase.
72 It is hazardous to use plain git-rebase on a git-debrebase branch,
73 because git-rebase has a tendency to start the rebase
74 too far back in history,
75 and then drop important commits.
76 See L<git-debrebase(5)/ILLEGAL OPERATIONS>
78 =item git-debrebase status
80 Analyses the current branch,
81 both in terms of its contents,
82 and the refs which are relevant to git-debrebase,
83 and prints a human-readable summary.
85 Please do not attempt to parse the output;
86 it may be reformatted or reorganised in the future.
88 use one of the L<UNDERLYING AND SUPPLEMENTARY OPERATIONS>
91 =item git-debrebase conclude
93 Finishes a git-debrebase session,
94 tidying up the branch and making it fast forward again.
96 Specifically: if the branch is unstitched,
97 launders and restitches it,
98 making a new pseudomerge.
99 Otherwise, it is an error,
102 =item git-debrebase quick
104 Unconditionally launders and restitches the branch,
105 consuming any ffq-prev
106 and making a new pseudomerge.
108 If the branch is already laundered and stitched, does nothing.
110 =item git-debrebase prepush [--prose=<for commit message>]
112 If the branch is unstitched,
116 This is a good command to run before pushing to a git server.
117 You should consider using B<conclude> instead,
118 because that launders the branch too.
120 =item git-debrebase stitch [--prose=<for commit message>]
125 If there is no ffq-prev, it is an error, unless --noop-ok.
127 You should consider using B<prepush> or B<conclude> instead.
129 =item git-debrebase scrap
131 Throws away all the work since the branch was last stitched.
132 This is done by resetting you to ffq-prev
133 and discarding all working tree changes.
135 If you are in the middle of a git-rebase, will abort that too.
137 =item git-debrebase new-upstream <new-version> [<upstream-details>...]
139 Rebases the delta queue
140 onto a new upstream version. In detail:
142 Firstly, checks that the proposed rebase seems to make sense:
143 It is a snag unless the new upstream(s)
144 are fast forward from the previous upstream(s)
145 as found in the current breakwater anchor.
146 And, in the case of a multi-piece upstream
147 (a multi-component upstream, in dpkg-source terminology),
148 if the pieces are not in the same order, with the same names.
150 If all seems well, unstitches and launders the branch.
154 (in a private working area)
155 a new anchor merge commit,
156 on top of the breakwater tip,
157 and on top of that a commit to
158 update the version number in debian/changelog.
162 of the delta queue onto these new commits.
164 That git-rebase may complete successfully,
165 or it may require your assistance,
166 just like a normal git-rebase.
168 If you git-rebase --abort,
169 the whole new upstream operation is aborted,
170 except for the laundering.
173 may be a whole new Debian version, including revision,
174 or just the upstream part,
175 in which case -1 will be appended
176 to make the new Debian version.
178 The <upstream-details> are, optionally, in order:
182 =item <upstream-commit-ish>
184 The new upstream branch (or commit-ish).
185 The default is to look for one of these tags, in this order:
187 where U is the new upstream version.
188 (This is the same algorithm as L<git-deborig(1)>.)
190 It is a snag if the upstream contains a debian/ directory;
191 if forced to proceed,
192 git-debrebase will disregard the upstream's debian/ and
193 take (only) the packaging from the current breakwater.
195 =item <piece-name> <piece-upstream-commit-ish>
197 Specifies that this is a multi-piece upstream.
200 When such a pair is specified,
201 git-debrebase will first combine the pieces of the upstream
203 and then use the result as the combined new upstream.
205 For each <piece-name>,
206 the tree of the <piece-upstream-commit-ish>
207 becomes the subdirectory <piece-name>
208 in the combined new upstream
209 (supplanting any subdirectory that might be there in
210 the main upstream branch).
212 <piece-name> has a restricted syntax:
213 it may contain only ASCII alphanumerics and hyphens.
215 The combined upstream is itself recorded as a commit,
216 with each of the upstream pieces' commits as parents.
217 The combined commit contains an annotation
218 to allow a future git-debrebase new upstream operation
219 to make the coherency checks described above.
221 =item <git-rebase options>
223 These will be passed to git rebase.
225 If the upstream rebase is troublesome, -i may be helpful.
226 As with plain git-debrebase,
227 do not specify a base, or --onto, or --fork-point.
231 If you are planning to generate a .dsc,
232 you will also need to have, or generate,
233 actual orig tarball(s),
234 which must be identical to the rev-spec(s)
235 passed to git-debrebase.
236 git-debrebase does not concern itself with source packages
237 so neither helps with this, nor checks it.
239 L<git-archive(1)>, L<dgit(1)> and
240 L<gbp-import-orig(1)> may be able to help.
242 =item git-debrebase make-patches [--quiet-would-amend]
244 Generate patches in debian/patches/
245 representing the changes made to upstream files.
247 It is not normally necessary to run this command explicitly.
248 When uploading to Debian,
249 dgit and git-debrebase
250 will cooperate to regenerate patches as necessary.
251 When working with pure git remotes,
252 the patches are not needed.
254 Normally git-debrebase make-patches will
255 require a laundered branch.
256 (A laundered branch does not contain any patches.)
257 But if there are already some patches made by
258 git-debrebase make-patches,
259 and all that has happened is that more
260 changes to upstream files have been committed,
261 running it again can add the missing patches.
263 If the patches implied by the current branch
264 are not a simple superset of those already in debian/patches,
265 make-patches will fail with exit status 7,
266 and an error message.
267 (The message can be suppressed with --quiet-would-amend.)
268 If the problem is simply that
269 the existing patches were not made by git-debrebase,
270 using dgit quilt-fixup instead should succeed.
272 =item git-debrebase convert-from-unapplied [<upstream-commit-ish>]
274 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
276 Converts any of the following into a git-debrebase interchange branch:
282 a gbp patches-unapplied branch (but not a gbp pq patch-queue branch)
286 a patches-unapplied git packaging branch containing debian/patches,
291 a git branch for a package which has no Debian delta -
292 ie where upstream files are have not been modified in Debian,
293 so there are no patches
297 (These two commands operate identically and are simply aliases.)
299 The conversion is done by generating a new anchor merge,
300 converting any quilt patches as a delta queue,
301 and dropping the patches from the tree.
303 The upstream commit-ish should correspond to
304 the upstream branch or tag, if there is one.
305 It is a snag if it is not an ancestor of HEAD,
306 or if the history between the upstream and HEAD
307 contains commits which make changes to upstream files.
308 If it is not specified,
309 the same algorithm is used as for git-debrebase new-upstream.
311 It is also a snag if the specified upstream
312 has a debian/ subdirectory.
313 This check exists to detect certain likely user errors,
314 but if this situation is true and expected,
317 git-debrebase will try to look for the dgit archive view
318 of the most recent release,
319 and if it finds it will make a pseduomerge so that
320 your new git-debrebase view is appropriately fast forward.
322 The result is a well-formed git-debrebase interchange branch.
323 The result is also fast-forward from the original branch.
325 It is a snag if the new branch looks like it will have diverged,
326 just as for a laundering/unstitching call to git-debrebase;
327 See L</Establish the current branch's ffq-prev>, below.
329 Note that it is dangerous not to know whether you are
330 dealing with a (gbp) patches-unapplied branch containing quilt patches,
331 or a git-debrebase interchange branch.
333 using the wrong tool for the branch format might result in
334 a dropped patch queue!
338 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
342 =item git-debrebase breakwater
344 Prints the breakwater tip commitid.
345 If your HEAD branch is not fully laundered,
346 prints the tip of the so-far-laundered breakwater.
348 =item git-debrebase anchor
350 Prints the breakwater anchor commitid.
352 =item git-debrebase analyse
354 Walks the history of the current branch,
355 most recent commit first,
356 back until the most recent anchor,
357 printing the commit object id,
358 and commit type and info
359 (ie the semantics in the git-debrebase model)
362 =item git-debrebase record-ffq-prev
364 Establishes the current branch's ffq-prev,
365 as discussed in L</UNSTITCHING AND LAUNDERING>,
366 but does not launder the branch or move HEAD.
368 It is an error if the ffq-prev could not be recorded.
369 It is also an error if an ffq-prev has already been recorded,
372 =item git-debrebase launder-v0
374 Launders the branch without recording anything in ffq-prev.
375 Then prints some information about the current branch.
376 Do not use this operation;
377 it will be withdrawn soon.
379 =item git-debrebase convert-to-gbp
381 Converts a laundered branch into a
382 gbp patches-unapplied branch containing quilt patches.
383 The result is not fast forward from the interchange branch,
384 and any ffq-prev is deleted.
386 This is provided mostly for the test suite
387 and for unusual situations.
388 It should only be used with care and
389 with a proper understanding of the underlying theory.
391 Be sure to not accidentally treat the result as
392 a git-debrebase branch,
393 or you will drop all the patches!
395 =item git-debrebase convert-from-dgit-view [<convert-options>] [upstream]
397 Converts any dgit-compatible git branch
398 corresponding to a (possibly hypothetical) 3.0 quilt dsc source package
399 into a git-debrebase-compatible branch.
401 This operation should not be used
402 if the branch is already in git-debrebase form.
403 Normally git-debrebase will refuse to continue in this case
404 (or silently do nothing if the global --noop-ok option is used).
406 Some representation of the original upstream source code will be needed.
407 If I<upstream> is supplied, that must be a suitable upstream commit.
409 git-debrebase will look first for git tags (as for new-upstream),
410 and then for orig tarballs which it will ask dgit to process.
412 The upstream source must be exactly right and
413 all the patches in debian/patches must be up to date.
414 Applying the patches from debian/patches to the upstream source
415 must result in exactly your HEAD.
417 The output is laundered and stitched.
418 The resulting history is not particularly pretty,
419 especially if orig tarball(s) were imported
420 to produce a synthetic upstream commit.
422 The available convert-options are as follows.
423 (These must come after convert-from-dgit-view.)
427 =item --[no-]diagnose
429 Print additional error messages to help diagnose
430 failure to find an appropriate upstream.
431 --no-diagnose is the default.
433 =item --build-products-dir
435 Directory to look in for orig tarballs.
436 The default is the git config option
437 dgit.default.build-products-dir
438 or failing that, C<..>.
439 Passed on to dgit, if git-debrebase invokes dgit.
443 Whether to try to look for or use any orig tarballs.
444 --origs is the default.
448 Whether to try to look for or use any upstream git tags.
449 --tags is the default.
451 =item --always-convert-anyway
453 Perform the conversion operation,
454 producing unpleasant extra history,
455 even if the branch seems to be in git-debrebase form already.
456 This should not be done unless necessary,
457 and it should not be necessary.
461 =item git-debrebase forget-was-ever-debrebase
463 Deletes the ffq-prev and debrebase-last refs
464 associated with this branch,
465 that git-debrebase and dgit use to determine
466 whether this branch is managed by git-debrebase,
467 and what previous head may need to be stitched back in.
469 This can be useful if you were just playing with git-debrebase,
470 and have used git-reset --hard to go back to a commit
471 before your experiments.
473 Do not use this if you expect to run git-debrebase on the branch again.
479 This section documents the general options
481 (ie, the ones which immediately follow
485 on the command line).
486 Individual operations may have their own options which are
487 docuented under each operation.
493 Turns snag(s) with id <snag-id> into warnings.
495 Some troublesome things which git-debrebase encounters
497 (The specific instances are discussed
498 in the text for the relevant operation.)
500 When a snag is detected,
501 a message is printed to stderr containing the snag id
502 (in the form C<-f<snag-idE<gt>>),
503 along with some prose.
505 If snags are detected, git-debrebase does not continue,
506 unless the relevant -f<snag-id> is specified,
507 or --force is specified.
511 Turns all snags into warnings.
512 See the -f<snag-id> option.
514 Do not invoke git-debrebase --force in scripts and aliases;
515 instead, specify the particular -f<snag-id> for expected snags.
519 Suppresses the error in
520 some situations where git-debrebase does nothing,
521 because there is nothing to do.
523 The specific instances are discussed
524 in the text for the relvant operation.
526 =item --anchor=<commit-ish>
528 Treats <commit-ish> as an anchor.
529 This overrides the usual logic which automatically classifies
530 commits as anchors, pseudomerges, delta queue commits, etc.
532 It also disables some coherency checks
533 which depend on metadata extracted from its commit message,
535 it is a snag if <commit-ish> is the anchor
536 for the previous upstream version in
537 git-debrebase new-upstream operations.
539 =item --dgit=<program>
541 Run <program>, instead of dgit from PATH,
542 when invocation of dgit is necessary.
543 This is provided mostly for the benefit of the test suite.
547 Requests (more) debugging. May be repeated.
549 =item --experimental-merge-resolution
551 Enable experimental code for handling general merges
552 (see L<git-debrebase(5)/General merges>).
554 This option may generate lossage of various kinds,
555 including misleading error messages,
556 references to nonexistent documentation, and
557 you being handed an incomprehensible pile of
558 multidimensional merge wreckage.
562 =head1 UNSTITCHING AND LAUNDERING
564 Several operations unstitch and launder the branch first.
565 In detail this means:
567 =head2 Establish the current branch's ffq-prev
569 If ffq-prev is not yet recorded,
570 git-debrebase checks that the current branch is ahead of relevant
571 remote tracking branches.
572 The relevant branches depend on
573 the current branch (and its
581 The branch that git would merge from
582 (remote.<branch>.merge, remote.<branch>.remote);
586 The branch git would push to, if different
587 (remote.<branch>.pushRemote etc.);
591 For local dgit suite branches,
592 the corresponding tracking remote;
596 If you are on C<master>,
597 remotes/dgit/dgit/sid.
601 The apparently relevant ref names to check are filtered through
602 branch.<branch>.ffq-ffrefs,
603 which is a semicolon-separated list of glob patterns,
604 each optionally preceded by !; first match wins.
606 In each case it is a snag if
607 the local HEAD is behind the checked remote,
608 or if local HEAD has diverged from it.
609 All the checks are done locally using the remote tracking refs:
610 git-debrebase does not fetch anything from anywhere.
612 If these checks pass,
614 git-debrebse then records the current tip as ffq-prev.
616 =head2 Examine the branch
619 analyses the current HEAD's history to find the anchor
621 and the most recent breakwater tip.
623 =head2 Rewrite the commits into laundered form
625 Mixed debian+upstream commits are split into two commits each.
626 Delta queue (upstream files) commits bubble to the top.
628 and quilt patch additions,
631 This rewrite will always succeed, by construction.
632 The result is the laundered branch.
637 dgit-maint-debrebase(7),