From 0057ec1d2d864bbd40a5fcc32a5edeeb2bc90b4e Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 31 Jul 2018 13:52:03 +0100 Subject: [PATCH] git-debrebase(5): Add ILLEGAL OPERATIONS section. Re #905004. Signed-off-by: Ian Jackson --- debian/changelog | 1 + git-debrebase.5.pod | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/debian/changelog b/debian/changelog index 3948db71..6f5e1557 100644 --- a/debian/changelog +++ b/debian/changelog @@ -11,6 +11,7 @@ dgit (6.3~) unstable; urgency=medium * git-debrebase: Improve error messages for bad options. * git-debrebase: Improve error message for convert-from-gbp upstream discrepancy. Closes:#905078. + * git-debrebase(5): Add ILLEGAL OPERATIONS section. (Re#905004.) -- diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index 52fb60b9..d39ad948 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -487,6 +487,48 @@ 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 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. + +=back + =head1 COMMIT MESSAGE ANNOTATIONS git-debrebase makes annotations -- 2.30.2