chiark / gitweb /
Arrange to pass --debug-quick-random to gpg-agent.
[dgit.git] / dgit.7
1 .TH dgit 7 "" "Debian Project" "dgit"
2 .SH NAME
3 dgit \- principles of operation
4 .SH SUMMARY
5 .B dgit
6 treats the Debian archive as a version control system, and
7 bidirectionally gateways between the archive and git.  The git view of
8 the package can contain the usual upstream git history, and will be
9 augmented by commits representing uploads done by other developers not
10 using dgit.  This git history is stored in a canonical location known
11 as
12 .B dgit-repos
13 which lives on a dedicated git server.
14
15 git branches suitable for use with dgit
16 can be edited directly in git,
17 and used directly for building binary packages.
18 They can be shared using all conventional means for sharing git
19 branches.
20 It is not necessary to use dgit to work with dgitish git branches.
21 However, dgit is (usually) needed in order to convert to or from
22 Debian-format source packages.
23 .SH SEE ALSO
24 .TP
25 \fBdgit\fP(1)
26 Reference manual and documentation catalogue.
27 .TP
28 \fBdgit-*\fB(7)
29 Tutorials and workflow guides.  See dgit(1) for a list.
30 .SH MODEL
31 You may use any suitable git workflow with dgit, provided you
32 satisfy dgit's requirements:
33
34 dgit maintains a pseudo-remote called
35 .BR dgit ,
36 with one branch per suite.  This remote cannot be used with
37 plain git.
38
39 The
40 .B dgit-repos
41 repository for each package contains one ref per suite named
42 \fBrefs/dgit/\fR\fIsuite\fR.  These should be pushed to only by
43 dgit.  They are fast forwarding.  Each push on this branch
44 corresponds to an upload (or attempted upload).
45
46 However, it is perfectly fine to have other branches in dgit-repos;
47 normally the dgit-repos repo for the package will be accessible via
48 the remote name `origin'.
49
50 dgit push will also make signed tags called
51 .BI archive/debian/ version
52 (with version encoded a la DEP-14)
53 and push them to dgit-repos.  These are used at the
54 server to authenticate pushes.
55
56 Uploads made by dgit contain an additional field
57 .B Dgit
58 in the source package .dsc.  (This is added by dgit push.)
59 This specifies a commit (an ancestor of the dgit/suite
60 branch) whose tree is identical to the unpacked source upload.
61
62 Uploads not made by dgit are represented in git by commits which are
63 synthesised by dgit.  The tree of each such commit corresponds to the
64 unpacked source; there is a
65 commit with the contents,
66 and a
67 pseudo-merge from last known upload - that is, from the contents of
68 the dgit/suite branch.
69 Depending on the source package format,
70 the contents commit may have a more complex structure,
71 but ultimately it will be a convergence of stubby branches
72 from origin commits representing the components of the source package.
73
74 dgit expects trees that it works with to have a
75 .B dgit
76 (pseudo) remote.  This refers to the dgit-created git view of
77 the corresponding archive.
78
79 The dgit archive tracking view is synthesised locally,
80 on demand,
81 by each copy of dgit.
82 The tracking view is always a descendant of the
83 dgit-repos suite branch (if one exists),
84 but may be ahead of it if uploads have been done without dgit.
85 The archive tracking view is always fast forwarding within
86 each suite.
87
88 dgit push can operate on any commit which is a descendant of
89 the suite tracking branch.
90
91 dgit does not make a systematic record of
92 its imports of orig tarball(s).
93 So it does not work by finding git tags or branches
94 referring to orig tarball(s).
95 The
96 orig tarballs are downloaded (by dgit clone) into the parent
97 directory, as with a traditional (non-gitish) dpkg-source workflow.
98 You need to retain these tarballs in the parent directory for dgit
99 build and dgit push.
100 (They are not needed for purely-git-based workflows.)
101
102 dgit repositories could be cloned with standard (git) methods.
103 However,
104 the dgit repositories do not contain uploads not made with dgit.
105 And
106 for sourceful builds / uploads the orig
107 tarball(s) will need to be present in the parent directory.
108
109 To a user looking at the archive, changes pushed
110 in a simple NMU
111 using dgit look like
112 reasonable
113 changes made in an NMU: in a `3.0 (quilt)' package the delta from the
114 previous upload is recorded in new patch(es) constructed by dpkg-source.
115 .SH COMBINED SUITES
116 dgit can synthesize a combined view of several underlying suites.
117 This is requested by specifying, for
118 .I suite,
119 a comma-separated list:
120 .IP
121 .IR mainsuite \fB,\fR subsuite ...
122 .LP
123 This facility is available with dgit clone, fetch and pull, only.
124
125 dgit will fetch the same package from each specified underlying suite,
126 separately (as if with dgit fetch).
127 dgit will then generate a pseudomerge commit
128 on the tracking branch
129 .BI remotes/dgit/dgit/ suite
130 which has the tip of each of the underlying suites
131 as an ancestor,
132 and which contains the same as the suite which
133 has the highest version of the package.
134
135 The package must exist in mainsuite,
136 but need not exist in the subsuites.
137
138 If a specified subsuite starts with
139 .B -
140 then mainsuite is prepended.
141
142 So, for example,
143 .B stable,-security
144 means to look for the package in stable, and stable-security,
145 taking whichever is newer.
146 If stable is currently jessie,
147 dgit clone would leave you on the branch
148 .BR dgit/jessie,-security .
149
150 Combined suites are not supported by the dgit build operations.
151 This is because those options are intended for building for
152 uploading source packages,
153 and look in the changelog to find the relevant suite.
154 It does not make sense to name a dgit-synthesised combined suite
155 in a changelog,
156 or to try to upload to it.
157
158 When using this facility, it is important to always specify the
159 same suites in the same order:
160 dgit will not be make a coherent fast-forwarding history
161 view otherwise.
162
163 The history generated by this feature is not normally suitable
164 for merging back into upstreams,
165 as it necessarily contains unattractive pseudomerges.
166 .SH LIMITATIONS
167 Because the synthesis
168 of the suite tracking branches
169 is done locally based only on the current archive state,
170 it will not necessarily see every upload
171 not done with dgit.
172 Also, different versions of dgit
173 (or the software it calls)
174 might import the same .dscs differently
175 (although we try to minimise this).
176 As a consequence, the dgit tracking views of the same
177 suite, made by different instances of dgit, may vary.
178 They will have the same contents, but may have different history.
179
180 There is no uniform linkage between the tracking branches for
181 different suites.
182 The Debian infrastructure
183 does not do any automatic import of uploads made without dgit.
184 It would be possible for a distro's infrastructure to do this;
185 in that case,
186 different dgit client instances
187 would see exactly the same history.
188
189 There has been no bulk import of historical uploads into
190 Debian's dgit infrastructure.
191 To do this it would be necessary to decide whether to
192 import existing vcs history
193 (which might not be faithful to dgit's invariants)
194 or previous non-Dgit uploads
195 (which would not provide a very rich history).
196 .SH READ-ONLY DISTROS
197 Distros which do not maintain a set of dgit history git repositories
198 can still be used in a read-only mode with dgit.  Currently Ubuntu
199 is configured this way.
200 .SH PACKAGE SOURCE FORMATS
201 If you are not the maintainer, you do not need to worry about the
202 source format of the package.  You can just make changes as you like
203 in git.  If the package is a `3.0 (quilt)' package, the patch stack
204 will usually not be represented in the git history.
205 .SH FORMAT 3.0 (QUILT)
206 For a format `3.0 (quilt)' source package, dgit may have to make a
207 commit on your current branch to contain metadata used by quilt and
208 dpkg-source.
209
210 This is because `3.0 (quilt)' source format represents the patch stack
211 as files in debian/patches/ actually inside the source tree.  This
212 means that, taking the whole tree (as seen by git or ls) (i)
213 dpkg-source cannot represent certain trees, and (ii) packing up a tree
214 in `3.0 (quilt)' and then unpacking it does not always yield the same
215 tree.
216
217 dgit will automatically work around this for you when building and
218 pushing.  The only thing you need to know is that dgit build, sbuild,
219 etc., may make new commits on your HEAD.  If you're not a quilt user
220 this commit won't contain any changes to files you care about.
221
222 You can explicitly request that dgit do just this fixup, by running
223 dgit quilt-fixup.
224
225 If you are a quilt user you need to know that dgit's git trees are
226 `patches applied packaging branches' and do not contain the .pc
227 directory (which is used by quilt to record which patches are
228 applied).  If you want to manipulate the patch stack you probably want
229 to be looking at tools like git-dpm.
230 .SH SPLIT VIEW QUILT MODE
231 When working with git branches intended
232 for use with the `3.0 (quilt)' source format
233 dgit can automatically convert a suitable
234 maintainer-provided git branch
235 (in one of a variety of formats)
236 into a dgit branch.
237
238 When a split view mode is engaged
239 dgit build commands and
240 dgit push
241 will, on each invocation,
242 convert the user's HEAD into the dgit view,
243 so that it can be built and/or uploaded.
244
245 dgit push in split view mode will push the dgit view to the dgit
246 git server.
247 The dgit view is always a descendant of the maintainer view.
248 dgit push will also make a maintainer view tag
249 according to DEP-14
250 and push that to the dgit git server.
251
252 Split view mode must be enabled explicitly
253 (by the use of the applicable command line options,
254 subcommands, or configuration).
255 This is because it is not possible to reliably tell
256 (for example)
257 whether a git tree for a dpkg-source `3.0 (quilt)' package
258 is a patches-applied or patches-unapplied tree.
259
260 Split view conversions are cached in the ref
261 dgit-intern/quilt-cache.
262 This should not be manipulated directly.
263 .SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT - AUTOTOOLS ETC.
264 This section is mainly of interest to maintainers who want to use dgit
265 with their existing git history for the Debian package.
266
267 Some developers like to have an extra-clean git tree which lacks files
268 which are normally found in source tarballs and therefore in Debian
269 source packages.  For example, it is conventional to ship ./configure
270 in the source tarball, but some people prefer not to have it present
271 in the git view of their project.
272
273 dgit requires that the source package unpacks to exactly the same
274 files as are in the git commit on which dgit push operates.  So if you
275 just try to dgit push directly from one of these extra-clean git
276 branches, it will fail.
277
278 As the maintainer you therefore have the following options:
279 .TP
280 \(bu
281 Persuade upstream that the source code in their git history and the
282 source they ship as tarballs should be identical.  Of course simply
283 removing the files from the tarball may make the tarball hard for
284 people to use.
285 .IP
286 One answer is to commit the (maybe autogenerated)
287 files, perhaps with some simple automation to deal with conflicts and
288 spurious changes.  This has the advantage that someone who clones
289 the git repository finds the program just as easy to build as someone
290 who uses the tarball.
291 .TP
292 \(bu
293 Have separate git branches which do contain the extra files, and after
294 regenerating the extra files (whenever you would have to anyway),
295 commit the result onto those branches.
296 .TP
297 \(bu
298 Provide source packages which lack the files you don't want
299 in git, and arrange for your package build to create them as needed.
300 This may mean not using upstream source tarballs and makes the Debian
301 source package less useful for people without Debian build
302 infrastructure.
303 .LP
304 Of course it may also be that the differences are due to build system
305 bugs, which cause unintended files to end up in the source package.
306 dgit will notice this and complain.  You may have to fix these bugs
307 before you can unify your existing git history with dgit's.
308 .LP
309 .SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT - DOCS, BINARIES ETC.
310 Some upstream tarballs contain build artifacts which upstream expects
311 some users not to want to rebuild (or indeed to find hard to rebuild),
312 but which in Debian we always rebuild.
313 .LP
314 Examples sometimes include crossbuild firmware binaries and
315 documentation.
316 To avoid problems when building updated source
317 packages
318 (in particular, to avoid trying to represent as changes in
319 the source package uninteresting or perhaps unrepresentable changes
320 to such files)
321 many maintainers arrange for the package clean target
322 to delete these files.
323 .LP
324 dpkg-source does not
325 (with any of the commonly used source formats)
326 represent deletion of files (outside debian/) present in upstream.
327 Thus deleting such files in a dpkg-source working tree does not
328 actually result in them being deleted from the source package.
329 Thus
330 deleting the files in rules clean sweeps this problem under the rug.
331 .LP
332 However, git does always properly record file deletion.
333 Since dgit's
334 principle is that the dgit git tree is the same of dpkg-source -x,
335 that means that a dgit-compatible git tree always contains these
336 files.
337 .LP
338 For the non-maintainer,
339 this can be observed in the following suboptimal occurrences:
340 .TP
341 \(bu
342 The package clean target often deletes these files, making the git
343 tree dirty trying to build the source package, etc.
344 This can be fixed
345 by using
346 .BR "dgit -wg" " aka " "--clean=git" ,
347 so that the package clean target is never run.
348 .TP
349 \(bu
350 The package build modifies these files, so that builds make the git
351 tree dirty.
352 This can be worked around by using `git reset --hard'
353 after each build
354 (or at least before each commit or push).
355 .LP
356 From the maintainer's point of view,
357 the main consequence is that to make a dgit-compatible git branch
358 it is necessary to commit these files to git.
359 The maintainer has a few additional options for mitigation:
360 for example,
361 it may be possible for the rules file to arrange to do the
362 build in a temporary area, which avoids updating the troublesome
363 files;
364 they can then be left in the git tree without seeing trouble.
365 .SH PROBLEMS WITH PACKAGE CLEAN TARGETS ETC.
366 A related problem is other unexpected behaviour by a package's
367 .B clean
368 target.
369 If a package's rules
370 modify files which are distributed in the package,
371 or simply forget to remove certain files,
372 dgit will complain that the tree is dirty.
373 .LP
374 Again, the solution is to use
375 .BR "dgit -wg" " aka " "--clean=git" ,
376 which instructs dgit to use git clean instead of the package's
377 build target,
378 along with perhaps
379 .B git reset --hard
380 before each build.
381 .LP
382 This is 100% reliable, but has the downside
383 that if you forget to git add or to commit, and then use
384 .BR "dgit -wg" " or " "git reset --hard" ,
385 your changes may be lost.