X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=git-debrebase.1.pod;h=0127e93d2023f89bea93cc35a90ad3ab88b6ab4b;hb=fc3c50c90141a0a3925c335eac71c315bee3f409;hp=ab6e12ce0ba5dd05511227acbca803f54d72e93e;hpb=75d0b8d7275c035f76db79e7cf7e802e061a9bee;p=dgit.git diff --git a/git-debrebase.1.pod b/git-debrebase.1.pod index ab6e12ce..0127e93d 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,87 @@ 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 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 UNSTITCHING AND LAUNDERING @@ -151,24 +240,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 +266,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 +286,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),