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(5)>.
19 For background, theory of operation,
20 and definitions of the terms used here,
21 see L<git-debrebase(5)>.
23 =head1 PRINCIPAL OPERATIONS
27 =item git-debrebase [-- <git-rebase options...>]
29 Unstitches and launders the branch.
30 (See L</UNSTITCHING AND LAUNDERING> below.)
32 Then optionally edits the Debian delta queue,
33 using git-rebase, by running
35 git rebase <git-rebase options> <breakwater-tip>
37 Do not pass a base branch argument:
38 git-debrebase will supply that.
39 Do not use --onto, or --fork-point.
40 Useful git-rebase options include -i and --autosquash.
42 If git-rebase stops for any reason,
43 you may git-rebase --abort, --continue, or --skip, as usual.
44 If you abort the git-rebase,
45 the branch will still have been laundered,
46 but everything in the rebase will be undone.
48 =item git-debrebase stitch [--prose=<for commit message>]
53 If there is no ffq-prev, it is an error, unless --noop-ok.
55 It is a problem if the branch is not laundered.
57 =item git-debrebase new-upstream-v0 <new-version> [<upstream-details>...]
59 Rebases the delta queue
60 onto a new upstream version. In detail:
62 Firstly, checks that the proposed rebase seems to make sense:
63 It is a problem unless the new upstream(s)
64 are fast forward from the previous upstream(s)
65 as found in the current breakwater anchor.
66 And, in the case of a multi-piece upstream
67 (a multi-component upstream, in dpkg-source terminology),
68 if the pieces are not in the same order, with the same names.
70 If all seems well, unstitches and launders the branch.
74 (in a private working area)
75 a new anchor merge commit,
76 on top of the breakwater tip,
77 and on top of that a commit to
78 update the version number in debian/changelog.
82 of the delta queue onto these new commits.
84 That git-rebase may complete successfully,
85 or it may require your assistance,
86 just like a normal git-rebase.
88 If you git-rebase --abort,
89 the whole new upstream operation is aborted,
90 except for the laundering.
92 The <upstream-details> are, optionally, in order:
96 =item <upstream-commit-ish>
98 The new upstream branch (or commit-ish).
99 Default is C<upstream>.
101 It is a problem if the upstream contains a debian/ directory;
102 if forced to proceed,
103 git-debrebase will disregard the upstream's debian/ and
104 take (only) the packaging from the current breakwater.
106 =item <piece-name> <piece-upstream-commit-ish>
108 Specifies that this is a multi-piece upstream.
111 When such a pair is specified,
112 git-debrebase will first combine the pieces of the upstream
114 and then use the result as the combined new upstream.
116 For each <piece-name>,
117 the tree of the <piece-upstream-commit-ish>
118 becomes the subdirectory <piece-name>
119 in the combined new upstream
120 (supplanting any subdirectory that might be there in
121 the main upstream branch).
123 <piece-name> has a restricted syntax:
124 it may contain only ASCII alphanumerics and hyphens.
126 The combined upstream is itself recorded as a commit,
127 with each of the upstream pieces' commits as parents.
128 The combined commit contains an annotation
129 to allow a future git-debrebase new upstream operation
130 to make the coherency checks described above.
132 =item <git-rebase options>
134 These will be passed to git rebase.
136 If the upstream rebase is troublesome, -i may be helpful.
137 As with plain git-debrebase,
138 do not specify a base, or --onto, or --fork-point.
142 If you are planning to generate a .dsc,
143 you will also need to have, or generate,
144 actual orig tarball(s),
145 which must be identical to the rev-spec(s)
146 passed to git-debrebase.
147 git-debrebase does not concern itself with source packages
148 so neither helps with this, nor checks it.
150 L<git-archive(1)>, L<dgit(1)> and
151 L<gbp-import-orig(1)> may be able to help.
153 This subcommand has -v0 in its name because we are not yet sure
154 that its command line syntax is optimal.
155 We may want to introduce an incompatible replacement syntax
156 under the name C<new-upstream>.
158 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
160 Cnnverts a gbp patches-unapplied branch
161 (not a gbp pq patch queue branch)
162 into a git-debrebase interchange branch.
164 This is done by generating a new anchor merge,
165 converting the quilt patches as a delta queue,
166 and dropping the patches from the tree.
168 The upstream commit-ish should correspond to
169 the gbp upstream branch, if there is one.
170 It is a problem if it is not an ancestor of HEAD,
171 or if the history between the upstream and HEAD
172 contains commits which make changes to upstream files.
174 It is also a problem if the specified upstream
175 has a debian/ subdirectory.
176 This check exists to detect certain likely user errors,
177 but if this situation is true and expected,
180 The result is a well-formed git-debrebase interchange branch.
181 The result is also fast-forward from the gbp branch.
183 Note that it is dangerous not to know whether you are
184 dealing with a gbp patches-unappled branch containing quilt patches,
185 or a git-debrebase interchange branch.
187 using the wrong tool for the branch format might result in
188 a dropped patch queue!
192 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
196 =item git-debrebase breakwater
198 Prints the breakwater tip commitid.
199 If your HEAD branch is not fully laundered,
200 prints the tip of the so-far-laundered breakwater.
202 =item git-debrebase anchor
204 Prints the breakwater anchor commitid.
206 =item git-debrebase analyse
208 Walks the history of the current branch,
209 most recent commit first,
210 back until the most recent anchor,
211 printing the commit object id,
212 and commit type and info
213 (ie the semantics in the git-debrebase model)
216 =item git-debrebase record-ffq-prev
218 Establishes the current branch's ffq-prev,
219 as discussed in L</UNSTITCHING AND LAUNDERING>,
220 but does not launder the branch or move HEAD.
222 It is an error if the ffq-prev could not be recorded.
223 It is also an error if an ffq-prev has already been recorded,
226 =item git-debrebase launder-v0
228 Launders the branch without recording anything in ffq-prev.
229 Then prints some information about the current branch.
230 Do not use this operation;
231 it will be withdrawn soon.
233 =item git-debrebase convert-to-gbp
235 Converts a laundered branch into a
236 gbp patches-unapplied branch containing quilt patches.
237 The result is not fast forward from the interchange branch,
238 and any ffq-prev is deleted.
240 This is provided mostly for the test suite
241 and for unusual situations.
242 It should only be used with a care and
243 with a proper understanding of the underlying theory.
245 Be sure to not accidentally treat the result as
246 a git-debrebase branch,
247 or you will drop all the patches!
253 This section documents the general options
255 (ie, the ones which immediately follow
259 on the command line).
260 Individual operations may have their own options which are
261 docuented under each operation.
267 Turns problems with id <problem-id> into warnings.
269 Some troublesome things which git-debrebase encounters
271 (The specific instances are discussed
272 in the text for the relvant operation.)
274 When a problem is detected,
275 a message is printed to stderr containing the problem id
276 (in the form C<-f<problem-idE<gt>>),
277 along with some prose.
279 If problems are detected, git-debrebase does not continue,
280 unless the relevant -f<problem-id> is specified,
281 or --force is specified.
285 Turns all problems into warnings.
286 See the -f<problem-id> option.
288 Do not invoke git-debrebase --force in scripts and aliases;
289 instead, specify the particular -f<problem-id> for expected problems.
293 Suppresses the error in
294 some situations where git-debrebase does nothing,
295 because there is nothing to do.
297 The specific instances are discussed
298 in the text for the relvant operation.
300 =item --anchor=<commit-ish>
302 Treats <commit-ish> as an anchor,
303 regardless of what it's actually like.
306 git-debrebase new-upstream operations
307 if <commit-ish> is the previous anchor to be used,
308 because treating an arbitrary commit as an anchor
309 means forgoing upstream coherency checks.)
313 Requests (more) debugging. May be repeated.
317 =head1 UNSTITCHING AND LAUNDERING
319 Several operations unstitch and launder the branch first.
320 In detail this means:
322 =head2 Establish the current branch's ffq-prev
324 If ffq-prev is not yet recorded,
325 git-debrebase checks that the current branch is ahead of relevant
326 remote tracking branches.
327 The relevant branches depend on
328 the current branch (and its
336 The branch that git would merge from
337 (remote.<branch>.merge, remote.<branch>.remote);
341 The branch git would push to, if different
342 (remote.<branch>.pushRemote etc.);
346 For local dgit suite branches,
347 the corresponding tracking remote;
351 If you are on C<master>,
352 remotes/dgit/dgit/sid.
356 The apparently relevant ref names to check are filtered through
357 branch.<branch>.ffq-ffrefs,
358 which is a semicolon-separated list of glob patterns,
359 each optionally preceded by !; first match wins.
361 In each case it is a problem if
362 the local HEAD is behind the checked remote,
363 or if local HEAD has diverged from it.
364 All the checks are done locally using the remote tracking refs:
365 git-debrebase does not fetch anything from anywhere.
367 If these checks pass,
369 git-debrebse then records the current tip as ffq-prev.
371 =head2 Examine the branch
374 analyses the current HEAD's history to find the anchor
376 and the most recent breakwater tip.
378 =head2 Rewrite the commits into laundered form
380 Mixed debian+upstream commits are split into two commits each.
381 Delta queue (upstream files) commits bubble to the top.
383 and quilt patch additions,
386 This rewrite will always succeed, by construction.
387 The result is the laundered branch.
392 dgit-maint-rebase(7),