3 git-debrebase - git data model for Debian packaging
7 git-debrebase is a tool for representing in git,
9 Debian packages based on upstream source code.
12 has a fast forwarding history.
13 The changes to upstream files are represented
14 as a series of individual git commits,
15 which can worked on with rebase,
18 git-debrebase is designed to work well with dgit.
19 git-debrebase can also be used in workflows without source packages,
20 for example to work on Debian-format packages outside Debian.
22 git-debrebase is not very suitable for use by Debian derivatives,
23 to work on packages inherited from Debian,
24 because it assumes that you want to throw away any packaging
25 provided by your upstream.
29 ------/--A!----/--B3!--%--/--> interchange view
30 / / / with debian/ directory
31 % % % all upstream changes applied
32 / / / 3.0 (quilt) has debian/patches
37 1 1 1 `breakwater' branch, merging baseline
38 / / / unmodified upstream code
39 ---@-----@--A----@--B--C plus debian/ (but no debian/patches)
40 / / / no ref refers to this: we
41 --#-----#-------#-----> upstream reconstruct its identity by
42 inspecting interchange branch
45 1,2,3 commits touching upstream files only
46 A,B,C commits touching debian/ only
47 B3 mixed commit (eg made by an NMUer)
50 -@- anchor merge, takes contents of debian/ from the
51 / previous `breakwater' commit and rest from upstream
53 -/- pseudomerge; contents are identical to
54 / parent lower on diagram.
56 % dgit-generated commit of debian/patches.
57 `3.0 (quilt)' only; dropped by rebase tool.
59 * Maintainer's HEAD was here while they were editing,
60 before they said they were done, at which point their
61 tools generated [% and] -/- commit[s] to convert to
62 the fast-forwarding interchange branch. (Maybe the
63 tooling is simply `dgit push'.)
65 ! NMUer's HEAD was here when they said `dgit push'.
66 Rebase branch launderer turns each ! into an
69 =head1 BRANCHES AND BRANCH STATES
71 git-debrebase has one primary branch,
72 the B<interchange branch>.
73 This branch is found on Debian contributor's workstations
74 (typically, a maintainer would call it B<master>),
75 in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
76 and on other git servers which support Debian owrk
77 (eg B<master> on salsa).
79 The interchange branch is fast-forwarding
80 (by virtue of pseudomerges, where necessary).
82 It is possible to have multiple different interchange branches
84 stored as different local and remote git branches.
85 However, divergence should be avoided where possible -
86 see L</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
88 A suitable interchange branch can be used directly with dgit.
89 In this case each dgit archive suite branch is a separate
92 Within the ancenstry of the interchange branch,
93 there is another importnt, implicit branch, the
95 The breakwater contains unmodified upstream source,
96 but with Debian's packaging superimposed
97 (replacing any C<debian/> directory that may be in upstream).
98 The breakwater does not contain any representation
99 of Debian's changes to upstream files.
100 The breakwater starts at an B<anchor>,
101 which is usually a special merge generated by git-debrebase.
103 When working, locally,
104 the user's branch can be in a rebasing state,
105 known as B<unstitched>.
106 When a branch is unstitched,
107 its previous tip is recorded so that it can later be
108 stitched into the fast-forwarding interchange form.
110 An unstitched branch may be in
113 which means it has a more particular special form
114 convenient for manipulating the changes to upstream files.
116 =head1 BRANCH CONTENTS
118 It is most convenient to describe the
121 It contains B<in this order> (ancestors first):
128 which is usually a special two-parent merge:
129 The first parent is a previous breakwater branch,
130 whose upstream files are irrelevant,
131 and whose packaging files are identical to the anchor's.
132 The second parent is an upstream source commit;
133 whose packaging files (if any) are irrelevant,
134 and whose upstream files are identical to the anchor's.
135 Anchor merges always contain
136 C<[git-debrebase anchor: ...]>
137 as a line in the commit message.
139 an anchor may be a single-parent commit which introduces
140 the C<debian/> directory and makes no other changes:
141 ie, the start of Debian packaging.
145 Zero or more single-parent commits
146 containing only packaging changes.
147 (And no changes to B<debian/patches/>.)
149 =item Delta from upstream
151 Zero or more single-parent commits
152 contaioning only changes to upstream files.
159 branch state is the same,
160 except that it may contain,
166 =item Linear commits to the source
168 Further commit(s) containing changes to
172 possibly mixed within a single commit.
173 (But no changes to B<debian/patches/>.)
175 =item Patch addition for `3.0 (quilt)'
177 Commit(s) which add patches to B<debian/patches/>,
178 and add those patches to the end of B<series>.
179 These are only necessary or useful when working with
180 packages in C<.dsc 3.0 (quilt)> format.
186 branch state is the same, but may additionally contain
188 possibly intermixed with the extra commits
189 which may be found on an unstitched unlaundered branch):
193 =item Pseudomerge to make fast forward
195 A pseudomerge making the branch fast forward from
197 The contributing parent is itself in interchange format.
198 Normally the overwritten parent is
199 a previous tip of the interchange branch,
200 but this is not necessary as the overwritten
201 parent is not examined.
203 =item dgit dsc import
205 Debian .dsc source package import(s) made by dgit.
206 Each such import must be a two-parent pseudomerge
207 whose contributing parent is in the special
208 dgit format (not described further here).
209 The overwritten parent must be
210 the previous interchange tip
211 (and will be generated that way by normal use of dgit).
215 =head1 STITCHING, PSEUDO-MERGES, FFQ RECORD
217 Whenever the branch C<refs/B> is unstitched,
218 the previous tip is recorded in the git ref C<refs/ffq-prev/heads/B>.
220 Unstiched branches are not fast forward from the published
221 interchange branches. [1]
222 So before a branch can be pushed,
223 the right pseudomerge must be reestablished.
224 This is the stitch operation,
225 which consumes the ffq-prev ref.
227 When the user has an unstituched branch,
228 they may rewrite it freely,
229 from the breakwater tip onwards.
230 Such a git rebase is the default operation for git-debrebase.
231 Rebases should not go back before the breakwater tip,
232 and certainly not before the most recent anchor.
234 Unstitched branches must not be pushed to interchange branch refs
235 (by the use of C<git push -f> or equivalent).
236 It is OK to share an unstitched branch
237 in similar circumstances and with similar warnings
238 to sharing any other rebasing git branch.
240 [1] Strictly, for a package
241 which has never had Debian changes to upstream files,
242 the interchange and breakwater branches may be identical,
243 in which case the unstitched branch is fast forward
244 from the interchange branch and no pseudomerge is needed.
248 Note that the representation described here does not permit
249 general merges on any of the relevant branches.
250 For this reason the tools will try to help the user
251 avoid divergence of the interchange branch.
253 Automatic resolution of divergent interchange branches
254 (or laundering of merges on the interchange branch)
255 is thought to be possible,
256 but there is no tooling for this yet:
258 Nonlinear (merging) history in the interchange branch is awkward
259 because it (obviously) does not preserve
260 the linearity of the delta queue.
261 Easy merging of divergent delta queues is a research problem.
263 Nonlinear (merging) history in the breakwater branch is
264 in principle tolerable,
265 but each of the parents would have to be, in turn,
267 and difficult qeustions arise if they don't have the same anchor.
269 We use the commit message annotation to
270 distinguish the special anchor merges from other general merges,
271 so we can at least detect unsupported merges.
279 A merge which does not actually merge the trees;
280 instead, it takes its tree by construction from one parent.
281 These are used to make a rewritten history fast forward
283 so that it can be pushed and pulled normally.
284 Manual construction of pseudomerges can be done with
286 but is not normally needed when using git-debrebase.
288 =item Packaging files
290 Files in the source tree within B<debian/>.
291 (Does not include anything which may exist in B<debian/patches/>.)
295 The version of the package without Debian's packaging.
296 Typically provided by the actual upstream project,
297 and often tracked by Debian contributors in a branch C<upstream>.
301 Files in the source tree outside B<debian/>.
302 These may include unmodified source from upstream,
303 but also files which have been modified or created for Debian.
307 =head1 APPENDIX - DGIT IMPORT HANDLING
309 Consider a non-dgit NMU followed by a dgit NMU:
311 interchange --/--B3!--%--/----D*-->
324 --#--------> upstream
329 =XBC% dgit tarball import of .debian.tar.gz containing
330 Debian packaging including changes B C and patches
332 0 dgit tarball import of upstream tarball
333 00 dgit tarball import of supplementary upstream tarball
334 &_ dgit nearly-breakwater import
335 &' git-debrebase converted import (upstream files only)
336 D' git-debrebase converted debian/ changes import
338 * ** before and after HEAD
340 We want to transform this into:
342 I. No new upstream version (0 + 00 eq #)
344 --/--B3!--%--/------D*-------------/-->
355 --@--A-----B-----------------------C--D
357 --#----------------------------------------->
360 II. New upstream (0 + 00 neq #)
362 --/--B3!--%--/------D*-------------/-->
373 --@--A-----B--------------------@--C--D
375 --#----------------------- - - / - - ----->
383 dgit(1), dgit(7), dgit-maint-*(7)