chiark / gitweb /
git-debrebase: Provide new get_tree and trees_diff_walk
[dgit.git] / git-debrebase.1.pod
1 =head1 NAME
2
3 git-debrebase - delta queue rebase tool for Debian packaging
4
5 =head1 SYNOPSYS
6
7  git-debrebase [<options...>] [-- <git-rebase options...>]
8  git-debrebase [<options...>] <operation> [<operation options...>
9
10 =head1 INTRODUCTION
11
12 git-debrebase is a tool for representing in git,
13 and manpulating,
14 Debian packages based on upstream source code.
15
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)>.
21
22 You should read this manpage in cojnunction with
23 L<git-debrebase(5)/TERMINOLOGY>,
24 which defines many important terms used here.
25
26 =head1 PRINCIPAL OPERATIONS
27
28 =over
29
30 =item git-debrebase [-- <git-rebase options...>]
31
32 =item git-debrebase [-i <further git-rebase options...>]
33
34 Unstitches and launders the branch.
35 (See L</UNSTITCHING AND LAUNDERING> below.)
36
37 Then, if any git-rebase options were supplied,
38 edits the Debian delta queue,
39 using git-rebase, by running
40
41     git rebase <git-rebase options> <breakwater-tip>
42
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.
47
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.
53
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.
57
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>
63
64 =item git-debrebase status
65
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.
70
71 Please do not attempt to parse the output;
72 it may be reformatted or reorganised in the future.
73 Instead,
74 use one of the L<UNDERLYING AND SUPPLEMENTARY OPERATIONS>
75 described below.
76
77 =item git-debrebase conclude
78
79 Finishes a git-debrebase session,
80 tidying up the branch and making it fast forward again.
81
82 Specifically: if the branch is unstitched,
83 launders and restitches it,
84 making a new pseudomerge.
85 Otherwise, it is an error,
86 unless --noop-ok.
87
88 =item git-debrebase quick
89
90 Unconditionally launders and restitches the branch,
91 consuming any ffq-prev
92 and making a new pseudomerge.
93
94 If the branch is already laundered and stitched, does nothing.
95
96 =item git-debrebase prepush [--prose=<for commit message>]
97
98 =item git-debrebase stitch [--prose=<for commit message>]
99
100 Stitches the branch,
101 consuming ffq-prev.
102 This is a good command to run before pushing to a git server.
103
104 If there is no ffq-prev, it is an error, unless --noop-ok.
105
106 You should consider using B<conclude> instead,
107 because that launders the branch too.
108
109 =item git-debrebase scrap
110
111 Throws away all the work since the branch was last stitched.
112 This is done by rewinding you to ffq-prev.
113
114 If you are in the middle of a git-rebase, will abort that too.
115
116 =item git-debrebase new-upstream <new-version> [<upstream-details>...]
117
118 Rebases the delta queue
119 onto a new upstream version.  In detail:
120
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.
128
129 If all seems well, unstitches and launders the branch.
130
131 Then,
132 generates
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.
138
139 Finally,
140 starts a git-rebase
141 of the delta queue onto these new commits.
142
143 That git-rebase may complete successfully,
144 or it may require your assistance,
145 just like a normal git-rebase.
146
147 If you git-rebase --abort,
148 the whole new upstream operation is aborted,
149 except for the laundering.
150
151 <new-version>
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.
156
157 The <upstream-details> are, optionally, in order:
158
159 =over
160
161 =item <upstream-commit-ish>
162
163 The new upstream branch (or commit-ish).
164 The default is to look for one of these tags, in this order:
165 U vU upstream/U;
166 where U is the new upstream version.
167 (This is the same algorithm as L<git-deborig(1)>.)
168
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.
173
174 =item <piece-name> <piece-upstream-commit-ish>
175
176 Specifies that this is a multi-piece upstream.
177 May be repeated.
178
179 When such a pair is specified,
180 git-debrebase will first combine the pieces of the upstream
181 together,
182 and then use the result as the combined new upstream.
183
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).
190
191 <piece-name> has a restricted syntax:
192 it may contain only ASCII alphanumerics and hyphens.
193
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.
199
200 =item <git-rebase options>
201
202 These will be passed to git rebase.
203
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.
207
208 =back
209
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.
217 L<git-deborig(1)>,
218 L<git-archive(1)>, L<dgit(1)> and
219 L<gbp-import-orig(1)> may be able to help.
220
221 =item git-debrebase make-patches [--quiet-would-amend]
222
223 Generate patches in debian/patches/
224 representing the changes made to upstream files.
225
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.
232
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.
241
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.
250
251 =item git-debrebase convert-from-gbp [<upstream-commit-ish>]
252
253 Cnnverts a gbp patches-unapplied branch
254 (not a gbp pq patch queue branch)
255 into a git-debrebase interchange branch.
256
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.
260
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.
268
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,
273 forcing it is fine.
274
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.
279
280 The result is a well-formed git-debrebase interchange branch.
281 The result is also fast-forward from the gbp branch.
282
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.
286
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.
290 At worst,
291 using the wrong tool for the branch format might result in
292 a dropped patch queue!
293
294 =back
295
296 =head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS
297
298 =over
299
300 =item git-debrebase breakwater
301
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.
305
306 =item git-debrebase anchor
307
308 Prints the breakwater anchor commitid.
309
310 =item git-debrebase analyse
311
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)
318 for each commit.
319
320 =item git-debrebase record-ffq-prev
321
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.
325
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,
328 unless --noop-ok.
329
330 =item git-debrebase launder-v0
331
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.
336
337 =item git-debrebase convert-to-gbp
338
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.
343
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.
348
349 Be sure to not accidentally treat the result as
350 a git-debrebase branch,
351 or you will drop all the patches!
352
353 =item git-debrebase convert-from-dgit-view [<convert-options>] [upstream]
354
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.
358
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).
363
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.
366 By default,
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.
369
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.
374
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.
379
380 The available convert-options are as follows.
381 (These must come after convert-from-dgit-view.)
382
383 =over
384
385 =item --[no-]diagnose
386
387 Print additional error messages to help diagnose
388 failure to find an appropriate upstream.
389 --no-diagnose is the default.
390
391 =item --build-products-dir
392
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.
398
399 =item --[no-]origs
400
401 Whether to try to look for or use any orig tarballs.
402 --origs is the default.
403
404 =item --[no-]tags
405
406 Whether to try to look for or use any upstream git tags.
407 --tags is the default.
408
409 =item --always-convert-anyway
410
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.
416
417 =back
418
419 =back
420
421 =head1 OPTIONS
422
423 This section documents the general options
424 to git-debrebase
425 (ie, the ones which immediately follow
426 git-debrebase
427 or
428 git debrebase
429 on the command line).
430 Individual operations may have their own options which are
431 docuented under each operation.
432
433 =over
434
435 =item -f<snag-id>
436
437 Turns snag(s) with id <snag-id> into warnings.
438
439 Some troublesome things which git-debrebase encounters
440 are B<snag>s.
441 (The specific instances are discussed
442 in the text for the relevant operation.)
443
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.
448
449 If snags are detected, git-debrebase does not continue,
450 unless the relevant -f<snag-id> is specified,
451 or --force is specified.
452
453 =item --force
454
455 Turns all snags into warnings.
456 See the -f<snag-id> option.
457
458 Do not invoke git-debrebase --force in scripts and aliases;
459 instead, specify the particular -f<snag-id> for expected snags.
460
461 =item --noop-ok
462
463 Suppresses the error in
464 some situations where git-debrebase does nothing,
465 because there is nothing to do.
466
467 The specific instances are discussed
468 in the text for the relvant operation.
469
470 =item --anchor=<commit-ish>
471
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.
475
476 It also disables some coherency checks
477 which depend on metadata extracted from its commit message,
478 so
479 it is a snag if <commit-ish> is the anchor
480 for the previous upstream version in
481 git-debrebase new-upstream operations.
482
483 =item --dgit=<program>
484
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.
488
489 =item -D
490
491 Requests (more) debugging.  May be repeated.
492
493 =back
494
495 =head1 UNSTITCHING AND LAUNDERING
496
497 Several operations unstitch and launder the branch first.
498 In detail this means:
499
500 =head2 Establish the current branch's ffq-prev
501
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
507 git configuration)
508 and are as follows:
509
510 =over
511
512 =item
513
514 The branch that git would merge from
515 (remote.<branch>.merge, remote.<branch>.remote);
516
517 =item
518
519 The branch git would push to, if different
520 (remote.<branch>.pushRemote etc.);
521
522 =item
523
524 For local dgit suite branches,
525 the corresponding tracking remote;
526
527 =item
528
529 If you are on C<master>,
530 remotes/dgit/dgit/sid.
531
532 =back
533
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.
538
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.
544
545 If these checks pass,
546 or are forced,
547 git-debrebse then records the current tip as ffq-prev.
548
549 =head2 Examine the branch
550
551 git-debrebase
552 analyses the current HEAD's history to find the anchor
553 in its breakwater,
554 and the most recent breakwater tip.
555
556 =head2 Rewrite the commits into laundered form
557
558 Mixed debian+upstream commits are split into two commits each.
559 Delta queue (upstream files) commits bubble to the top.
560 Pseudomerges,
561 and quilt patch additions,
562 are dropped.
563
564 This rewrite will always succeed, by construction.
565 The result is the laundered branch.
566
567 =head1 SEE ALSO
568
569 git-debrebase(1),
570 dgit-maint-rebase(7),
571 dgit(1),
572 gitglossary(7)