X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=git-debrebase.5.pod;h=e445c0e6001354bd337d8b01f7b8859ed98150d1;hp=26e4813f72eadb879c5280a626f6d66829eb89aa;hb=f8ba14071c7977a0ea2d8f1882202136b7b88dce;hpb=58eb6a81d7b7cc482fa36f2f653c393f84d927da diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index 26e4813f..e445c0e6 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -24,7 +24,7 @@ itself is not very suitable for use by Debian derivatives, 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. =head1 TERMINOLOGY @@ -123,7 +123,7 @@ See L. -/- 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, @@ -177,7 +177,7 @@ known as B. 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 @@ -381,8 +381,8 @@ general merges on any of the relevant branches. 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. @@ -401,7 +401,7 @@ Nonlinear (merging) history in the breakwater branch is 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, @@ -501,6 +501,7 @@ The full set of annotations is: [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 convert-from-gbp: drop patches] [git-debrebase anchor: declare upstream] @@ -510,7 +511,8 @@ The full set of annotations is: 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 and C tags are added to the pre-existing commit message, @@ -518,9 +520,14 @@ when git-debrebase rewrites the commit. =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 @@ -531,21 +538,22 @@ Consider a non-dgit NMU followed by a dgit NMU: 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 @@ -556,43 +564,43 @@ We want to transform this into: =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