summaryrefslogtreecommitdiff
path: root/git-debrebase.5.pod
diff options
context:
space:
mode:
authorIan Jackson <ijackson@chiark.greenend.org.uk>2018-04-14 16:24:23 +0100
committerIan Jackson <ijackson@chiark.greenend.org.uk>2018-06-16 16:07:00 +0100
commit134858eaf9df5e8e6f03c67b40c8ce4cc119b41e (patch)
tree224464fb5f005c2ba7269025ea6f9f04573cd5cb /git-debrebase.5.pod
parent190c045107f1681dd7f5232bd3ad41088e0a8244 (diff)
git-debrebase(1),(5): More changes from conversation with Sean
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
Diffstat (limited to 'git-debrebase.5.pod')
-rw-r--r--git-debrebase.5.pod76
1 files changed, 48 insertions, 28 deletions
diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod
index f749f62..d3ecda8 100644
--- a/git-debrebase.5.pod
+++ b/git-debrebase.5.pod
@@ -34,7 +34,9 @@ derivatives, and it can make some things easier.
=item Pseudomerge
A merge which does not actually merge the trees;
-instead, it takes its tree, by construction, from only one parent.
+instead, it is constructed by taking the tree
+from one of the parents
+(ignoring the contents of the other parents).
These are used to make a rewritten history fast forward
from a previous tip,
so that it can be pushed and pulled normally.
@@ -74,7 +76,8 @@ a series of git commits.
Files in B<debian/patches/> generated for the benefit of
dpkg-source's 3.0 (quilt) .dsc source package format.
-Not used, often deleted, and regenerated when needed,
+Not used, often deleted, and regenerated when needed
+(such as when uploading to Debian),
by git-debrebase.
=back
@@ -148,7 +151,8 @@ there is another important, implicit branch, the
B<breakwater>.
The breakwater contains unmodified upstream source,
but with Debian's packaging superimposed
-(replacing any C<debian/> directory that may be in upstream).
+(replacing any C<debian/> directory that may be in
+the upstream commits).
The breakwater does not contain any representation of
the delta queue (not even debian/patches).
The part of the breakwater processed by git-debrebase
@@ -188,17 +192,24 @@ It contains B<in this order> (ancestors first):
An B<anchor> commit,
which is usually a special two-parent merge:
-The first parent is
-a previous branch tip with Debian packaging tip
-(perhaps a previous breakwater tip)
-whose upstream files are irrelevant,
-and whose packaging files are identical to the anchor's.
-The second parent is an upstream source commit,
-whose packaging files (if any) are irrelevant,
-and whose upstream files are identical to the anchor's.
+
+The first parent
+contains the most recent version, at that point,
+of the Debian packaging (in debian/);
+it also often contains upstream files,
+but they are to be ignored.
+Often the first parent is a previous breakwater tip.
+
+The second parent
+is an upstream source commit.
+It may sometimes contain a debian/ subdirectory,
+but if so that is to be ignored.
+The second parent's upstream files
+are identical to the anchor's.
Anchor merges always contain
C<[git-debrebase anchor: ...]>
as a line in the commit message.
+
Alternatively,
an anchor may be a single-parent commit which introduces
the C<debian/> directory and makes no other changes:
@@ -287,21 +298,30 @@ but this is not necessary as the overwritten
parent is not examined.
If the two parents have identical trees,
-the contributing parent is taken to be
-the one with the later commit date,
-or if the commit dates are the same,
-the first parent.
-
-=item dgit dsc import
-
-Debian .dsc source package import(s) made by dgit.
-Each such import must be a two-parent pseudomerge
-whose contributing parent is in the special
-dgit format (not described further here).
-The overwritten parent must be
-the previous interchange tip.
-This is the form normally generated by dgit
-when it imports .dsc-based uploads.
+the one with the later commit date
+(or, if the commit dates are the same,
+the first parent)
+is treated as
+the contributing parent.
+
+=item dgit dsc import pseudomerge
+
+Debian .dsc source package import(s)
+made by dgit
+(during dgit fetch of a package most recently
+uploaded to Debian without dgit,
+or during dgit import-dsc).
+
+git-debrebase requires that
+each such import is in the fast-forwarding
+format produced by dgit:
+a two-parent pseudomerge,
+whose contributing parent is in the
+non-fast-forwarding
+dgit dsc import format (not described further here),
+and whose overwritten parent is
+the previous interchange tip
+(eg, the previous tip of the dgit suite branch).
=back
@@ -457,8 +477,8 @@ The general form is
[git-debrebase[ COMMIT-TYPE [ ARGS...]]: PROSE, MORE PROSE]
-git-debrebase does not pay attention to anything after the colon,
-so PROSE is ignored.
+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]