/ / /
2* 2* 2
/ / /
- 1 1 1 `breakwater' branch, merging baseline
+ 1 1 1 breakwater branch, merging baseline
/ / / unmodified upstream code
---@-----@--A----@--B--C plus debian/ (but no debian/patches)
/ / / no ref refers to this: we
* Maintainer's HEAD was here while they were editing,
before they said they were done, at which point their
tools generated [% and] -/- commit[s] to convert to
- the fast-forwarding interchange branch. (Maybe the
- tooling is simply `dgit push'.)
+ the fast-forwarding interchange branch.
! NMUer's HEAD was here when they said `dgit push'.
Rebase branch launderer turns each ! into an
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<debian/patches/>.
+(These can be stripped out and/or regenerated as needed.)
+
+=back
+
=head1 TERMINOLOGY
=over
We want to transform this into:
- I. No new upstream version (0 + 00 eq #)
+=over
+
+=item I. No new upstream version
+ (0 + 00 eq #)
--/--B3!--%--/------D*-------------/-->
/ / /
% 4 4**
/
--#----------------------------------------->
+=item II. New upstream
- II. New upstream (0 + 00 neq #)
+ (0 + 00 neq #)
--/--B3!--%--/------D*-------------/-->
/ / /
/|
0 00
+=back
+
=head1 SEE ALSO
-dgit(1), dgit(7), dgit-maint-*(7)
+git-debrebase(1),
+dgit-maint-rebase(7),
+dgit(1)