X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=git-debrebase.5.pod;h=c30b124dea9d7cf254107f32827a17fc9a4e2682;hb=f9de6d94951a129a0a90c688b15807da2d56e77a;hp=e445c0e6001354bd337d8b01f7b8859ed98150d1;hpb=da6f19f4f54e84723e9d1435bcfd4f7db8e55986;p=dgit.git diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index e445c0e6..c30b124d 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -15,6 +15,8 @@ as a series of individual git commits, which can worked on with rebase, and also shared. +=head2 DISCUSSION + git-debrebase is designed to work well with dgit. git-debrebase can also be used in workflows without source packages, for example to work on Debian-format packages outside or alongside Debian. @@ -27,6 +29,11 @@ provided by your upstream. However, use of git-debrebase in Debian does not make anything harder for derivatives, and it can make some things easier. +When using gitk on branches managed by git-debrebase, +B, B +and B (or B) +produce more useful output than the default. + =head1 TERMINOLOGY =over @@ -139,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 @@ -168,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, @@ -183,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 @@ -248,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 @@ -259,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 @@ -371,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 @@ -409,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 @@ -462,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 @@ -473,13 +483,70 @@ 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. =back +=head1 ILLEGAL OPERATIONS + +Some git operations are not permitted in this data model. +Performing them will break git-debrebase. + +=over + +=item General merges + +See L, above. + +=item git-rebase starting too soon, or without base argument + +git-rebase must not be invoked in such a way that +the chosen base is before the anchor, +or before the last pseudomerge. +This is because git-rebase mangles merges. +git rebase --preserve-merges is also dangerous. + +git-rebase without a base argument will often start too early. + +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 made this mistake, +it is best to use the reflog to recover to a suitable +good previous state. + +=item Editing debian/patches + +debian/patches is an output from git-debrebase, +not an input. +If you edit patches git-debrebase will complain +and refuse to work. +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 git-debrebase makes annotations @@ -487,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,