X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.5.pod;h=c30b124dea9d7cf254107f32827a17fc9a4e2682;hp=d39ad9484986fb022e98e735a030d91f6e136063;hb=f9de6d94951a129a0a90c688b15807da2d56e77a;hpb=0057ec1d2d864bbd40a5fcc32a5edeeb2bc90b4e diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index d39ad948..c30b124d 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -146,7 +146,7 @@ See L. git-debrebase has one primary branch, the B. -This branch is found on Debian contributor's workstations +This branch is found on Debian contributors' workstations (typically, a maintainer would call it B), in the Debian dgit git server as the suite branch (B) and on other git servers which support Debian work @@ -175,7 +175,7 @@ the upstream commits). The breakwater does not contain any representation of the delta queue (not even debian/patches). The part of the breakwater processed by git-debrebase -is the part since the most reecent B, +is the part since the most recent B, which is usually a special merge generated by git-debrebase. When working, locally, @@ -190,7 +190,7 @@ and the user's work can later be stitched into the fast-forwarding interchange form. -An unstitched branch may be in +An unstitched branch may be in the B state, which means it has a more particular special form @@ -255,7 +255,7 @@ a representation of the delta queue: =item Delta queue commits Zero or more single-parent commits -contaioning only changes to upstream files. +containing only changes to upstream files. =back @@ -266,7 +266,7 @@ branch state is also B. It has the same contents as the laundered state, except that it may contain, additionally, -in B: +B: =over @@ -378,8 +378,11 @@ from the interchange branch and no pseudomerge is needed. When ffq-prev is not present, C records some ancestor of refs/B, (usually, the result of last stitch). -This can be used to quickly determine whether refs/B -is being maintained in git-debrebase form. +This is used for status printing and some error error checks - +especially for printing guesses about what a problem is. +To determine whether a branch +is being maintained in git-debrebase form +it is necessary to walk its history. =head1 OTHER MERGES @@ -416,7 +419,7 @@ so we can at least detect unsupported merges. =head1 LEGAL OPERATIONS -The following basic operations follows from this model +The following basic operations follow from this model (refer to the diagram above): =over @@ -469,7 +472,7 @@ so that git log shows the packaging history.) =item Stitch Make a pseudomerge, -whose contributing parent to is the unstitched branch +whose contributing parent is the unstitched branch and whose overwritten parent is ffq-prev, consuming ffq-prev in the process @@ -480,7 +483,7 @@ or perhaps a laundered branch with a quilt patch addition commit. =item Commit quilt patches To generate a tree which can be represented as a -3.0 (quilt) .dsc source packages, +3.0 (quilt) .dsc source package, the delta queue must be reified inside the git tree in B. These patch files can be stripped out and/or regenerated as needed. @@ -512,7 +515,7 @@ For these reasons, it is better to use git-debrebase and let it choose the base for your rebase. -If you do realise you have make this mistake, +If you do realise you have made this mistake, it is best to use the reflog to recover to a suitable good previous state. @@ -527,6 +530,21 @@ If you add patches your work is likely to be discarded. Instead of editing patches, use git-debrebase to edit the corresponding commits. +=item Renaming (etc.) branch while unstitched + +The previous HEAD, +which will be pseudomerged over +by operations like git-debrebase stitch, +is recorded in a ref name dervied from your branch name. + +If you rename unstitched branches, +this information can get out of step. + +Conversely, +creating a new branch from an unstitched branch +is good for making a branch to play about in, +but the result cannot be stitched. + =back =head1 COMMIT MESSAGE ANNOTATIONS @@ -536,27 +554,31 @@ in the messages of commits it generates. The general form is - [git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE] + [git-debrebase COMMIT-TYPE [ ARGS...]: PROSE, MORE PROSE] git-debrebase treats anything after the colon as a comment, paying no attention to PROSE. The full set of annotations is: - [git-debrebase: split mixed commit, debian part] - [git-debrebase: split mixed commit, upstream-part] - [git-debrebase: convert dgit import, debian changes] + [git-debrebase split: mixed commit, debian part] + [git-debrebase split: mixed commit, upstream-part] + [git-debrebase onvert dgit import: debian changes] [git-debrebase anchor: convert dgit import, upstream changes] [git-debrebase upstream-combine . PIECE[ PIECE...]: new upstream] [git-debrebase anchor: new upstream NEW-UPSTREAM-VERSION, merge] - [git-debrebase: new upstream NEW-UPSTREAM-VERSION, changelog] - [git-debrebase: export and commit patches] + [git-debrebase changelog: new upstream NEW-UPSTREAM-VERSION] + [git-debrebase make-patches: export and commit patches] [git-debrebase convert-from-gbp: drop patches] [git-debrebase anchor: declare upstream] [git-debrebase pseudomerge: stitch] + [git-debrebase merged-breakwater: constructed from vanilla merge] + [git-debrebase convert-to-gbp: commit patches] + [git-debrebase convert-from-dgit-view upstream-import-convert: VERSION] + [git-debrebase convert-from-dgit-view drop-patches] Only anchor merges have the C<[git-debrebase anchor: ...]> tag. Single-parent anchors are not generated by git-debrebase,