X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=git-debrebase.1.pod;h=9ddf9390b40781b2aad7724c5c29685aadfe7c58;hb=58cd6d7cf9c2e0c5faba010744079881da008fea;hp=ab6e12ce0ba5dd05511227acbca803f54d72e93e;hpb=75d0b8d7275c035f76db79e7cf7e802e061a9bee;p=dgit.git diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index ab6e12ce..9ddf9390 100644 --- a/git-debrebase.1.pod +++ b/git-debrebase.1.pod @@ -2,6 +2,11 @@ git-debrebase - delta queue rebase tool for Debian packaging +=head1 SYNOPSYS + + git-debrebase [] [-- ] + git-debrebase [] [ + =head1 INTRODUCTION git-debrebase is a tool for representing in git, @@ -11,11 +16,14 @@ Debian packages based on upstream source code. This is the command line reference. Please read the tutorial L. - For background, theory of operation, and definitions of the terms used here, see L. +If no operation is specified, +git-debrebase launders the branch and rebases the Debian delta queue. +See below. + =head1 PRINCIPAL OPERATIONS =over @@ -142,6 +150,159 @@ git-debrebase does not concern itself with source packages so neither helps with this, nor checks it. L, L and L may be able to help. +This subcommand has -v0 in its name because we are not yet sure +that its command line syntax is optimal. +We may want to introduce an incompatible replacement syntax +under the name C. + +=item git-debrebase convert-from-gbp [] + +Cnnverts a gbp patches-unapplied branch +(not a gbp pq patch queue branch) +into a git-debrebase interchange branch. + +This is done by generating a new anchor merge, +converting the quilt patches as a delta queue, +and dropping the patches from the tree. + +The upstream commitish should correspond to +the gbp upstream branch. +It is a problem 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 +has a debian/ subdirectory. +This check exists to detect certain likely user errors, +but if this situation is true and expected, +forcing it is fine. + +The result is a well-formed git-debrebase interchange branch. +The result is also fast-forward from the gbp branch. + +Note that it is dangerous not to know whether you are +dealing with a gbp patches-unappled branch containing quilt patches, +or a git-debrebase interchange branch. +At worst, +using the wrong tool for the branch format might result in +a dropped patch queue! + +=back + +=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS + +=over + +=item git-debrebase breakwater + +Prints the breakwater tip commitid. +Fails if your HEAD branch is not laundered. + +=item git-debrebase analyse + +Walks the history of the current branch, +most recent commit first, +back until the most recent anchor, +printing the commit object id, +and commit type and info +(ie the semantics in the git-debrebase model) +for each commit. + +=item git-debrebase record-ffq-prev + +Establishes the current branch's ffq-prev, +as discussed in L, +but does not launder the branch or move HEAD. + +It is an error if the ffq-prev could not be recorded. +It is also an error if an ffq-prev has already been recorded, +unless --noop-ok. + +=item git-debrebase launder-v0 + +Launders the branch without recording anything in ffq-prev. +Then prints some information about the current branch. +Do not use this operation; +it will be withdrawn soon. + +=item git-debrebase convert-to-gbp + +Converts a laundered branch into a +gbp patches-unapplied branch containing quilt patches. +The result is not fast forward from the interchange branch, +and any ffq-prev is deleted. + +This is provided mostly for the test suite +and for unusual situations. +It should only be used with a care and +with a proper understanding of the underlying theory. + +Be sure to not accidentally treat the result as +a git-debrebase branch, +or you will drop all the patches! + +=back + +=head1 OPTIONS + +This section documents the general options +to git-debrebase +(ie, the ones which follow git-debrebase). +Individual operations may have their own options which are +docuented under each operation. + +=over + +=item -f + +Turns problems with id into warnings. + +Some troublesome things which git-debrebase encounters +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>), +along with some prose. + +If problems 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. + +Do not invoke git-debrebase --force in scripts and aliases; +instead, specify the particular -f for expected problems. + +=item --noop-ok + +Suppresses the error in +some situations where git-debrebase does nothing, +because there is nothing to do. + +The specific instances are discussed +in the text for the relvant operation. + +=item --anchor= + +Treats as an anchor, +regardless of what it's actually like. + +(It is a problem for +git-debrebase new-upstream operations +if is the previous anchor to be used, +because treating an arbitrary commit as an anchor +means forgoing upstream coherency checks.) + +=item -D + +Requests (more) debugging. May be repeated. + =back =head1 UNSTITCHING AND LAUNDERING @@ -151,24 +312,25 @@ In detail this means: =head2 Establish the current branch's ffq-prev -If it is not yet recorded, we -check that the current branch is ahead of relevant +If it is not yet recorded, +git-debrebase checks that the current branch is ahead of relevant remote tracking branches. The remote tracking branches checked by default are obtained from the git config. -In each case it is a problem if we are behind the checked remote, -or if we have diverged from it. -All the checks are local: +In each case it is a problem 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: git-debrebase does not fetch anything from anywhere. -We check the branch we would merge from +git-debrebase checks the branch that git would merge from (remote..merge, remote..remote) -and the branch we would push to +and the branch git would push to (remote..pushRemote etc.). For local dgit suite branches -we check the corresponding tracking remote. -If we are on C, we check remotes/dgit/dgit/sid. +it checks the corresponding tracking remote. +If you are on C, it checks remotes/dgit/dgit/sid. The resulting ref names to check are filtered through branch..ffq-ffrefs, which is a semicolon-separated list of glob patterns, @@ -176,11 +338,12 @@ each optionally preceded by !; first match wins. If these checks pass, or are forced, -we then record the current tip as ffq-prev. +git-debrebse then records the current tip as ffq-prev. =head2 Examine the branch -Analyse the current HEAD's history to find the anchor +git-debrebase +analyses the current HEAD's history to find the anchor in its breakwater, and the most recent breakwater tip. @@ -195,17 +358,6 @@ are dropped. This rewrite will always succeed, by construction. The result is the laundered branch. -=head1 UNDERLYING AND SUPPLEMENTARY OPERATIONS - -=over - -=item git-debrebase breakwater - -Prints the breakwater tip commitid. -Fails if your HEAD branch is not laundered. - -=back - =head1 SEE ALSO git-debrebase(1),