3 git-debrebase - delta queue rebase tool for Debian packaging
7 git-debrebase [<options...>] [-- <git-rebase options...>]
8 git-debrebase [<options...>] <operation> [<operation options...>
12 git-debrebase is a tool for representing in git,
14 Debian packages based on upstream source code.
16 This is the command line reference.
17 Please read the tutorial
18 L<dgit-maint-debrebase(7)>.
19 For background, theory of operation,
20 and definitions see L<git-debrebase(5)>.
22 You should read this manpage in cojnunction with
23 L<git-debrebase(5)/TERMINOLOGY>,
24 which defines many important terms used here.
26 =head1 PRINCIPAL OPERATIONS
30 =item git-debrebase [-- <git-rebase options...>]
32 =item git-debrebase [-i <further git-rebase options...>]
34 Unstitches and launders the branch.
35 (See L</UNSTITCHING AND LAUNDERING> below.)
37 Then, if any git-rebase options were supplied,
38 edits the Debian delta queue,
39 using git-rebase, by running
41 git rebase <git-rebase options> <breakwater-tip>
43 Do not pass a base branch argument:
44 git-debrebase will supply that.
45 Do not use --onto, or --fork-point.
46 Useful git-rebase options include -i and --autosquash.
48 If git-rebase stops for any reason,
49 you may git-rebase --abort, --continue, or --skip, as usual.
50 If you abort the git-rebase,
51 the branch will still have been laundered,
52 but everything in the rebase will be undone.
54 The options for git-rebase must either start with C<-i>,
55 or be prececded by C<-->,
56 to distinguish them from options for git-debrebase.
58 It is hazardous to use plain git-rebase on a git-debrebase branch,
59 because git-rebase has a tendency to start the rebase
60 too far back in history,
61 and then drop important commits.
62 Soo L<git-debrebase(5)/ILLEGAL OPERATIONS>
64 =item git-debrebase status
66 Analyses the current branch,
67 both in terms of its contents,
68 and the refs which are relevant to git-debrebase,
69 and prints a human-readable summary.
71 Please do not attempt to parse the output;
72 it may be reformatted or reorganised in the future.
74 use one of the L<UNDERLYING AND SUPPLEMENTARY OPERATIONS>
77 =item git-debrebase conclude
79 Finishes a git-debrebase session,
80 tidying up the branch and making it fast forward again.
82 Specifically: if the branch is unstitched,
83 launders and restitches it,
84 making a new pseudomerge.
85 Otherwise, it is an error,
88 =item git-debrebase quick
90 Unconditionally launders and restitches the branch,
91 consuming any ffq-prev
92 and making a new pseudomerge.
94 If the branch is already laundered and stitched, does nothing.
96 =item git-debrebase prepush [--prose=<for commit message>]
98 =item git-debrebase stitch [--prose=<for commit message>]
102 This is a good command to run before pushing to a git server.
104 If there is no ffq-prev, it is an error, unless --noop-ok.
106 You should consider using B<conclude> instead,
107 because that launders the branch too.
109 =item git-debrebase scrap
111 Throws away all the work since the branch was last stitched.
112 This is done by rewinding you to ffq-prev.
114 If you are in the middle of a git-rebase, will abort that too.
116 =item git-debrebase new-upstream <new-version> [<upstream-details>...]
118 Rebases the delta queue
119 onto a new upstream version. In detail:
121 Firstly, checks that the proposed rebase seems to make sense:
122 It is a snag unless the new upstream(s)
123 are fast forward from the previous upstream(s)
124 as found in the current breakwater anchor.
125 And, in the case of a multi-piece upstream
126 (a multi-component upstream, in dpkg-source terminology),
127 if the pieces are not in the same order, with the same names.
129 If all seems well, unstitches and launders the branch.
133 (in a private working area)
134 a new anchor merge commit,
135 on top of the breakwater tip,
136 and on top of that a commit to
137 update the version number in debian/changelog.
141 of the delta queue onto these new commits.
143 That git-rebase may complete successfully,
144 or it may require your assistance,
145 just like a normal git-rebase.
147 If you git-rebase --abort,
148 the whole new upstream operation is aborted,
149 except for the laundering.
152 may be whole new Debian version, including revision,
153 or just the upstream part,
154 in which case -1 will be appended
155 to make the new Debian version.
157 The <upstream-details> are, optionally, in order:
161 =item <upstream-commit-ish>
163 The new upstream branch (or commit-ish).
164 The default is to look for one of these tags, in this order:
166 where U is the new upstream version.
167 (This is the same algorithm as L<git-deborig(1)>.)
169 It is a snag if the upstream contains a debian/ directory;
170 if forced to proceed,
171 git-debrebase will disregard the upstream's debian/ and
172 take (only) the packaging from the current breakwater.
174 =item <piece-name> <piece-upstream-commit-ish>
176 Specifies that this is a multi-piece upstream.
179 When such a pair is specified,
180 git-debrebase will first combine the pieces of the upstream
182 and then use the result as the combined new upstream.
184 For each <piece-name>,
185 the tree of the <piece-upstream-commit-ish>
186 becomes the subdirectory <piece-name>
187 in the combined new upstream
188 (supplanting any subdirectory that might be there in
189 the main upstream branch).
191 <piece-name> has a restricted syntax:
192 it may contain only ASCII alphanumerics and hyphens.
194 The combined upstream is itself recorded as a commit,
195 with each of the upstream pieces' commits as parents.
196 The combined commit contains an annotation
197 to allow a future git-debrebase new upstream operation
198 to make the coherency checks described above.
200 =item <git-rebase options>
202 These will be passed to git rebase.
204 If the upstream rebase is troublesome, -i may be helpful.
205 As with plain git-debrebase,
206 do not specify a base, or --onto, or --fork-point.
210 If you are planning to generate a .dsc,
211 you will also need to have, or generate,
212 actual orig tarball(s),
213 which must be identical to the rev-spec(s)
214 passed to git-debrebase.
215 git-debrebase does not concern itself with source packages
216 so neither helps with this, nor checks it.
218 L<git-archive(1)>, L<dgit(1)> and
219 L<gbp-import-orig(1)> may be able to help.
221 =item git-debrebase make-patches [--quiet-would-amend]
223 Generate patches in debian/patches/
224 representing the changes made to upstream files.
226 It is not normally necessary to run this command explicitly.
227 When uploading to Debian,
228 dgit and git-debrebase
229 will cooperate to regenerate patches as necessary.
230 When working with pure git remotes,
231 the patches are not needed.
233 Normally git-debrebase make-patches will
234 require a laundered branch.
235 (A laundered branch does not contain any patches.)
236 But if there are already some patches made by
237 git-debrebase make-patches,
238 and all that has happened is that more
239 changes to upstream files have been committed,
240 running it again can add the missing patches.
242 If the patches implied by the current branch
243 are not a simple superset of those already in debian/patches,
244 make-patches will fail with exit status 7,
245 and an error message.
246 (The message can be suppress with --quiet-would-amend.)
247 If the problem is simply that
248 the existing patches were not made by git-debrebase,
249 using dgit quilt-fixup instead should succeed.
251 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
253 Cnnverts a gbp patches-unapplied branch
254 (not a gbp pq patch queue branch)
255 into a git-debrebase interchange branch.
257 This is done by generating a new anchor merge,
258 converting the quilt patches as a delta queue,
259 and dropping the patches from the tree.
261 The upstream commit-ish should correspond to
262 the gbp upstream branch, if there is one.
263 It is a snag if it is not an ancestor of HEAD,
264 or if the history between the upstream and HEAD
265 contains commits which make changes to upstream files.
266 If it is not specified,
267 the same algorithm is used as for git-debrebase new-upstream.
269 It is also a snag if the specified upstream
270 has a debian/ subdirectory.
271 This check exists to detect certain likely user errors,
272 but if this situation is true and expected,
275 git-debrebase will try to look for the dgit archive view
276 of the most recent release,
277 and if it finds it will make a pseduomerge so that
278 your new git-debrebase view is appropriately fast forward.
280 The result is a well-formed git-debrebase interchange branch.
281 The result is also fast-forward from the gbp branch.
283 It is a snag if the new branch looks like it will have diverged,
284 just as for a laundering/unstitching call to git-debrebase;
285 See L</Establish the current branch's ffq-prev>, below.
287 Note that it is dangerous not to know whether you are
288 dealing with a gbp patches-unapplied branch containing quilt patches,
289 or a git-debrebase interchange branch.
291 using the wrong tool for the branch format might result in
292 a dropped patch queue!
296 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
300 =item git-debrebase breakwater
302 Prints the breakwater tip commitid.
303 If your HEAD branch is not fully laundered,
304 prints the tip of the so-far-laundered breakwater.
306 =item git-debrebase anchor
308 Prints the breakwater anchor commitid.
310 =item git-debrebase analyse
312 Walks the history of the current branch,
313 most recent commit first,
314 back until the most recent anchor,
315 printing the commit object id,
316 and commit type and info
317 (ie the semantics in the git-debrebase model)
320 =item git-debrebase record-ffq-prev
322 Establishes the current branch's ffq-prev,
323 as discussed in L</UNSTITCHING AND LAUNDERING>,
324 but does not launder the branch or move HEAD.
326 It is an error if the ffq-prev could not be recorded.
327 It is also an error if an ffq-prev has already been recorded,
330 =item git-debrebase launder-v0
332 Launders the branch without recording anything in ffq-prev.
333 Then prints some information about the current branch.
334 Do not use this operation;
335 it will be withdrawn soon.
337 =item git-debrebase convert-to-gbp
339 Converts a laundered branch into a
340 gbp patches-unapplied branch containing quilt patches.
341 The result is not fast forward from the interchange branch,
342 and any ffq-prev is deleted.
344 This is provided mostly for the test suite
345 and for unusual situations.
346 It should only be used with a care and
347 with a proper understanding of the underlying theory.
349 Be sure to not accidentally treat the result as
350 a git-debrebase branch,
351 or you will drop all the patches!
353 =item git-debrebase convert-from-dgit-view [<convert-options>] [upstream]
355 Converts any dgit-compatible git branch
356 corresponding to a (possibly hypothetical) 3.0 quilt dsc source package
357 into a git-debrebase-compatible branch.
359 This operation should not be used
360 if the branch is already in git-debrebase form.
361 Normally git-debrebase will refuse to continue in this case
362 (or silently do nothing if the global --noop-ok option is used).
364 Some representation of the original upstream source code will be needed.
365 If I<upstream> is supplied, that must be a suitable upstream commit.
367 git-debrebase will look first for git tags (as for new-upstream),
368 and then for orig tarballs which it will ask dgit to process.
370 The upstream source must be exactly right and
371 all the patches in debian/patches must be up to date.
372 Applying the patches from debian/patches to the upstream source
373 must result in exactly your HEAD.
375 The output is laundered and stitched.
376 The resulting history is not particularly pretty,
377 especially if orig tarball(s) were imported
378 to produce a synthetic upstream commit.
380 The available convert-options are as follows.
381 (These must come after convert-from-dgit-view.)
385 =item --[no-]diagnose
387 Print additional error messages to help diagnose
388 failure to find an appropriate upstream.
389 --no-diagnose is the default.
391 =item --build-products-dir
393 Directory to look in for orig tarballs.
394 The default is the git config option
395 dgit.default.build-products-dir
396 or failing that, C<..>.
397 Passed on to dgit, if git-debrebase invokes dgit.
401 Whether to try to look for or use any orig tarballs.
402 --origs is the default.
406 Whether to try to look for or use any upstream git tags.
407 --tags is the default.
409 =item --always-convert-anyway
411 Perform the conversion operation,
412 producing unpleasant extra history,
413 even if the branch seems to be in git-debrebase form already.
414 This should not be done unless necessary,
415 and it should not be necessary.
423 This section documents the general options
425 (ie, the ones which immediately follow
429 on the command line).
430 Individual operations may have their own options which are
431 docuented under each operation.
437 Turns snag(s) with id <snag-id> into warnings.
439 Some troublesome things which git-debrebase encounters
441 (The specific instances are discussed
442 in the text for the relevant operation.)
444 When a snag is detected,
445 a message is printed to stderr containing the snag id
446 (in the form C<-f<snag-idE<gt>>),
447 along with some prose.
449 If snags are detected, git-debrebase does not continue,
450 unless the relevant -f<snag-id> is specified,
451 or --force is specified.
455 Turns all snags into warnings.
456 See the -f<snag-id> option.
458 Do not invoke git-debrebase --force in scripts and aliases;
459 instead, specify the particular -f<snag-id> for expected snags.
463 Suppresses the error in
464 some situations where git-debrebase does nothing,
465 because there is nothing to do.
467 The specific instances are discussed
468 in the text for the relvant operation.
470 =item --anchor=<commit-ish>
472 Treats <commit-ish> as an anchor.
473 This overrides the usual logic which automatically classifies
474 commits as anchors, pseudomerges, delta queue commits, etc.
476 It also disables some coherency checks
477 which depend on metadata extracted from its commit message,
479 it is a snag if <commit-ish> is the anchor
480 for the previous upstream version in
481 git-debrebase new-upstream operations.
483 =item --dgit=<program>
485 Run <program>, instead of dgit from PATH,
486 when invocation of dgit is necessary.
487 This is provided mostly for the benefit of the test suite.
491 Requests (more) debugging. May be repeated.
495 =head1 UNSTITCHING AND LAUNDERING
497 Several operations unstitch and launder the branch first.
498 In detail this means:
500 =head2 Establish the current branch's ffq-prev
502 If ffq-prev is not yet recorded,
503 git-debrebase checks that the current branch is ahead of relevant
504 remote tracking branches.
505 The relevant branches depend on
506 the current branch (and its
514 The branch that git would merge from
515 (remote.<branch>.merge, remote.<branch>.remote);
519 The branch git would push to, if different
520 (remote.<branch>.pushRemote etc.);
524 For local dgit suite branches,
525 the corresponding tracking remote;
529 If you are on C<master>,
530 remotes/dgit/dgit/sid.
534 The apparently relevant ref names to check are filtered through
535 branch.<branch>.ffq-ffrefs,
536 which is a semicolon-separated list of glob patterns,
537 each optionally preceded by !; first match wins.
539 In each case it is a snag if
540 the local HEAD is behind the checked remote,
541 or if local HEAD has diverged from it.
542 All the checks are done locally using the remote tracking refs:
543 git-debrebase does not fetch anything from anywhere.
545 If these checks pass,
547 git-debrebse then records the current tip as ffq-prev.
549 =head2 Examine the branch
552 analyses the current HEAD's history to find the anchor
554 and the most recent breakwater tip.
556 =head2 Rewrite the commits into laundered form
558 Mixed debian+upstream commits are split into two commits each.
559 Delta queue (upstream files) commits bubble to the top.
561 and quilt patch additions,
564 This rewrite will always succeed, by construction.
565 The result is the laundered branch.
570 dgit-maint-rebase(7),