chiark / gitweb /
Merge branch stable into master
[dgit.git] / dgit.1
1 '\" t
2 .TH dgit 1 "" "Debian Project" "dgit"
4 dgit \- git integration with the Debian archive
5 .
7 .B dgit
8 [\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]
9 \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
10 .br
11 .B dgit
12 [\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
13 [\fIsuite\fP]
14 .br
15 .B dgit
16 [\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP
17 [\fIbuild\-opts\fp]
18 .br
19 .B dgit
20 [\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
21 [\fIsuite\fP]
22 .br
23 .B dgit
24 [\fIdgit\-opts\fP] \fBrpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR
25 [\fIpush args...\fR]
26 .br
27 .B dgit
28 [\fIdgit\-opts\fP] \fIaction\fR ...
30 .B dgit
31 allows you to treat the Debian archive as if it were a git
32 repository.
33 Conversely,
34 it allows Debian to publish the source of its packages
35 as git branches, in a format which is directly useable
36 by ordinary people.
38 This is the command line reference.
39 Please read the tutorial(s):
40 .TS
41 lb l.
42 dgit-user(7)    for users: editing, building and sharing packages
43 dgit-nmu-simple(7)      for DDs: doing a straightforward NMU
44 dgit-maint-native(7)    for maintainers of Debian-native packages
45 dgit-maint-merge(7)     for maintainers who want a pure git workflow
46 dgit-maint-gbp(7)       for maintainers already using git-buildpackage
47 dgit-sponsorship(7)     for sponsors and sponsored contributors
48 .TE
49 .LP
50 See \fBdgit(7)\fP for detailed information about the data
51 model,
52 common problems likely to arise with certain kinds of package,
53 etc.
55 .TP
56 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
57 Consults the archive and dgit-repos to construct the git view of
58 history for
59 .I package
60 in
61 .I suite
62 .RB ( sid
63 by default)
64 in a new directory (named
65 .BI ./ package
66 by default);
67 also, downloads any necessary orig tarballs.
69 The suite's git tip is
70 left on the local branch
71 .BI dgit/ suite
72 ready for work, and on the corresponding dgit remote tracking branch.
73 The
74 .B origin
75 remote will be set up to point to the package's dgit-repos tree
76 for the distro to which
77 .I suite
78 belongs.
80 .I suite
81 may be a combination of several underlying suites in the form
82 .IR mainsuite \fB,\fR subsuite ...;
83 see COMBINED SUITES in dgit(7).
85 For your convenience, the
86 .B vcs-git
87 remote will be set up from the package's Vcs-Git field, if there is
88 one - but note that in the general case the history found there may be
89 different to or even disjoint from dgit's view.
90 .TP
91 \fBdgit fetch\fR [\fIsuite\fP]
92 Consults the archive and git-repos to update the git view of
93 history for a specific suite (and downloads any necessary orig
94 tarballs), and updates the remote tracking branch
95 .BR remotes/dgit/dgit/ \fIsuite\fR.
96 If the current branch is
97 .BI dgit/ suite
98 then dgit fetch defaults to
99 .IR suite ;
100 otherwise it parses debian/changelog and uses the suite specified
101 there.
102 suite may be a combined suite, as for clone.
103 .TP
104 \fBdgit pull\fR [\fIsuite\fP]
105 Does dgit fetch, and then merges the new head of the remote tracking
106 branch
107 .BI remotes/dgit/dgit/ suite
108 into the current branch.
109 .TP
110 \fBdgit build\fR ...
111 Runs
112 .B dpkg-buildpackage
113 with some suitable options.  Options and arguments after build
114 will be passed on to dpkg-buildpackage.  It is not necessary to use
115 dgit build when using dgit; it is OK to use any approach which ensures
116 that the generated source package corresponds to the relevant git
117 commit.
119 Tagging, signing and actually uploading should be left to dgit push.
120 .TP
121 \fBdgit build-source\fR ...
122 Builds the source package, and a changes file for a prospective
123 source-only upload, using
124 .BR dpkg-source .
125 The output is left in
126 .IR package \fB_\fR version \fB.dsc\fR
127 and
128 .IR package \fB_\fR version \fB_source.changes\fR.
130 Tagging, signing and actually uploading should be left to dgit push.
131 .TP
132 .B dgit clean
133 Cleans the current working tree (according to the --clean= option in
134 force).
135 .TP
136 .B dgit help
137 Print a usage summary.
138 .TP
139 \fBdgit sbuild\fR ...
140 Constructs the source package, uses
141 .B  sbuild
142 to do a binary build, and uses mergechanges to merge the source and
143 binary changes files.  Options and arguments after sbuild will be
144 passed on to sbuild.
145 The output is left in
146 .IR package \fB_\fR version \fB_multi.changes\fR.
147 .IP
148 Note that by default
149 sbuild does not build arch-independent packages.
150 You probably want to pass -A, to request those.
151 .IP
152 Tagging, signing and actually uploading should be left to dgit push.
153 .TP
154 \fBdgit gbp-build\fR ...
155 Runs
156 .B git-buildpackage
157 with some suitable options.  Options and arguments after gbp-build
158 will be passed on to git-buildpackage.
160 By default this uses \-\-quilt=gbp, so HEAD should be a
161 git-buildpackage style branch, not a patches-applied branch.
163 Tagging, signing and actually uploading should be left to dgit push.
164 .TP
165 \fBdgit push\fR [\fIsuite\fP]
166 Does an `upload', pushing the current HEAD to the archive (as a source
167 package) and to dgit-repos (as git commits).  The package must already
168 have been built ready for upload, with the .dsc and .changes
169 left in the parent directory.  It is normally best to do the build
170 with dgit too (eg with dgit sbuild): some existing build tools pass
171 unhelpful options to dpkg-source et al by default, which can result in
172 the built source package not being identical to the git tree.
174 In more detail: dgit push checks that the current HEAD corresponds to
175 the .dsc.  It then pushes the HEAD to the suite's dgit-repos branch,
176 adjusts the .changes to include any .origs which the archive lacks
177 and exclude .origs which the archive has
178 (so -sa and -sd are not needed when building for dgit push),
179 makes a signed git tag, edits the .dsc to contain the dgit metadata
180 field, runs debsign to sign the upload (.dsc and .changes), pushes the
181 signed tag, and finally uses dput to upload the .changes to the
182 archive.
184 dgit push always uses the package, suite and version specified in the
185 debian/changelog and the .dsc, which must agree.  If the command line
186 specifies a suite then that must match too.
187 .TP
188 \fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
189 Pushes the contents of the specified directory on a remote machine.
190 This is like running dgit push on build-host with build-dir as the
191 current directory; however, signing operations are done on the
192 invoking host.  This allows you to do a push when the system which has
193 the source code and the build outputs has no access to the key:
195 .TS
196 l l.
197 1.      Clone on build host (dgit clone)
198 2.      Edit code on build host (edit, git commit)
199 3.      Build package on build host (dgit build)
200 4.      Test package on build host or elsewhere (dpkg -i, test)
201 5.      Upload by invoking dgit rpush on host with your GPG key.
202 .TE
204 However, the build-host must be able to ssh to the dgit repos.  If
205 this is not already the case, you must organise it separately, for
206 example by the use of ssh agent forwarding.
208 The remaining arguments are treated just as dgit push would handle
209 them.
211 build-host and build\-dir can be passed as separate
212 arguments; this is assumed to be the case if the first argument
213 contains no : (except perhaps one in [ ], to support IPv6 address
214 literals).
216 You will need similar enough versions of dgit on the build-host and
217 the invocation host.  The build-host needs gnupg installed, with your
218 public key in its keyring (but not your private key, obviously).
219 .TP
220 .B dgit setup-new-tree
221 Configure the current working tree the way that dgit clone would have
222 set it up.  Like running
223 .BR "dgit setup-useremail" ,
224 .B setup-mergechangelogs
225 and
226 .B setup-gitattributes
227 (but only does each thing if dgit is configured to do it automatically).
228 You can use these in any git repository, not just ones used with
229 the other dgit operations.
230 .TP
231 .B dgit setup-useremail
232 Set the working tree's and from the
233 distro-specific dgit configuration
234 .RB ( dgit-distro. \fIdistro\fR .user-name " and " .user-email ),
236 .TP
237 .B dgit setup-mergechangelogs
238 Configures a git merge helper for the file
239 .B debian/changelog
240 which uses
241 .BR dpkg-mergechangelogs .
242 .TP
243 .B dgit setup-gitattributes
244 Set up the working tree's
245 .B .git/info/attributes
246 to disable all transforming attributes for all files.
247 This is done by defining a macro attribute
248 .B dgit-defuse-attrs
249 and applying it to
250 .BR * .
251 For why, see
253 in
254 .BR dgit(7) .
256 (If there is already a macro attribute line
257 .B [attr]dgit-defuse-attrs
258 in .git/info/attributes
259 (whatever its effects),
260 this operation does nothing further.
261 This fact can be used to defeat or partially defeat
262 dgit setup-gitattributes
263 and hence
264 dgit setup-new-tree.)
265 .TP
266 .B dgit quilt-fixup
267 `3.0 (quilt)' format source packages need changes representing not
268 only in-tree but also as patches in debian/patches.  dgit quilt-fixup
269 checks whether this has been done; if not, dgit will make appropriate
270 patches in debian/patches and also commit the resulting changes to
271 git.
273 This is normally done automatically by dgit build and dgit push.
275 dgit will try to turn each relevant commit in your git history into a
276 new quilt patch.  dgit cannot convert nontrivial merges, or certain
277 other kinds of more exotic history.  If dgit can't find a suitable
278 linearisation of your history, by default it will fail, but you can
279 ask it to generate a single squashed patch instead.
280 .TP
281 \fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch
282 Import a Debian-format source package,
283 specified by its .dsc,
284 into git,
285 the way dgit fetch would do.
287 This does about half the work of dgit fetch:
288 it will convert the .dsc into a new, orphan git branch.
289 Since dgit has no access to a corresponding source package archive
290 or knowledge of the history
291 it does not consider whether this version is newer
292 than any previous import
293 or corresponding git branches;
294 and it therefore does not
295 make a pseudomerge to bind the import
296 into any existing git history.
298 Because a .dsc can contain a Dgit field naming a git commit
299 (which you might not have),
300 and specifying where to find that commit
301 (and any history rewrite table),
302 import-dsc might need online access.
303 If this is a problem
304 (or dgit's efforts to find the commit fail),
305 consider --no-chase-dsc-distro
306 or --force-import-dsc-with-dgit-field.
308 There is only only sub-option:
310 .B --require-valid-signature
311 causes dgit to insist that the signature on the .dsc is valid
312 (using the same criteria as dpkg-source -x).
313 Otherwise, dgit tries to verify the signature but
314 the outcome is reported only as messages to stderr.
316 If
317 .I branch
318 is prefixed with
319 .B +
320 then if it already exists, it will be simply ovewritten,
321 no matter its existing contents.
322 If
323 .I branch
324 is prefixed with
325 .B ..
326 then if it already exists
327 and dgit actually imports the dsc
328 (rather than simply reading the git commit out of the Dgit field),
329 dgit will make a pseudomerge
330 so that the result is necessarily fast forward
331 from the existing branch.
332 Otherwise, if branch already exists,
333 dgit will stop with an error message.
335 If
336 .I branch
337 does not start with refs/, refs/heads/ is prepended.
338 .TP
339 .B dgit version
340 Prints version information and exits.
341 .TP
342 .BI "dgit clone-dgit-repos-server" " destdir"
343 Tries to fetch a copy of the source code for the dgit-repos-server,
344 as actually being used on the dgit git server, as a git tree.
345 .TP
346 .BI "dgit print-dgit-repos-server-source-url"
347 Prints the url used by dgit clone-dgit-repos-server.
348 This is hopefully suitable for use as a git remote url.
349 It may not be useable in a browser.
350 .TP
351 .BI "dgit print-dpkg-source-ignores"
352 Prints the -i and -I arguments which must be passed to dpkg-souce
353 to cause it to exclude exactly the .git diredcory
354 and nothing else.
355 The separate arguments are unquoted, separated by spaces,
356 and do not contain spaces.
358 .TP
359 .BR --dry-run " | " -n
360 Go through the motions, fetching all information needed, but do not
361 actually update the output(s).  For push, dgit does
362 the required checks and leaves the new .dsc in a temporary file,
363 but does not sign, tag, push or upload.
364 .TP
365 .BR --damp-run " | " -L
366 Go through many more of the motions: do everything that doesn't
367 involve either signing things, or making changes on the public
368 servers.
369 .TP
370 .BI -k keyid
371 Use
372 .I keyid
373 for signing the tag and the upload.  The default comes from the
374 distro's
375 .B keyid
376 config setting (see CONFIGURATION, below), or failing that, the
377 uploader trailer line in debian/changelog.
378 .TP
379 .BR --no-sign
380 does not sign tags or uploads (meaningful only with push).
381 .TP
382 .TP
383 .BI -p package
384 Specifies that we should process source package
385 .I package
386 rather than looking in debian/control or debian/changelog.
387 Valid with dgit fetch and dgit pull, only.
388 .TP
389 .BR --clean=git " | " -wg
390 Use
391 .BR "git clean -xdf"
392 to clean the working tree,
393 rather than running the package's rules clean target.
395 This will delete all files which are not tracked by git.
396 (Including any files you forgot to git add.)
398 .BI --clean= ...
399 options other than dpkg-source
400 are useful when the package's clean target is troublesome, or
401 to avoid needing the build-dependencies.
402 .TP
403 .BR --clean=git-ff " | " -wgf
404 Use
405 .BR "git clean -xdff"
406 to clean the working tree.
407 Like
408 git clean -xdf
409 but it also removes any subdirectories containing different git
410 trees (which only unusual packages are likely to create).
411 .TP
412 .BR --clean=check " | " -wc
413 Merely check that the tree is clean (does not contain uncommitted
414 files).
415 Avoids running rules clean,
416 and can avoid needing the build-dependencies.
417 .TP
418 .BR --clean=none " | " -wn
419 Do not clean the tree, nor check that it is clean.
420 Avoids running rules clean,
421 and can avoid needing the build-dependencies.
422 If there are
423 files which are not in git, or if the build creates such files, a
424 subsequent dgit push will fail.
425 .TP
426 .BR --clean=dpkg-source " | " -wd
427 Use dpkg-buildpackage to do the clean, so that the source package
428 is cleaned by dpkg-source running the package's clean target.
429 This is the default.
430 Requires the package's build dependencies.
431 .TP
432 .BR --clean=dpkg-source-d " | " -wdd
433 Use
434 .B dpkg-buildpackage -d
435 to do the clean,
436 so that the source package
437 is cleaned by dpkg-source running the package's clean target.
438 The build-dependencies are not checked (due to
439 .BR -d ),
440 which violates policy, but may work in practice.
441 .TP
442 .BR -N " | " --new
443 The package is or may be new in this suite.  Without this, dgit will
444 refuse to push.  It may (for Debian, will) be unable to access the git
445 history for any packages which have been newly pushed and have not yet
446 been published.
447 .TP
448 .BR --ignore-dirty
449 Do not complain if the working tree does not match your git HEAD.
450 This can be useful with build, if you plan to commit later.  (dgit
451 push will still ensure that the .dsc you upload and the git tree
452 you push are identical, so this option won't make broken pushes.)
453 .TP
454 .BR --overwrite [=\fIprevious-version\fR]
455 Declare that even though your git branch is not a descendant
456 of the version in the archive
457 according to the revision history,
458 it really does contain
459 all the (wanted) changes from that version.
461 This option is useful if you are the maintainer, and you have
462 incorporated NMU changes into your own git workflow in a way that
463 doesn't make your branch a fast forward from the NMU.
465 .I previous-version
466 ought to be the version currently in the archive.  If
467 .I previous-version
468 is not
469 specified, dgit will check that the version in the archive is
470 mentioned in your debian/changelog.
471 (This will avoid losing
472 changes unless someone committed to git a finalised changelog
473 entry, and then made later changes to that version.)
475 dgit push --overwrite
476 will make a
477 pseudo-merge (that is, something that looks like the result
478 of git merge -s ours) to stitch the archive's version into your own
479 git history, so that your push is a fast forward from the archive.
481 (In quilt mode
482 .BR gbp ", " dpm " or " unpatched ,
483 implying a split between the dgit view and the
484 maintainer view, the pseudo-merge will appear only in the dgit view.)
485 .TP
486 .BR --delayed =\fIdays\fR
487 Upload to a DELAYED queue.
490 If the maintainer responds by cancelling
491 your upload from the queue,
492 and does not make an upload of their own,
493 this will not rewind the git branch on the dgit git server.
494 Other dgit users will then see your push
495 (with a warning message from dgit)
496 even though the maintainer wanted to abolish it.
497 Such users might unwittingly reintroduce your changes.
499 If this situation arises,
500 someone should make a suitable dgit push
501 to update the contents of dgit-repos
502 to a version without the controversial changes.
503 .TP
504 .BR --no-chase-dsc-distro
505 Tells dgit not to look online
506 for additional git repositories
507 containing information about a particular .dsc being imported.
508 Chasing is the default.
510 For most operations
511 (such as fetch and pull),
512 disabling chasing
513 means dgit will access only the git server
514 for the distro you are directly working with,
515 even if the .dsc was copied verbatim from another distro.
516 For import-dsc,
517 disabling chasing
518 means dgit will work completely offline.
520 Disabling chasing can be hazardous:
521 if the .dsc names a git commit which has been rewritten
522 by those in charge of the distro,
523 this option may prevent that rewrite from being effective.
524 Also,
525 it can mean that
526 dgit fails to find necessary git commits.
527 .TP
528 .BR --dgit-view-save= \fIbranch\fR|\fIref\fR
529 Specifies that when a split view quilt mode is in operation,
530 and dgit calculates
531 (or looks up in its cache)
532 a dgit view corresponding to your HEAD,
533 the dgit view will be left in
534 .IR ref .
535 The specified ref is unconditionally overwritten,
536 so don't specify a branch you want to keep.
538 This option is effective only with the following operations:
539 quilt-fixup; push; all builds.
540 And it is only effective with
541 --[quilt=]gbp,
542 --[quilt=]dpm,
543 --quilt=unpatched.
545 If ref does not start with refs/
546 it is taken to to be a branch -
547 i.e. refs/heads/ is prepended.
548 .TP
549 .BI --deliberately- something
550 Declare that you are deliberately doing
551 .IR something .
552 This can be used to override safety catches, including safety catches
553 which relate to distro-specific policies.
554 The use of --deliberately is declared and published in the signed tags
555 generated for you by dgit,
556 so that the archive software can give effect to your intent,
557 and
558 for the benefit humans looking at the history.
559 The meanings of
560 .IR something s
561 understood in the context of Debian are discussed below:
562 .TP
563 .BR --deliberately-not-fast-forward
564 Declare that you are deliberately rewinding history.  When pushing to
565 Debian, use this when you are making a renewed upload of an entirely
566 new source package whose previous version was not accepted for release
567 from NEW because of problems with copyright or redistributibility.
569 In split view quilt modes,
570 this also prevents the construction by dgit of a pseudomerge
571 to make the dgit view fast forwarding.
572 Normally only one of
573 --overwrite (which creates a suitable pseudomerge)
574 and
575 --deliberately-not-fast-forward
576 (which suppresses the pseudomerge and the fast forward checks)
577 should be needed;
578 --overwrite is usually better.
579 .TP
580 .BR --deliberately-include-questionable-history
581 Declare that you are deliberately including, in the git history of
582 your current push, history which contains a previously-submitted
583 version of this package which was not approved (or has not yet been
584 approved) by the ftpmasters.  When pushing to Debian, only use this
585 option after verifying that: none of the rejected-from-NEW (or
586 never-accepted) versions in the git history of your current push, were
587 rejected by ftpmaster for copyright or redistributability reasons.
588 .TP
589 .BR --deliberately-fresh-repo
590 Declare that you are deliberately rewinding history and want to
591 throw away the existing repo.  Not relevant when pushing to Debian,
592 as the Debian server will do this automatically when necessary.
593 .TP
594 .BR --quilt=linear
595 When fixing up source format `3.0 (quilt)' metadata, insist on
596 generating a linear patch stack: one new patch for each relevant
597 commit.
598 If such a stack cannot be generated, fail.
599 This is the default for Debian.
601 HEAD should be a series of plain commits
602 (not touching debian/patches/),
603 and pseudomerges,
604 with as ancestor a patches-applied branch.
605 .TP
606 .BR --quilt=auto
607 When fixing up source format `3.0 (quilt)' metadata, prefer to
608 generate a linear patch stack
609 (as with --quilt=auto)
610 but if that doesn't seem possible,
611 try to generate a single squashed patch for all the changes made in git
612 (as with --quilt=smash).
613 This is not a good idea for an NMU in Debian.
614 .TP
615 .BR --quilt=smash
616 When fixing up source format `3.0 (quilt)' metadata,
617 generate a single additional patch for all the changes made in git.
618 This is not a good idea for an NMU in Debian.
620 (If HEAD has any in-tree patches already, they must apply cleanly.
621 This will be the case for any trees produced by dgit fetch or clone;
622 if you do not change the upstream version
623 nor make changes in debian/patches,
624 it will remain true.)
625 .TP
626 .BR --quilt=nofix
627 Check whether source format `3.0 (quilt)' metadata would need fixing
628 up, but, if it does, fail.  You must then fix the metadata yourself
629 somehow before pushing.  (NB that dpkg-source --commit will not work
630 because the dgit git tree does not have a
631 .B .pc
632 directory.)
633 .TP
634 .BR --quilt=nocheck " | " --no-quilt-fixup
635 Do not check whether up source format `3.0 (quilt)' metadata needs
636 fixing up.  If you use this option and the metadata did in fact need
637 fixing up, dgit push will fail.
638 .TP
639 .BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied
640 Tell dgit that you are using a nearly-dgit-compatible git branch,
641 aka a
642 .BR "maintainer view" ,
643 and
644 do not want your branch changed by dgit.
646 .B --gbp
647 (short for
648 .BR --quilt=gbp )
649 is for use with git-buildpackage.
650 Your HEAD is expected to be
651 a patches-unapplied git branch, except that it might contain changes
652 to upstream .gitignore files.  This is the default for dgit gbp-build.
654 .B --dpm
655 (short for
656 .BR --quilt=dpm )
657 is for use with git-dpm.
658 Your HEAD is expected to be
659 a patches-applied git branch,
660 except that it might contain changes to upstream .gitignore files.
662 .B --quilt=unapplied
663 specifies that your HEAD is a patches-unapplied git branch (and
664 that any changes to upstream .gitignore files are represented as
665 patches in debian/patches).
667 With --quilt=gbp|dpm|unapplied,
668 dgit push (or precursors like quilt-fixup and build) will automatically
669 generate a conversion of your git branch into the right form.
670 dgit push will push the
671 dgit-compatible form (the
672 .BR "dgit view" )
673 to the dgit git server.
674 The dgit view will be visible to you
675 in the dgit remote tracking branches, but your own branch will
676 not be modified.
677 dgit push will create a tag
678 .BI debian/ version
679 for the maintainer view, and the dgit tag
680 .BI archive/debian/ version
681 for the dgit view.
682 dgit quilt-fixup will merely do some checks,
683 and cache the maintainer view.
685 .B If you have a branch like this it is essential to specify the appropriate --quilt= option!
686 This is because it is not always possible to tell: a patches-unapplied
687 git branch of a package with one patch, for example, looks very like
688 a patches-applied branch where the user has used git revert to
689 undo the patch, expecting to actually revert it.
690 However, if you fail to specify the right \-\-quilt option,
691 and you aren't too lucky, dgit will notice the problem and stop,
692 with a useful hint. 
693 .TP
694 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
695 Specifies that the suite to be operated on is part of distro
696 .IR distro .
697 This overrides the default value found from the git config option
698 .BR dgit-suite. \fIsuite\fR .distro .
699 The only effect is that other configuration variables (used
700 for accessing the archive and dgit-repos) used are
701 .BR dgit-distro. \fIdistro\fR .* .
703 If your suite is part of a distro that dgit already knows about, you
704 can use this option to make dgit work even if your dgit doesn't know
705 about the suite.  For example, specifying
706 .B -ddebian
707 will work when the suite is an unknown suite in the Debian archive.
709 To define a new distro it is necessary to define methods and URLs
710 for fetching (and, for dgit push, altering) a variety of information both
711 in the archive and in dgit-repos.
712 How to set this up is not yet documented.
713 .TP
714 .BI -C changesfile
715 Specifies the .changes file which is to be uploaded.  By default
716 dgit push looks for single .changes file in the parent directory whose
717 filename suggests it is for the right package and version.
719 If the specified
720 .I changesfile
721 pathname contains slashes, the directory part is also used as
722 the value for
723 .BR --build-products-dir ;
724 otherwise, the changes file is expected in that directory (by
725 default, in
726 .BR .. ).
727 .TP
728 .B --rm-old-changes
729 When doing a build, delete any changes files matching
730 .IB package _ version _*.changes
731 before starting.  This ensures that
732 dgit push (and dgit sbuild) will be able to unambigously
733 identify the relevant changes files from the most recent build, even
734 if there have been previous builds with different tools or options.
735 The default is not to remove, but
736 .B \-\-no-rm-old-changes
737 can be used to override a previous \-\-rm-old-changes
738 or the .rm-old-changes configuration setting.
739 .TP
740 .BI --build-products-dir= directory
741 Specifies where to find the built files to be uploaded.
742 By default, dgit looks in the parent directory
743 .RB ( .. ).
744 .TP
745 .BI --no-rm-on-error
746 Do not delete the destination directory if clone fails.
747 .TP
748 .BI --dep14tag
749 Generates a DEP-14 tag (eg
750 .BR debian/ \fIversion\fR)
751 as well as a dgit tag (eg
752 .BR archive/debian/ \fIversion\fR)
753 where possible.  This is the default.
754 .TP
755 .BI --no-dep14tag
756 Do not generate a DEP-14 tag, except in split quilt view mode.
757 (On servers where only the old tag format is supported,
758 the dgit tag will have the DEP-14 name.
759 This option does not prevent that.)
760 .TP
761 .BI --dep14tag-always
762 Insist on generating a DEP-14 tag
763 as well as a dgit tag.
764 If the server does not support that, dgit push will fail.
765 .TP
766 .BI -D
767 Prints debugging information to stderr.  Repeating the option produces
768 more output (currently, up to -DDDD is meaningfully different).
769 .TP
770 .BI -c name = value
771 Specifies a git configuration option, to be used for this run.
772 dgit itself is also controlled by git configuration options.
773 .TP
774 .RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR
775 Specifies the
776 .BI -v version
777 option to pass to dpkg-genchanges, during builds.  Changes (from
778 debian/changelog) since this version will be included in the built
779 changes file, and hence in the upload.  If this option is not
780 specified, dgit will query the archive and use the latest version
781 uploaded to the intended suite.
783 Specifying
784 .B _
785 inhibits this, so that no -v option will be passed to dpkg-genchanges
786 (and as a result, only the last stanza from debian/changelog will
787 be used for the build and upload).
788 .TP
789 .RI \fB-m\fR maintaineraddress
790 Passed to dpkg-genchanges (eventually).
791 .TP
792 .RI \fB--ch:\fR option
793 Specifies a single additional option to pass, eventually, to
794 dpkg-genchanges.
796 Options which are safe to pass include
797 .BR -C
798 (and also
799 .BR "-si -sa -sd"
800 although these should never be necessary with Debian since dgit
801 automatically calculates whether .origs need to be uploaded.)
803 For other options the caveat below applies.
804 .TP
805 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
806 Specifies a single additional option to pass to
807 .BR curl ,
808 .BR dput ,
809 .BR debsign ,
810 .BR dpkg-source ,
811 .BR dpkg-buildpackage ,
812 .BR dpkg-genchanges ,
813 .BR sbuild ,
814 .BR ssh ,
815 .BR dgit ,
816 .BR apt-get ,
817 .BR apt-cache ,
818 .BR gbp-pq ,
819 .BR gbp-build ,
820 or
821 .BR mergechanges .
822 Can be repeated as necessary.
824 Use of this ability should not normally be necessary.
825 It is provided for working around bugs,
826 or other unusual situations.
827 If you use these options,
828 you may violate dgit's assumptions
829 about the behaviour of its subprograms
830 and cause lossage.
832 For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
833 the option applies only when the program is invoked directly by dgit.
834 Usually, for passing options to dpkg-genchanges, you should use
835 .BR --ch: \fIoption\fR.
837 Specifying --git is not effective for some lower-level read-only git
838 operations performed by dgit, and also not when git is invoked by
839 another program run by dgit.
841 See notes below regarding ssh and dgit.
843 NB that --gpg:option is not supported (because debsign does not
844 have that facility).
845 But see
846 .B -k
847 and the
848 .B keyid
849 distro config setting.
850 .TP
851 .RI \fB--curl=\fR program " | \fB--dput=\fR" program  " |..."
852 Specifies alternative programs to use instead of
853 .BR curl ,
854 .BR dput ,
855 .BR debsign ,
856 .BR dpkg-source ,
857 .BR dpkg-buildpackage ,
858 .BR dpkg-genchanges ,
859 .BR sbuild ,
860 .BR gpg ,
861 .BR ssh ,
862 .BR dgit ,
863 .BR apt-get ,
864 .BR apt-cache ,
865 .BR git ,
866 .BR gbp-pq ,
867 .BR gbp-build ,
868 or
869 .BR mergechanges .
871 For
872 .BR dpkg-buildpackage ,
873 .BR dpkg-genchanges ,
874 .B mergechanges
875 and
876 .BR sbuild ,
877 this applies only when the program is invoked directly by dgit.
879 For
880 .BR dgit ,
881 specifies the command to run on the remote host when dgit
882 rpush needs to invoke a remote copy of itself.  (dgit also reinvokes
883 itself as the EDITOR for dpkg-source --commit; this is done using
884 argv[0], and is not affected by --dgit=).
886 .BR gbp-build 's
887 value
888 is used instead of gbp build or git-buildpackage.  (The default is
889 the latter unless the former exists on PATH.)
890 .BR gbp-pq 's
891 value
892 is used instead of gbp pq.
893 In both cases,
894 unusually, the specified value is split on whitespace
895 to produce a command and possibly some options and/or arguments.
897 For
898 .BR ssh ,
899 the default value is taken from the
901 or
902 .B GIT_SSH
903 environment variables, if set (see below).  And, for ssh, when accessing the
904 archive and dgit-repos, this command line setting is overridden by the
905 git config variables
906 .BI dgit-distro. distro .ssh
907 and
908 .B .dgit.default.ssh
909 (which can in turn be overridden with -c).  Also, when dgit is using
910 git to access dgit-repos, only git's idea of what ssh to use (eg,
911 .BR GIT_SSH )
912 is relevant.
913 .TP
914 .BI --existing-package= package
915 dgit push needs to canonicalise the suite name.  Sometimes, dgit
916 lacks a way to ask the archive to do this without knowing the
917 name of an existing package.  Without --new we can just use the
918 package we are trying to push.  But with --new that will not work, so
919 we guess
920 .B dpkg
921 or use the value of this option.  This option is not needed with the
922 default mechanisms for accessing the archive.
923 .TP
924 .BR -h | --help
925 Print a usage summary.
926 .TP
927 .BI --initiator-tempdir= directory
928 dgit rpush uses a temporary directory on the invoking (signing) host.
929 This option causes dgit to use
930 .I directory
931 instead.  Furthermore, the specified directory will be emptied,
932 removed and recreated before dgit starts, rather than removed
933 after dgit finishes.  The directory specified must be an absolute
934 pathname.
935 .TP
936 .BI --force- something
937 Instructs dgit to try to proceed despite detecting
938 what it thinks is going to be a fatal problem.
939 .B This is probably not going to work.
940 These options are provided as an escape hatch,
941 in case dgit is confused.
942 (They might also be useful for testing error cases.)
943 .TP
944 .B --force-import-dsc-with-dgit-field
945 Tell dgit import-dsc to treat a .dsc with a Dgit field
946 like one without it.
947 The result is a fresh import,
948 discarding the git history
949 that the person who pushed that .dsc was working with.
950 .TP
951 .B --force-unrepresentable
952 Carry on even if
953 dgit thinks that your git tree contains changes
954 (relative to your .orig tarballs)
955 which dpkg-source is not able to represent.
956 Your build or push will probably fail later.
957 .TP
958 .B --force-changes-origs-exactly
959 Use the set of .origs specified in your .changes, exactly,
960 without regard to what is in the archive already.
961 The archive may well reject your upload.
962 .TP
963 .B --force-unsupported-source-format
964 Carry on despite dgit not understanding your source package format.
965 dgit will probably mishandle it.
966 .TP
967 .B --force-dsc-changes-mismatch
968 Do not check whether .dsc and .changes match.
969 The archive will probably reject your upload.
970 .TP
971 .BR --force-import-gitapply-absurd " | " --force-import-gitapply-no-absurd
972 Force on or off the use of the absurd git-apply emulation
973 when running gbp pq import
974 when importing a package from a .dsc.
975 See Debian bug #841867.
977 dgit can be configured via the git config system.
978 You may set keys with git-config (either in system-global or per-tree
979 configuration), or provide
980 .BI -c key = value
981 on the dgit command line.
982 .LP
983 Settings likely to be useful for an end user include:
984 .TP
985 .BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR"
986 Specifies the distro for a suite.  dgit keys off the suite name (which
987 appears in changelogs etc.), and uses that to determine the distro
988 which is involved.  The config used is thereafter that for the distro.
990 .I suite
991 may be a glob pattern.
992 .TP
993 .BI dgit.default.distro " distro"
994 The default distro for an unknown suite.
995 .TP
996 .BI dgit.default.default-suite " suite"
997 The default suite (eg for clone).
998 .TP
999 .BR dgit.default. *
1000 for each
1001 .BR dgit-distro. \fIdistro\fR . *,
1002 the default value used if there is no distro-specific setting.
1003 .TP
1004 .BR dgit-distro. \fIdistro\fR .clean-mode
1005 One of the values for the command line --clean= option; used if
1006 --clean is not specified.
1007 .TP
1008 .BR dgit-distro. \fIdistro\fR .quilt-mode
1009 One of the values for the command line --quilt= option; used if
1010 --quilt is not specified.
1011 .TP
1012 .BR dgit-distro. \fIdistro\fR .rm-old-changes
1013 Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes
1014 is specified.  The default is not to remove.
1015 .TP
1016 .BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
1017 Whether you have push access to the distro.
1018 For Debian, it is OK to use auto, which uses readonly mode if you are
1019 not pushing right now;
1020 but, setting this to false will avoid relying on the mirror of the dgit
1021 git repository server.
1022 .TP
1023 .BI dgit-distro. distro .keyid
1024 See also
1025 .BR -k .
1026 .TP
1027 .BI dgit-distro. distro .mirror " url"
1028 .TP
1029 .BI dgit-distro. distro .username
1030 Not relevant for Debian.
1031 .TP
1032 .BI dgit-distro. distro .upload-host
1033 Might be useful if you have an intermediate queue server.
1034 .TP
1035 .BI dgit-distro. distro .user-name " " dgit-distro. distro .user-email
1036 Values to configure for and in new git trees.  If
1037 not specified, the DEBFULLNAME and DEBEMAIL environment variables are
1038 used, respectively.  Only used if .setup-usermail is not disabled.
1039 .TP
1040 .BI dgit-distro. distro .setup-useremail
1041 Whether to set and in new git trees.
1042 True by default.  Ignored for dgit setup-setup-useremail, which does it anyway.
1043 .TP
1044 .BI dgit-distro. distro .setup-mergechangelogs
1045 Whether to setup a merge driver which uses dpkg-mergechangelogs for
1046 debian/changelog.  True by default.  Ignored for dgit
1047 setup-mergechangelogs, which does it anyway.
1048 .TP
1049 .BI dgit-distro. distro .setup-gitattributes
1050 Whether to configure .git/info/attributes
1051 to suppress checkin/checkout file content transformations
1052 in new git trees.
1053 True by default.  Ignored for dgit setup-gitattributes, which does it anyway.
1054 .TP
1055 .BI dgit-distro. distro .cmd- cmd
1056 Program to use instead of
1057 .IR cmd .
1058 Works like
1059 .BR -- \fIcmd\fR = "... ."
1060 .TP
1061 .BI dgit-distro. distro .opts- cmd
1062 Extra options to pass to
1063 .IR cmd .
1064 Works like
1065 .BR -- \fIcmd\fR : "... ."
1066 To pass several options, configure multiple values in git config
1067 (with git config --add).  The options for
1068 .BI dgit.default.opts- cmd
1069 .BI dgit-distro. distro /push.opts- cmd
1070 and are all used, followed by options from dgit's command line.
1072 There are many other settings which specify how a particular distro's
1073 services (archive and git) are provided.  These should not normally be
1074 adjusted, but are documented for the benefit of distros who wish to
1075 adopt dgit.
1076 .TP
1077 .BI dgit-distro. distro .nominal-distro
1078 Shown in git tags, Dgit fields, and so on.
1079 .TP
1080 .BI dgit-distro. distro .alias-canon
1081 Used for all access configuration lookup.
1082 .TP
1083 .BR dgit-distro. \fIdistro\fR /push. *
1084 If set, overrides corresponding non \fB/push\fR config when
1085 .BR readonly=false ,
1086 or when pushing and
1087 .BR readonly=auto .
1088 .TP
1089 .BI dgit-distro. distro .git-url
1090 .TP
1091 .BR dgit-distro. \fIdistro\fR .git-url [ -suffix ]
1092 .TP
1093 .BI dgit-distro. distro .git-proto
1094 .TP
1095 .BI dgit-distro. distro .git-path
1096 .TP
1097 .BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd
1098 .TP
1099 .BI dgit-distro. distro .git-check-suffix
1100 .TP
1101 .BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR
1102 .TP
1103 .BI dgit-distro. distro .git-create " " ssh-cmd | true
1104 .TP
1105 .BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR  | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR
1106 .TP
1107 .BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )
1108 .TP
1109 .BI dgit-distro. distro .madison-distro
1110 .TP
1111 .BI dgit-distro. distro .archive-query-default-component
1112 .TP
1113 .BI dgit-distro. distro .dgit-tag-format
1114 .TP
1115 .BR dgit-distro. \fIdistro\fR .dep14tag " " want | no | always
1116 .TP
1117 .BI dgit-distro. distro .ssh
1118 .TP
1119 .BI dgit-distro. distro .sshpsql-dbname
1120 .TP
1121 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
1122 .TP
1123 .BI dgit-distro. distro .backports-quirk
1124 .TP
1125 .BI dgit-distro. distro .rewrite-map-enable
1126 .TP
1127 .BI dgit.default.old-dsc-distro
1128 .TP
1129 .BI dgit.dsc-url-proto-ok. protocol
1130 .TP
1131 .BI dgit.dsc-url-proto-ok.bad-syntax
1132 .TP
1133 .BI dgit.default.dsc-url-proto-ok
1135 .TP
1136 .BR DGIT_SSH ", " GIT_SSH
1137 specify an alternative default program (and perhaps arguments) to use
1138 instead of ssh.  DGIT_SSH is consulted first and may contain arguments;
1139 if it contains any whitespace will be passed to the shell.  GIT_SSH
1140 specifies just the program; no arguments can be specified, so dgit
1141 interprets it the same way as git does.
1142 See
1143 also the --ssh= and --ssh: options.
1144 .TP
1146 Default git and for new trees.  See
1147 .BR "dgit setup-new-tree" .
1148 .TP
1149 .BR gpg ", " dpkg- "..., " debsign ", " git ", " curl ", " dput ", " LWP::UserAgent
1150 and other subprograms and modules used by dgit are affected by various
1151 environment variables.  Consult the documentaton for those programs
1152 for details.
1153 .SH BUGS
1154 There should be
1155 a `dgit rebase-prep' command or some such to turn a
1156 fast-forwarding branch containing pseudo-merges
1157 back into a rebasing patch stack.
1158 It might have to leave a note
1159 for a future dgit push.
1161 If the dgit push fails halfway through,
1162 it is not necessarily restartable and
1163 idempotent.
1164 It would be good to check that the proposed signing key is
1165 available before starting work.
1167 dgit's build functions, and dgit push, may make changes to
1168 your current HEAD.  Sadly this is necessary for packages in the `3.0
1169 (quilt)' source format.  This is ultimately due to what I consider
1170 design problems in quilt and dpkg-source.
1172 --dry-run does not always work properly, as not doing some of the git
1173 fetches may result in subsequent actions being different.  Doing a
1174 non-dry-run dgit fetch first will help.
1175 --damp-run is likely to work much better.
1177 \fBdgit\fP(7),
1178 \fBdgit-*\fP(7),
1179 \fBcurl\fP(1),
1180 \fBdput\fP(1),
1181 \fBdebsign\fP(1),
1182 \fBgit-config\fP(1),
1183 \fBgit-buildpackage\fP(1),
1184 \fBdpkg-buildpackage\fP(1),
1185 .br