X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=git-debrebase.5.pod;h=f641a70fe756fd8147c82e86c40335d26041c29b;hb=626c5a5851ebabb54e01e3fe3e15b3971f62555b;hp=cc9fb7a03e3edf77b1d268cfd9ae697d95c0af3b;hpb=472edf9ca063494baf017ed891baa34d0ac057be;p=dgit.git

diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index cc9fb7a0..f641a70f 100644
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -29,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<gitk --date-order>, B<gitk --first-parent>
+and B<gitk -- :.> (or B<gitk .>)
+produce more useful output than the default.
+
 =head1 TERMINOLOGY
 
 =over
@@ -482,6 +487,63 @@ 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</OTHER MERGES>, 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 make 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
@@ -509,6 +571,8 @@ The full set of annotations is:
   [git-debrebase anchor: declare upstream]
   [git-debrebase pseudomerge: stitch]
 
+  [git-debrebase merged-breakwater: constructed from vanilla merge]
+
   [git-debrebase convert-to-gbp: commit patches]
 
 Only anchor merges have the C<[git-debrebase anchor: ...]> tag.