diff options
Diffstat (limited to 'git-debrebase.5.pod')
| -rw-r--r-- | git-debrebase.5.pod | 67 |
1 files changed, 45 insertions, 22 deletions
diff --git a/git-debrebase.5.pod b/git-debrebase.5.pod index f181a40..b9abba0 100644 --- a/git-debrebase.5.pod +++ b/git-debrebase.5.pod @@ -19,10 +19,13 @@ 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. -git-debrebase is not very suitable for use by Debian derivatives, +git-debrebase +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 +derivatives, and it can make some things easier. =head1 DIAGRAM @@ -30,7 +33,7 @@ provided by your upstream. / / / with debian/ directory % % % entire delta queue applied / / / 3.0 (quilt) has debian/patches - / / 3* + / / 3* "master" on Debian git servers / / / 2* 2* 2 / / / @@ -65,7 +68,7 @@ provided by your upstream. Rebase branch launderer turns each ! into an equivalent *. -=head1 BRANCHES AND BRANCH STATES +=head1 BRANCHES AND BRANCH STATES - OVERVIEW git-debrebase has one primary branch, the B<interchange branch>. @@ -95,7 +98,7 @@ The breakwater contains unmodified upstream source, but with Debian's packaging superimposed (replacing any C<debian/> directory that may be in upstream). The breakwater does not contain any representation of -the delta queue. +the delta queue (not even debian/patches). The part of the breakwater processed by git-debrebase is the part since the most reecent B<anchor>, which is usually a special merge generated by git-debrebase. @@ -104,7 +107,9 @@ When working, locally, the user's branch can be in a rebasing state, known as B<unstitched>. While a branch is unstitched, -its previous tip is recorded, +it is not in interchange format. +The previous interchange branch tip +tip is recorded, so that the previous history and the user's work can later be @@ -172,9 +177,9 @@ contaioning only changes to upstream files. =back -An +The merely B<unstitched> -(unlaundered) +(ie, unstitched but unlaundered) branch state is also B<rebasing>. It has the same contents as the laundered state, except that it may contain, @@ -196,10 +201,14 @@ possibly mixed within a single commit. Commit(s) which add patches to B<debian/patches/>, and add those patches to the end of B<series>. + 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. +git-debrebase takes care to make a proper patch +series out of the delta queue, +so that any resulting source packages are nice. =back @@ -221,7 +230,7 @@ A pseudomerge making the branch fast forward from previous history. The contributing parent is itself in interchange format. Normally the overwritten parent is -a previous tip of the interchange branch, +a previous tip of an interchange branch, but this is not necessary as the overwritten parent is not examined. @@ -229,7 +238,7 @@ 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. +the first parent. =item dgit dsc import @@ -247,7 +256,7 @@ when it imports .dsc-based uploads. =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD Whenever the branch C<refs/B> is unstitched, -the previous tip is recorded in the git ref C<refs/ffq-prev/B>. +the previous head is recorded in the git ref C<refs/ffq-prev/B>. Unstiched branches are not fast forward from the published interchange branches [1]. @@ -288,6 +297,12 @@ 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 +should be be avoided +because +they might generate such merges. + Automatic resolution of divergent interchange branches (or laundering of merges on the interchange branch) is thought to be possible, @@ -327,7 +342,7 @@ or both. =item Launder branch -Record the previous tip in ffq-prev, +Record the previous head in ffq-prev, if we were stitched before (and delete debrebase-last). @@ -336,7 +351,7 @@ 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. +Drop pseudomerges and any quilt patch additions. =item Interactive rebase @@ -346,12 +361,13 @@ one can do an interactive git rebase of the delta queue. =item New upstream rebase Start rebasing onto a new upstream version, -turning C<...#..@-A-B-1-2-3> into C<(...#..@-A-B-|...#'-)@'-1-2>. +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 the commit list. +@' doesn't appear in the commit list, since +@' is the newbase of the rebase (see git-rebase(1)). Note that the construction of @' cannot fail because @' simply copies debian/ from B and and everything else from #'. @@ -433,14 +449,20 @@ but is not normally needed when using git-debrebase. =item Packaging files -Files in the source tree within B<debian/>. -(Does not include anything which may exist in B<debian/patches/>.) +Files in the source tree within B<debian/>, +excluding anything in B<debian/patches/>. =item Upstream The version of the package without Debian's packaging. Typically provided by the actual upstream project, -and often tracked by Debian contributors in a branch C<upstream>. +and sometimes tracked by Debian contributors in a branch C<upstream>. + +Upstream contains upstream files, +but some upstreams also contain packaging files in B<debian/>. +Any such non-upstream files found in upstream +are thrown away by git-debrebase +each time a new upstream version is incorporated. =item Upstream files @@ -457,7 +479,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, and often deleted, by git-debrebase. +Not used, often deleted, and regenerated when needed, +by git-debrebase. =back @@ -471,7 +494,7 @@ Consider a non-dgit NMU followed by a dgit NMU: / 3 / 2 / 1 - 2* &_ + 2 &_ / /| \ 1 0 00 =XBC% / @@ -481,7 +504,7 @@ Consider a non-dgit NMU followed by a dgit NMU: --#--------> upstream - Key: + Supplementary key: =XBC% dgit tarball import of .debian.tar.gz containing Debian packaging including changes B C and quilt patches @@ -507,7 +530,7 @@ We want to transform this into: / 3 3 / 2 2 / 1 1 - 2* &_ / + 2 &_ / / /| \ / 1 0 00 =XBC% / / / @@ -526,7 +549,7 @@ We want to transform this into: / 3 3 / 2 2 / 1 1 - 2* &_ / + 2 &_ / / /| \ / 1 0 00 =XBC% / / / |