From d76a377b48bbcc3dcaf85100588a2d5d4d151db4 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 18 Feb 2018 21:36:45 +0000 Subject: [PATCH] git-debrebase(5): more from README Signed-off-by: Ian Jackson --- README.git-debrebase | 32 ----------------------- git-debrebase.5.pod | 62 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+), 32 deletions(-) diff --git a/README.git-debrebase b/README.git-debrebase index 49fae981..e69de29b 100644 --- a/README.git-debrebase +++ b/README.git-debrebase @@ -1,32 +0,0 @@ - - -So it would be possible to write a `git-debrebase' tool which would -take (for example) B4, above, and be able to perform functions like: - - * Strip pseudomerges: Rewrite the current branch so it contains no - pseudomerges, turning ...B3 into ...@-A-1-2-B3. (This should - make a note, in your .git/ somewhere, of the original branch - tip so that it can be overwritten with a pseudomerge.) - - * Cleanup branch: Reorganise the current branch so that the debian/ - changes come first, turning -@-A-1-2-B3 into ...@-A-B-1-2-3. - - * New upstream rebase: Start rebasing onto a new upstream version, - turning ...#..@-A-B-1-2-3 into (...#..@-A-B-|...#'-)@'-1-2. This - would be a wrapper around git-rebase, which prepares @' and then - tries to rebase 1 2 onto @'. So if you ask for an interactive - rebase @' doesn't appear in your commit list. - - Note that the construction of @' cannot fail because @' simply - copies debian/ from B and and everything else from #'. (Rebasing A - and B is undesirable. We want the debian/ files to be non-rebasing - so we can `git log' and get the packaging history.) - - * Record pseudomerge. This is like "committing" your patch queue. - The LH parent is taken from the previously recorded tip. (We could - perhaps check that this is consistent with what we see in - debian/changelog, but that is not a sufficient check so the - recorded tip check is primary.) - -Maybe some of these operations should automatically edit -debian/changelog. diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index 1c73ea3a..ce982369 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -269,6 +269,68 @@ We use the commit message annotation to distinguish the special anchor merges from other general merges, so we can at least detect unsupported merges. +=head1 LEGAL OPERATIONS + +The following basic operations follows from this model +(refer to the diagram above): + +=over + +=item Append linear commits + +No matter the branch state, +it is always fine to simply git commit +(or cherry-pick etc.) +commits containing upstream file changes, packaging changes, +or both. + +=item Launder branch + +Record the previous tip in ffq-prev, +if we were stitched before. + +Reorganise the current branch so that the debian/ +changes come first, +turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>. + +Drop pseudomerges and any quilt patches. + +=item Interactive rebase + +With a laundered branch, +one can do an interactive git rebase of the delta queue. + +=item New upstream rebase + +Start rebasing onto a new upstream version, +turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-|...#'-)@'-1-2>. + +This has to be a wrapper around git-rebase, +which prepares @' and then tries to rebase 1 2 onto @'. +If the user asks for an interactive rebase, +@' doesn't appear in thec ommit list. + +Note that the construction of @' cannot fail +because @' simply copies debian/ from B and and everything else from #'. +(Rebasing A and B is undesirable. +We want the debian/ files to be non-rebasing +so that git log shows the packaging history.) + +=item Stitch + +Make a pseudomerge, +overwriting (and consuming) ffq-prev. + +=item Commit patches + +To generate a tree which can be represented as a +3.0 (quilt) .dsc source packages, +the delta queue must be reified inside the git tree +in B. +(These can be stripped out and/or regenerated as needed.) + +=back + =head1 TERMINOLOGY =over -- 2.30.2