1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
|
=head1 NAME
git-debrebase - git data model for Debian packaging
=head1 INTRODUCTION
git-debrebase is a tool for representing in git,
and manpulating,
Debian packages based on upstream source code.
The Debian packaging
has a fast forwarding history.
The changes to upstream files are 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.
git-debrebase 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.
=head1 DIAGRAM
------/--A!----/--B3!--%--/--> interchange view
/ / / with debian/ directory
% % % all upstream changes applied
/ / / 3.0 (quilt) has debian/patches
/ / 3*
/ / /
2* 2* 2
/ / /
1 1 1 `breakwater' branch, merging baseline
/ / / unmodified upstream code
---@-----@--A----@--B--C plus debian/ (but no debian/patches)
/ / / no ref refers to this: we
--#-----#-------#-----> upstream reconstruct its identity by
inspecting interchange branch
Key:
1,2,3 commits touching upstream files only
A,B,C commits touching debian/ only
B3 mixed commit (eg made by an NMUer)
# upstream releases
-@- anchor merge, takes contents of debian/ from the
/ previous `breakwater' commit and rest from upstream
-/- pseudomerge; contents are identical to
/ parent lower on diagram.
% dgit-generated commit of debian/patches.
`3.0 (quilt)' only; dropped by rebase tool.
* 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
the fast-forwarding interchange branch. (Maybe the
tooling is simply `dgit push'.)
! NMUer's HEAD was here when they said `dgit push'.
Rebase branch launderer turns each ! into an
equivalent *.
=head1 BRANCHES AND BRANCH STATES
git-debrebase has one primary branch,
the B<interchange branch>.
This branch is found on Debian contributor's workstations
(typically, a maintainer would call it B<master>),
in the Debian dgit git server as the suite branch (B<dgit/dgit/sid>)
and on other git servers which support Debian owrk
(eg B<master> on salsa).
The interchange branch is fast-forwarding
(by virtue of pseudomerges, where necessary).
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</STITCHING, PSEUDO-MERGES, FFQ RECORD>.
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
B<breakwater>.
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 Debian's changes to upstream files.
The breakwater starts at an B<anchor>,
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<unstitched>.
When a branch is unstitched,
its previous tip is recorded so that it can later be
stitched into the fast-forwarding interchange form.
An unstitched branch may be in
B<laundered>
state,
which means it has a more particular special form
convenient for manipulating the changes to upstream files.
=head1 BRANCH CONTENTS
It is most convenient to describe the
B<laundered>
state first.
It contains B<in this order> (ancestors first):
=over
=item Anchor
An B<anchor> commit,
which is usually a special two-parent merge:
The first parent is a previous breakwater branch,
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.
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:
ie, the start of Debian packaging.
=item Packaging
Zero or more single-parent commits
containing only packaging changes.
(And no changes to B<debian/patches/>.)
=item Delta from upstream
Zero or more single-parent commits
contaioning only changes to upstream files.
=back
The
B<unstitched>
(unlaundered)
branch state is the same,
except that it may contain,
additionally,
in B<in any order>:
=over
=item Linear commits to the source
Further commit(s) containing changes to
to upstream files
and/or
to packaging,
possibly mixed within a single commit.
(But no changes to B<debian/patches/>.)
=item Patch addition for `3.0 (quilt)'
Commit(s) which add patches to B<debian/patches/>,
and add those patches to the end of B<series>.
These are only necessary or useful when working with
packages in C<.dsc 3.0 (quilt)> format.
=back
The
B<interchange>
branch state is the same, but may additionally contain
(in some order,
possibly intermixed with the extra commits
which may be found on an unstitched unlaundered branch):
=over
=item Pseudomerge to make fast forward
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,
but this is not necessary as the overwritten
parent is not examined.
=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
(and will be generated that way by normal use of dgit).
=back
=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/heads/B>.
Unstiched branches are not fast forward from the published
interchange branches. [1]
So before a branch can be pushed,
the right pseudomerge must be reestablished.
This is the stitch operation,
which consumes the ffq-prev ref.
When the user has an unstituched branch,
they may rewrite it freely,
from the breakwater tip onwards.
Such a git rebase is the default operation for git-debrebase.
Rebases should not go back before the breakwater tip,
and certainly not before the most recent anchor.
Unstitched branches must not be pushed to interchange branch refs
(by the use of C<git push -f> or equivalent).
It is OK to share an unstitched branch
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,
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.
=head1 OTHER MERGES
Note that the representation described here does not permit
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.
Automatic resolution of divergent interchange branches
(or laundering of merges on the interchange branch)
is thought to be possible,
but there is no tooling for this yet:
Nonlinear (merging) history in the interchange branch is awkward
because it (obviously) does not preserve
the linearity of the delta queue.
Easy merging of divergent delta queues is a research problem.
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.
We use the commit message annotation to
distinguish the special anchor merges from other general merges,
so we can at least detect unsupported merges.
=head1 TERMINOLOGY
=over
=item Pseudomerge
A merge which does not actually merge the trees;
instead, it takes its tree by construction from 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.
Manual construction of pseudomerges can be done with
C<git merge -s ours>
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/>.)
=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>.
=item Upstream files
Files in the source tree outside B<debian/>.
These may include unmodified source from upstream,
but also files which have been modified or created for Debian.
=back
=head1 APPENDIX - DGIT IMPORT HANDLING
Consider a non-dgit NMU followed by a dgit NMU:
interchange --/--B3!--%--/----D*-->
/ /
% 4
/ 3
/ 2
/ 1
2* &_
/ /| \
1 0 00 =XBC%
/
/
--@--A breakwater
/
--#--------> upstream
Key:
=XBC% dgit tarball import of .debian.tar.gz containing
Debian packaging including changes B C and patches
0 dgit tarball import of upstream tarball
00 dgit tarball import of supplementary upstream tarball
&_ dgit nearly-breakwater import
&' git-debrebase converted import (upstream files only)
D' git-debrebase converted debian/ changes import
* ** before and after HEAD
We want to transform this into:
I. No new upstream version (0 + 00 eq #)
--/--B3!--%--/------D*-------------/-->
/ / /
% 4 4**
/ 3 3
/ 2 2
/ 1 1
2* &_ /
/ /| \ /
1 0 00 =XBC% /
/ /
/ /
--@--A-----B-----------------------C--D
/
--#----------------------------------------->
II. New upstream (0 + 00 neq #)
--/--B3!--%--/------D*-------------/-->
/ / /
% 4 4**
/ 3 3
/ 2 2
/ 1 1
2* &_ /
/ /| \ /
1 0 00 =XBC% /
/ /
/ /
--@--A-----B--------------------@--C--D
/ /
--#----------------------- - - / - - ----->
/
&'
/|
0 00
=head1 SEE ALSO
dgit(1), dgit(7), dgit-maint-*(7)
|
