From 4d17885419daca2127f870a06503ec5643d0f626 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Sun, 18 Feb 2018 22:28:31 +0000 Subject: [PATCH 1/1] git-debrebase(5): Terminology fixes, cleanups Signed-off-by: Ian Jackson --- git-debrebase.5.pod | 94 ++++++++++++++++++++++++++++++--------------- 1 file changed, 63 insertions(+), 31 deletions(-) diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index ce982369..6fc1ae54 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -10,14 +10,14 @@ Debian packages based on upstream source code. The Debian packaging has a fast forwarding history. -The changes to upstream files are represented +The delta queue (changes to upstream files) is represented as a series of individual git commits, which can worked on with rebase, and also shared. 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 Debian. +for example to work on Debian-format packages outside or alongside Debian. git-debrebase is not very suitable for use by Debian derivatives, to work on packages inherited from Debian, @@ -28,7 +28,7 @@ provided by your upstream. ------/--A!----/--B3!--%--/--> interchange view / / / with debian/ directory - % % % all upstream changes applied + % % % entire delta queue applied / / / 3.0 (quilt) has debian/patches / / 3* / / / @@ -54,11 +54,11 @@ provided by your upstream. / parent lower on diagram. % dgit-generated commit of debian/patches. - `3.0 (quilt)' only; dropped by rebase tool. + `3.0 (quilt)' only; generally dropped by git-debrebase. * 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 + tools made -/- (and maybe %) to convert to the fast-forwarding interchange branch. ! NMUer's HEAD was here when they said `dgit push'. @@ -72,7 +72,7 @@ the B. This branch is found on Debian contributor's workstations (typically, a maintainer would call it B), in the Debian dgit git server as the suite branch (B) -and on other git servers which support Debian owrk +and on other git servers which support Debian work (eg B on salsa). The interchange branch is fast-forwarding @@ -82,35 +82,39 @@ It is possible to have multiple different interchange branches for the same package, stored as different local and remote git branches. However, divergence should be avoided where possible - -see L. +see L. A suitable interchange branch can be used directly with dgit. In this case each dgit archive suite branch is a separate interchange branch. -Within the ancenstry of the interchange branch, -there is another importnt, implicit branch, the +Within the ancestry of the interchange branch, +there is another important, implicit branch, the B. The breakwater contains unmodified upstream source, but with Debian's packaging superimposed (replacing any C directory that may be in upstream). -The breakwater does not contain any representation -of Debian's changes to upstream files. -The breakwater starts at an B, +The breakwater does not contain any representation of +the delta queue. +The part of the breakwater processed by git-debrebase +is the part since the most reecent B, which is usually a special merge generated by git-debrebase. When working, locally, the user's branch can be in a rebasing state, known as B. -When a branch is unstitched, -its previous tip is recorded so that it can later be +While a branch is unstitched, +its previous tip is recorded, +so that the previous history +and the user's work +can later be stitched into the fast-forwarding interchange form. An unstitched branch may be in B state, which means it has a more particular special form -convenient for manipulating the changes to upstream files. +convenient for manipulating the delta queue. =head1 BRANCH CONTENTS @@ -125,10 +129,12 @@ It contains B (ancestors first): An B commit, which is usually a special two-parent merge: -The first parent is a previous breakwater branch, +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; +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. Anchor merges always contain @@ -143,9 +149,9 @@ ie, the start of Debian packaging. Zero or more single-parent commits containing only packaging changes. -(And no changes to B.) +(And no quilt patch changes.) -=item Delta from upstream +=item Delta queue commits Zero or more single-parent commits contaioning only changes to upstream files. @@ -169,14 +175,16 @@ to upstream files and/or to packaging, possibly mixed within a single commit. -(But no changes to B.) +(But not quilt patch changes.) -=item Patch addition for `3.0 (quilt)' +=item Quilt patch addition for `3.0 (quilt)' Commit(s) which add patches to B, and add those patches to the end of B. -These are only necessary or useful when working with +These are only necessary when working with packages in C<.dsc 3.0 (quilt)> format. +For git-debrebase they are purely an output; +they are deleted when branches are laundered. =back @@ -199,6 +207,12 @@ a previous tip of the interchange branch, 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 left parent. + =item dgit dsc import Debian .dsc source package import(s) made by dgit. @@ -206,8 +220,9 @@ 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 -(and will be generated that way by normal use of dgit). +the previous interchange tip. +This is the form normally generated by dgit +when it imports .dsc-based uploads. =back @@ -237,7 +252,7 @@ in similar circumstances and with similar warnings to sharing any other rebasing git branch. [1] Strictly, for a package -which has never had Debian changes to upstream files, +which has never had a Debian delta queue, the interchange and breakwater branches may be identical, in which case the unstitched branch is fast forward from the interchange branch and no pseudomerge is needed. @@ -289,8 +304,9 @@ or both. Record the previous tip in ffq-prev, if we were stitched before. -Reorganise the current branch so that the debian/ +Reorganise the current branch so that the packaging changes come first, +followed by the delta queue, turning C<-@-A-1-2-B3> into C<...@-A-B-1-2-3>. Drop pseudomerges and any quilt patches. @@ -308,7 +324,7 @@ 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. +@' doesn't appear in the commit list. Note that the construction of @' cannot fail because @' simply copies debian/ from B and and everything else from #'. @@ -319,9 +335,14 @@ so that git log shows the packaging history.) =item Stitch Make a pseudomerge, -overwriting (and consuming) ffq-prev. +whose contributing parent to is the unstitched branch +and +whose overwritten parent is ffq-prev, +consuming ffq-prev in the process. +Ideally the contributing parent would be a laundered branch, +or perhaps a laundered branch with a quilt patch addition commit. -=item Commit patches +=item Commit quilt patches To generate a tree which can be represented as a 3.0 (quilt) .dsc source packages, @@ -338,7 +359,7 @@ in B. =item Pseudomerge A merge which does not actually merge the trees; -instead, it takes its tree by construction from one parent. +instead, it takes its tree, by construction, from only one parent. These are used to make a rewritten history fast forward from a previous tip, so that it can be pushed and pulled normally. @@ -363,6 +384,17 @@ Files in the source tree outside B. These may include unmodified source from upstream, but also files which have been modified or created for Debian. +=item Delta queue + +Debian's changes to upstream files: +a series of git commits. + +=item Quilt patches + +Files in B generated for the benefit of +dpkg-source's 3.0 (quilt) .dsc source package format. +Not used, and often deleted, by git-debrebase. + =back =head1 APPENDIX - DGIT IMPORT HANDLING @@ -388,7 +420,7 @@ Consider a non-dgit NMU followed by a dgit NMU: Key: =XBC% dgit tarball import of .debian.tar.gz containing - Debian packaging including changes B C and 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 -- 2.30.2