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 new-upstream <new-version> [<upstream-details>...]
111 Rebases the delta queue
112 onto a new upstream version. In detail:
114 Firstly, checks that the proposed rebase seems to make sense:
115 It is a snag unless the new upstream(s)
116 are fast forward from the previous upstream(s)
117 as found in the current breakwater anchor.
118 And, in the case of a multi-piece upstream
119 (a multi-component upstream, in dpkg-source terminology),
120 if the pieces are not in the same order, with the same names.
122 If all seems well, unstitches and launders the branch.
126 (in a private working area)
127 a new anchor merge commit,
128 on top of the breakwater tip,
129 and on top of that a commit to
130 update the version number in debian/changelog.
134 of the delta queue onto these new commits.
136 That git-rebase may complete successfully,
137 or it may require your assistance,
138 just like a normal git-rebase.
140 If you git-rebase --abort,
141 the whole new upstream operation is aborted,
142 except for the laundering.
145 may be whole new Debian version, including revision,
146 or just the upstream part,
147 in which case -1 will be appended
148 to make the new Debian version.
150 The <upstream-details> are, optionally, in order:
154 =item <upstream-commit-ish>
156 The new upstream branch (or commit-ish).
157 The default is to look for one of these tags, in this order:
159 where U is the new upstream version.
160 (This is the same algorithm as L<git-deborig(1)>.)
162 It is a snag if the upstream contains a debian/ directory;
163 if forced to proceed,
164 git-debrebase will disregard the upstream's debian/ and
165 take (only) the packaging from the current breakwater.
167 =item <piece-name> <piece-upstream-commit-ish>
169 Specifies that this is a multi-piece upstream.
172 When such a pair is specified,
173 git-debrebase will first combine the pieces of the upstream
175 and then use the result as the combined new upstream.
177 For each <piece-name>,
178 the tree of the <piece-upstream-commit-ish>
179 becomes the subdirectory <piece-name>
180 in the combined new upstream
181 (supplanting any subdirectory that might be there in
182 the main upstream branch).
184 <piece-name> has a restricted syntax:
185 it may contain only ASCII alphanumerics and hyphens.
187 The combined upstream is itself recorded as a commit,
188 with each of the upstream pieces' commits as parents.
189 The combined commit contains an annotation
190 to allow a future git-debrebase new upstream operation
191 to make the coherency checks described above.
193 =item <git-rebase options>
195 These will be passed to git rebase.
197 If the upstream rebase is troublesome, -i may be helpful.
198 As with plain git-debrebase,
199 do not specify a base, or --onto, or --fork-point.
203 If you are planning to generate a .dsc,
204 you will also need to have, or generate,
205 actual orig tarball(s),
206 which must be identical to the rev-spec(s)
207 passed to git-debrebase.
208 git-debrebase does not concern itself with source packages
209 so neither helps with this, nor checks it.
211 L<git-archive(1)>, L<dgit(1)> and
212 L<gbp-import-orig(1)> may be able to help.
214 =item git-debrebase make-patches [--quiet-would-amend]
216 Generate patches in debian/patches/
217 representing the changes made to upstream files.
219 It is not normally necessary to run this command explicitly.
220 When uploading to Debian,
221 dgit and git-debrebase
222 will cooperate to regenerate patches as necessary.
223 When working with pure git remotes,
224 the patches are not needed.
226 Normally git-debrebase make-patches will
227 require a laundered branch.
228 (A laundered branch does not contain any patches.)
229 But if there are already some patches made by
230 git-debrebase make-patches,
231 and all that has happened is that more
232 changes to upstream files have been committed,
233 running it again can add the missing patches.
235 If the patches implied by the current branch
236 are not a simple superset of those already in debian/patches,
237 make-patches will fail with exit status 7,
238 and an error message.
239 (The message can be suppress with --quiet-would-amend.)
240 If the problem is simply that
241 the existing patches were not made by git-debrebase,
242 using dgit quilt-fixup instead should succeed.
244 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
246 Cnnverts a gbp patches-unapplied branch
247 (not a gbp pq patch queue branch)
248 into a git-debrebase interchange branch.
250 This is done by generating a new anchor merge,
251 converting the quilt patches as a delta queue,
252 and dropping the patches from the tree.
254 The upstream commit-ish should correspond to
255 the gbp upstream branch, if there is one.
256 It is a snag if it is not an ancestor of HEAD,
257 or if the history between the upstream and HEAD
258 contains commits which make changes to upstream files.
259 If it is not specified,
260 the same algorithm is used as for git-debrebase new-upstream.
262 It is also a snag if the specified upstream
263 has a debian/ subdirectory.
264 This check exists to detect certain likely user errors,
265 but if this situation is true and expected,
268 git-debrebase will try to look for the dgit archive view
269 of the most recent release,
270 and if it finds it will make a pseduomerge so that
271 your new git-debrebase view is appropriately fast forward.
273 The result is a well-formed git-debrebase interchange branch.
274 The result is also fast-forward from the gbp branch.
276 It is a snag if the new branch looks like it will have diverged,
277 just as for a laundering/unstitching call to git-debrebase;
278 See L</Establish the current branch's ffq-prev>, below.
280 Note that it is dangerous not to know whether you are
281 dealing with a gbp patches-unapplied branch containing quilt patches,
282 or a git-debrebase interchange branch.
284 using the wrong tool for the branch format might result in
285 a dropped patch queue!
289 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
293 =item git-debrebase breakwater
295 Prints the breakwater tip commitid.
296 If your HEAD branch is not fully laundered,
297 prints the tip of the so-far-laundered breakwater.
299 =item git-debrebase anchor
301 Prints the breakwater anchor commitid.
303 =item git-debrebase analyse
305 Walks the history of the current branch,
306 most recent commit first,
307 back until the most recent anchor,
308 printing the commit object id,
309 and commit type and info
310 (ie the semantics in the git-debrebase model)
313 =item git-debrebase record-ffq-prev
315 Establishes the current branch's ffq-prev,
316 as discussed in L</UNSTITCHING AND LAUNDERING>,
317 but does not launder the branch or move HEAD.
319 It is an error if the ffq-prev could not be recorded.
320 It is also an error if an ffq-prev has already been recorded,
323 =item git-debrebase launder-v0
325 Launders the branch without recording anything in ffq-prev.
326 Then prints some information about the current branch.
327 Do not use this operation;
328 it will be withdrawn soon.
330 =item git-debrebase convert-to-gbp
332 Converts a laundered branch into a
333 gbp patches-unapplied branch containing quilt patches.
334 The result is not fast forward from the interchange branch,
335 and any ffq-prev is deleted.
337 This is provided mostly for the test suite
338 and for unusual situations.
339 It should only be used with a care and
340 with a proper understanding of the underlying theory.
342 Be sure to not accidentally treat the result as
343 a git-debrebase branch,
344 or you will drop all the patches!
350 This section documents the general options
352 (ie, the ones which immediately follow
356 on the command line).
357 Individual operations may have their own options which are
358 docuented under each operation.
364 Turns snag(s) with id <snag-id> into warnings.
366 Some troublesome things which git-debrebase encounters
368 (The specific instances are discussed
369 in the text for the relevant operation.)
371 When a snag is detected,
372 a message is printed to stderr containing the snag id
373 (in the form C<-f<snag-idE<gt>>),
374 along with some prose.
376 If snags are detected, git-debrebase does not continue,
377 unless the relevant -f<snag-id> is specified,
378 or --force is specified.
382 Turns all snags into warnings.
383 See the -f<snag-id> option.
385 Do not invoke git-debrebase --force in scripts and aliases;
386 instead, specify the particular -f<snag-id> for expected snags.
390 Suppresses the error in
391 some situations where git-debrebase does nothing,
392 because there is nothing to do.
394 The specific instances are discussed
395 in the text for the relvant operation.
397 =item --anchor=<commit-ish>
399 Treats <commit-ish> as an anchor.
400 This overrides the usual logic which automatically classifies
401 commits as anchors, pseudomerges, delta queue commits, etc.
403 It also disables some coherency checks
404 which depend on metadata extracted from its commit message,
406 it is a snag if <commit-ish> is the anchor
407 for the previous upstream version in
408 git-debrebase new-upstream operations.
412 Requests (more) debugging. May be repeated.
416 =head1 UNSTITCHING AND LAUNDERING
418 Several operations unstitch and launder the branch first.
419 In detail this means:
421 =head2 Establish the current branch's ffq-prev
423 If ffq-prev is not yet recorded,
424 git-debrebase checks that the current branch is ahead of relevant
425 remote tracking branches.
426 The relevant branches depend on
427 the current branch (and its
435 The branch that git would merge from
436 (remote.<branch>.merge, remote.<branch>.remote);
440 The branch git would push to, if different
441 (remote.<branch>.pushRemote etc.);
445 For local dgit suite branches,
446 the corresponding tracking remote;
450 If you are on C<master>,
451 remotes/dgit/dgit/sid.
455 The apparently relevant ref names to check are filtered through
456 branch.<branch>.ffq-ffrefs,
457 which is a semicolon-separated list of glob patterns,
458 each optionally preceded by !; first match wins.
460 In each case it is a snag if
461 the local HEAD is behind the checked remote,
462 or if local HEAD has diverged from it.
463 All the checks are done locally using the remote tracking refs:
464 git-debrebase does not fetch anything from anywhere.
466 If these checks pass,
468 git-debrebse then records the current tip as ffq-prev.
470 =head2 Examine the branch
473 analyses the current HEAD's history to find the anchor
475 and the most recent breakwater tip.
477 =head2 Rewrite the commits into laundered form
479 Mixed debian+upstream commits are split into two commits each.
480 Delta queue (upstream files) commits bubble to the top.
482 and quilt patch additions,
485 This rewrite will always succeed, by construction.
486 The result is the laundered branch.
491 dgit-maint-rebase(7),