X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.1.pod;h=4d4c85a94992b7e83f68d5e8a20212176ee658c6;hp=7e126246bfd9e534d2998591539956fc24025099;hb=ca261d36408442d8f3beeac12434af95810b1e32;hpb=134858eaf9df5e8e6f03c67b40c8ce4cc119b41e diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index 7e126246..4d4c85a9 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -29,10 +29,13 @@ which defines many important terms used here. =item git-debrebase [-- ] +=item git-debrebase [-i ] + Unstitches and launders the branch. (See L below.) -Then optionally edits the Debian delta queue, +Then, if any git-rebase options were supplied, +edits the Debian delta queue, using git-rebase, by running git rebase @@ -48,14 +51,54 @@ If you abort the git-rebase, the branch will still have been laundered, but everything in the rebase will be undone. +The options for git-rebase must either start with C<-i>, +or be prececded by C<-->, +to distinguish them from options for git-debrebase. + +=item git-debrebase status + +Analyise the current branch, +both in terms of its conents, +and the refs which are relevant to git-debrebase, +and print a human-readable summary. + +Please do not attempt to parse the output; +it may be reformatted or reorganised in the future. +Instead, +use one of the L +described below. + +=item git-debrebase conclude + +Finishes a git-debrebase session, +tidying up the branch and making it fast forward again. + +Specifically: if the branch is unstitched, +launders and restitches it, +making a new pseudomerge. +Otherwise, it is an error, +unless --noop-ok. + +=item git-debrebase quick + +Unconditionally launders and restitches the branch, +consuming any ffq-prev +and making a new pseudomerge. + +If the branch is already laundered and stitched, does nothing. + +=item git-debrebase prepush [--prose=] + =item git-debrebase stitch [--prose=] -Stitch the branch, +Stitches the branch, consuming ffq-prev. +This is a good command to run before pushing to a git server. If there is no ffq-prev, it is an error, unless --noop-ok. -It is a problem if the branch is not laundered. +You should consider using B instead, +because that launders the branch too. =item git-debrebase new-upstream-v0 [...] @@ -63,7 +106,7 @@ Rebases the delta queue onto a new upstream version. In detail: Firstly, checks that the proposed rebase seems to make sense: -It is a problem unless the new upstream(s) +It is a snag unless the new upstream(s) are fast forward from the previous upstream(s) as found in the current breakwater anchor. And, in the case of a multi-piece upstream @@ -101,7 +144,7 @@ The are, optionally, in order: The new upstream branch (or commit-ish). Default is C. -It is a problem if the upstream contains a debian/ directory; +It is a snag if the upstream contains a debian/ directory; if forced to proceed, git-debrebase will disregard the upstream's debian/ and take (only) the packaging from the current breakwater. @@ -158,6 +201,33 @@ that its command line syntax is optimal. We may want to introduce an incompatible replacement syntax under the name C. +=item git-debrebase make-patches [--quiet-would-amend] + +Generate patches in debian/patches/ +representing the changes made to upstream files. + +It is not normally necessary to run this command explicitly. +When uploading to Debian, +dgit and git-debrebase +will cooperate to regenerate patches as necessary. +When working with pure git remotes, +the patches are not needed. + +Normally git-debrebase make-patches will +require a laundered branch. +(A laundered branch does not contain any patches.) +But if there are already some patches made by +git-debrebase make-patches, +and all that has happened is that more +changes to upstream files have been committed, +running it again can add the missing patches. + +If the patches implied by the current branch +are not a simple superset of those already in debian/patches, +make-patches will fail with exit status 7, +and an error message. +(The message can be suppress with --quiet-would-amend.) + =item git-debrebase convert-from-gbp [] Cnnverts a gbp patches-unapplied branch @@ -170,11 +240,11 @@ and dropping the patches from the tree. The upstream commit-ish should correspond to the gbp upstream branch, if there is one. -It is a problem if it is not an ancestor of HEAD, +It is a snag if it is not an ancestor of HEAD, or if the history between the upstream and HEAD contains commits which make changes to upstream files. -It is also a problem if the specified upstream +It is also a snag if the specified upstream has a debian/ subdirectory. This check exists to detect certain likely user errors, but if this situation is true and expected, @@ -265,31 +335,31 @@ docuented under each operation. =over -=item -f +=item -f -Turns problems with id into warnings. +Turns snag(s) with id into warnings. Some troublesome things which git-debrebase encounters -are Bs. +are Bs. (The specific instances are discussed in the text for the relvant operation.) -When a problem is detected, -a message is printed to stderr containing the problem id -(in the form C<-f>), +When a snag is detected, +a message is printed to stderr containing the snag id +(in the form C<-f>), along with some prose. -If problems are detected, git-debrebase does not continue, -unless the relevant -f is specified, +If snags are detected, git-debrebase does not continue, +unless the relevant -f is specified, or --force is specified. =item --force -Turns all problems into warnings. -See the -f option. +Turns all snags into warnings. +See the -f option. Do not invoke git-debrebase --force in scripts and aliases; -instead, specify the particular -f for expected problems. +instead, specify the particular -f for expected snags. =item --noop-ok @@ -303,12 +373,13 @@ in the text for the relvant operation. =item --anchor= Treats as an anchor. -This overrides the usual automatic commit classification logic. +This overrides the usual logic which automatically classifies +commits as anchors, pseudomerges, delta queue commits, etc. It also disables some coherency checks which depend on metadata extracted from its commit message, so -it is a problem if is the anchor +it is a snag if is the anchor for the previous upstream version in git-debrebase new-upstream operations. @@ -362,7 +433,7 @@ branch..ffq-ffrefs, which is a semicolon-separated list of glob patterns, each optionally preceded by !; first match wins. -In each case it is a problem if +In each case it is a snag if the local HEAD is behind the checked remote, or if local HEAD has diverged from it. All the checks are done locally using the remote tracking refs: