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
git-debrebase has one primary branch,
the B<interchange branch>.
-This branch is found on Debian contributor's workstations
+This branch is found on Debian contributors' workstations
(typically, a maintainer would call it B<master>),
in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
and on other git servers which support Debian work
The breakwater does not contain any representation of
the delta queue (not even debian/patches).
The part of the breakwater processed by git-debrebase
-is the part since the most re
ecent B<anchor>,
+is the part since the most recent B<anchor>,
which is usually a special merge generated by git-debrebase.
When working, locally,
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
=item Delta queue commits
Zero or more single-parent commits
-contaioning only changes to upstream files.
+containing only changes to upstream files.
=back
It has the same contents as the laundered state,
except that it may contain,
additionally,
-in B<in any order but after the breakwater>:
+B<in any order but after the breakwater>:
=over
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 about what a problem is.
+To determine whether a branch
+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,
=head1 LEGAL OPERATIONS
-The following basic operations follows from this model
+The following basic operations follow from this model
(refer to the diagram above):
=over
=item Stitch
Make a pseudomerge,
-whose contributing parent to is the unstitched branch
+whose contributing parent is the unstitched branch
and
whose overwritten parent is ffq-prev,
consuming ffq-prev in the process
=item Commit quilt patches
To generate a tree which can be represented as a
-3.0 (quilt) .dsc source packages,
+3.0 (quilt) .dsc source package,
the delta queue must be reified inside the git tree
in B<debian/patches/>.
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 made 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: export and commit patches]
+ [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,
~ianmdlvl / dgit.git / blobdiff