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.
to work on packages inherited from Debian,
because it assumes that you want to throw away any packaging
provided by your upstream.
-However, of git-debrebase in Debian does not make anything harder for
+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
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
+ / / / no ref refers to this: we
--#-----#-------#-----> upstream reconstruct its identity by
- inspecting interchange branch
+ inspecting interchange branch
Key:
1,2,3 commits touching upstream files only
-/- pseudomerge; contents are identical to
/ parent lower on diagram.
- % dgit-generated commit of debian/patches.
+ % dgit- or git-debrebase- generated commit of debian/patches.
`3.0 (quilt)' only; generally dropped by git-debrebase.
* Maintainer's HEAD was here while they were editing,
While a branch is unstitched,
it is not in interchange format.
The previous interchange branch tip
-tip is recorded,
+is recorded,
so that the previous history
and the user's work
can later be
When ffq-prev is not present,
C<refs/debrebase-last/B> 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 what a problem is.
+To determine whether a branch is
+is being maintained in git-debrebase form
+it is necessary to walk its history.
=head1 OTHER MERGES
For this reason the tools will try to help the user
avoid divergence of the interchange branch.
-See dgit-maint-rebase(7) XXX TBD
-for a discussio of what kinds of behaviours
+See dgit-maint-rebase(7)
+for a discussion of what kinds of behaviours
should be be avoided
because
they might generate such merges.
in principle tolerable,
but each of the parents would have to be, in turn,
a breakwater,
-and difficult qeustions arise if they don't have the same anchor.
+and difficult questions arise if they don't have the same anchor.
We use the commit message annotation to
distinguish the special anchor merges from other general merges,
=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
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 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,
-and when made manually should not be tagged.
+and when made manually should not
+contain any C<[git-debrebase ...]> annotation.
The C<split mixed commit> and C<convert dgit import>
tags are added to the pre-existing commit message,
=head1 APPENDIX - DGIT IMPORT HANDLING
+The dgit .dsc import format is not documented or specified
+(so some of the following terms are not defined anywhere).
+The dgit import format it is defined by the implementation in dgit,
+of which git-debrebase has special knowledge.
+
Consider a non-dgit NMU followed by a dgit NMU:
- interchange --/--B3!--%--/----D*-->
+ interchange --/--B3!--%--//----D*-->
/ /
% 4
/ 3
1 0 00 =XBC%
/
/
- --@--A breakwater
- /
- --#--------> upstream
+ --@--A breakwater
+ /
+ --#--------> upstream
Supplementary key:
=XBC% dgit tarball import of .debian.tar.gz containing
- Debian packaging including changes B C and quilt patches
-
+ Debian packaging including changes B C and quilt patches
0 dgit tarball import of upstream tarball
- 00 dgit tarball import of supplementary upstream tarball
- &_ dgit nearly-breakwater import
+ 00 dgit tarball import of supplementary upstream piece
+ &_ dgit import nearly-breakwater-anchor
+ // dgit fetch / import-dsc pseudomerge to make fast forward
+
&' git-debrebase converted import (upstream files only)
- D' git-debrebase converted debian/ changes import
+ C' git-debrebase converted packaging change import
* ** before and after HEAD
=item I. No new upstream version
(0 + 00 eq #)
- --/--B3!--%--/------D*-------------/-->
- / / /
- % 4 4**
- / 3 3
- / 2 2
- / 1 1
- 2 &_ /
- / /| \ /
+ --/--B3!--%--//-----D*-------------/-->
+ / / /
+ % 4 4**
+ / 3 3
+ / 2 2
+ / 1 1
+ 2 &_ /
+ / /| \ /
1 0 00 =XBC% /
- / /
- / /
- --@--A-----B-----------------------C--D
- /
- --#----------------------------------------->
+ / /
+ / /
+ --@--A-----B---------------------C'---D
+ /
+ --#----------------------------------------->
=item II. New upstream
(0 + 00 neq #)
- --/--B3!--%--/------D*-------------/-->
- / / /
- % 4 4**
- / 3 3
- / 2 2
- / 1 1
- 2 &_ /
- / /| \ /
+ --/--B3!--%--//-----D*-------------/-->
+ / / /
+ % 4 4**
+ / 3 3
+ / 2 2
+ / 1 1
+ 2 &_ /
+ / /| \ /
1 0 00 =XBC% /
- / /
- / /
- --@--A-----B--------------------@--C--D
- / /
- --#----------------------- - - / - - ----->
- /
- &'
- /|
- 0 00
+ / /
+ / /
+ --@--A-----B-----------------@---C'---D
+ / /
+ --#--------------------- - - / - - --------->
+ /
+ &'
+ /|
+ 0 00
=back