chiark / gitweb /
changelog: start 9.14
[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] \fBpbuilder\fP|\fBcowbuilder\fP
21 [\fIdebbuildopts\fP]
22 .br
23 .B dgit
24 [\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
25 [\fIsuite\fP]
26 .br
27 .B dgit
28 [\fIdgit\-opts\fP] \fBrpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR
29 [\fIpush args...\fR]
30 .br
31 .B dgit
32 [\fIdgit\-opts\fP] \fIaction\fR ...
34 .B dgit
35 allows you to treat the Debian archive as if it were a git
36 repository.
37 Conversely,
38 it allows Debian to publish the source of its packages
39 as git branches, in a format which is directly useable
40 by ordinary people.
42 This is the command line reference.
43 Please read the tutorial(s):
44 .TS
45 lb l.
46 dgit-user(7)    for users: edit, build and share packages
47 dgit-nmu-simple(7)      for DDs: do a straightforward NMU
48 dgit-maint-native(7)    for maintainers of Debian-native packages
49 dgit-maint-debrebase(7) for maintainers: a pure-git rebasish workflow
50 dgit-maint-merge(7)     for maintainers: a pure-git merging workflow
51 dgit-maint-gbp(7)       for maintainers already using git-buildpackage
52 dgit-sponsorship(7)     for sponsors and sponsored contributors
53 dgit-downstream-dsc(7)  setting up dgit push for a new distro
54 .TE
55 .LP
56 See \fBdgit(7)\fP for detailed information about the data
57 model,
58 common problems likely to arise with certain kinds of package,
59 etc.
61 .TP
62 \fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
63 Consults the archive and dgit-repos to construct the git view of
64 history for
65 .I package
66 in
67 .I suite
68 .RB ( sid
69 by default)
70 in a new directory (named
71 .BI ./ package
72 by default);
73 also, downloads any necessary orig tarballs.
75 The suite's git tip is
76 left on the local branch
77 .BI dgit/ suite
78 ready for work, and on the corresponding dgit remote tracking branch.
79 The
80 .B origin
81 remote will be set up to point to the package's dgit-repos tree
82 for the distro to which
83 .I suite
84 belongs.
86 .I suite
87 may be a combination of several underlying suites in the form
88 .IR mainsuite \fB,\fR subsuite ...;
89 see COMBINED SUITES in dgit(7).
91 For your convenience, the
92 .B vcs-git
93 remote will be set up from the package's Vcs-Git field, if there is
94 one - but note that in the general case the history found there may be
95 different to or even disjoint from dgit's view.
96 (See also dgit update-vcs-git.)
97 .TP
98 \fBdgit fetch\fR [\fIsuite\fP]
99 Consults the archive and git-repos to update the git view of
100 history for a specific suite (and downloads any necessary orig
101 tarballs), and updates the remote tracking branch
102 .BR remotes/dgit/dgit/ \fIsuite\fR.
103 If the current branch is
104 .BI dgit/ suite
105 then dgit fetch defaults to
106 .IR suite ;
107 otherwise it parses debian/changelog and uses the suite specified
108 there.
109 suite may be a combined suite, as for clone.
110 .TP
111 \fBdgit pull\fR [\fIsuite\fP]
112 Does dgit fetch, and then merges the new head of the remote tracking
113 branch
114 .BI remotes/dgit/dgit/ suite
115 into the current branch.
116 .TP
117 \fBdgit checkout\fR \fIsuite\fR
118 Checks out the local branch
119 .BR dgit/ \fIsuite\fR.
121 If the branch does not exist,
122 dgit checkout creates it,
123 and sets it up the same way as dgit clone would.
124 In that case, if
125 the archive remote tracking branch does not exist,
126 dgit checkout will do a dgit fetch first.
128 NB: dgit checkout will only do a fetch if it has to.
129 If you already have the suite branch,
130 and want to merge your branch with updates from the archive,
131 use dgit pull.
133 dgit checkout will normally need to access the archive server,
134 to canonicalise the provided suite name.
135 The exception is if you specify the canonical name,
136 and the branch (or tracking branch) already exists.
137 .TP
138 \fBdgit build\fR ...
139 Runs
140 .B dpkg-buildpackage
141 with some suitable options.  Options and arguments after build
142 will be passed on to dpkg-buildpackage.  It is not necessary to use
143 dgit build when using dgit; it is OK to use any approach which ensures
144 that the generated source package corresponds to the relevant git
145 commit.
147 Tagging, signing and actually uploading should be left to dgit push.
149 dgit's build operations access the network,
150 to get the \-v option right.
151 See \-v, below.
152 .TP
153 \fBdgit build-source\fR ...
154 Builds the source package, and a changes file for a prospective
155 source-only upload, using
156 .BR dpkg-source .
157 The output is left in
158 .IR package \fB_\fR version \fB.dsc\fR
159 and
160 .IR package \fB_\fR version \fB_source.changes\fR.
162 Tagging, signing and actually uploading should be left to dgit
163 push-source, or dgit push.
164 .TP
165 .B dgit clean
166 Cleans the current working tree (according to the \-\-clean= option in
167 force).
168 .TP
169 \fBdgit update-vcs-git\fR [\fIsuite\fP|\fB.\fR] [\fB\-\-\fR] [\fIgit fetch options\fR]
170 .TQ
171 \fBdgit update-vcs-git\fR [\fIsuite|\fP\fB.\fR] \fB\-\fR
172 Sets up, or updates the url of, the vcs-git remote, and
173 (unless \fB-\fR was specified)
174 runs git fetch on it.
176 By default, the Vcs-Git field of the .dsc from Debian sid is used,
177 as that is probably most up to date.
178 Another suite may be specified, or
179 .B .
180 to indicate that the Vcs-Git of the cwd's debian/control should
181 be used instead.
182 .TP
183 .B dgit help
184 Print a usage summary.
185 .TP
186 \fBdgit sbuild\fR ...
187 Constructs the source package, uses
188 .B  sbuild
189 to do a binary build, and uses mergechanges to merge the source and
190 binary changes files.  Options and arguments after sbuild will be
191 passed on to sbuild.
192 The output is left in
193 .IR package \fB_\fR version \fB_multi.changes\fR.
194 .IP
195 Tagging, signing and actually uploading should be left to dgit push.
196 .TP
197 \fBdgit pbuilder\fR [\fIdebbuildopts\fP]
198 Constructs the source package, uses
199 .B  pbuilder
200 to do a binary build, and uses mergechanges to merge the source and
201 binary changes files.
202 The output is left in
203 .IR package \fB_\fR version \fB_multi.changes\fR.
205 You should ensure that your dgit \-\-build-products-dir setting matches
206 your pbuilder \-\-buildresult.
208 The \fIdebbuildopts\fP are passed to pbuilder using its \-\-debbuildopts
209 option.  If you want to pass other options to pbuilder, use the
210 \fB\-\-pbuilder:\fR dgit option as described below
211 (remember that dgit options should appear between \fBdgit\fR and
212 \fBpbuilder\fR).
214 You should ensure that in your pbuilderrc you do
215 .B not
216 have the setting
218 as this may cause trouble.
219 .TP
220 \fBdgit cowbuilder\fR [\fIdebbuildopts\fP]
221 Like \fBdgit pbuilder\fR, but uses
222 .B cowbuilder
223 instead of
224 .B pbuilder.
225 .TP
226 \fBdgit gbp-build\fR ...
227 Runs
228 .B git-buildpackage
229 with some suitable options.  Options and arguments after gbp-build
230 will be passed on to git-buildpackage.
232 By default this uses \-\-quilt=gbp, so HEAD should be a
233 git-buildpackage style branch, not a patches-applied branch.
235 Tagging, signing and actually uploading should be left to dgit push.
236 .TP
237 \fBdgit push\fR [\fIsuite\fP]
238 Does an `upload', pushing the current HEAD to the archive (as a source
239 package) and to dgit-repos (as git commits).  The package must already
240 have been built ready for upload, with the .dsc and .changes
241 left in the parent directory.  It is normally best to do the build
242 with dgit too (eg with dgit sbuild): some existing build tools pass
243 unhelpful options to dpkg-source et al by default, which can result in
244 the built source package not being identical to the git tree.
246 In more detail: dgit push checks that the current HEAD corresponds to
247 the .dsc.  It then pushes the HEAD to the suite's dgit-repos branch,
248 adjusts the .changes to include any .origs which the archive lacks
249 and exclude .origs which the archive has
250 (so \-sa and \-sd are not needed when building for dgit push),
251 makes a signed git tag, edits the .dsc to contain the dgit metadata
252 field, runs debsign to sign the upload (.dsc and .changes), pushes the
253 signed tag, and finally uses dput to upload the .changes to the
254 archive.
256 dgit push always uses the package, suite and version specified in the
257 debian/changelog and the .dsc, which must agree.  If the command line
258 specifies a suite then that must match too.
260 When used on a git-debrebase branch,
261 dgit calls git-debrebase
262 to prepare the branch
263 for source package upload and push.
264 .TP
265 \fBdgit push-source\fR [\fIsuite\fP]
266 Without \fB\-C\fR, builds a source package and dgit pushes it.  Saying
267 \fBdgit push-source\fR is like saying "update the source code in the
268 archive to match my git HEAD, and let the autobuilders do the rest."
270 With \fB\-C\fR, performs a dgit push, additionally ensuring that no
271 binary packages are uploaded.
272 .TP
273 \fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
274 Pushes the contents of the specified directory on a remote machine.
275 This is like running dgit push on build-host with build-dir as the
276 current directory; however, signing operations are done on the
277 invoking host.  This allows you to do a push when the system which has
278 the source code and the build outputs has no access to the key:
280 .TS
281 l l.
282 1.      Clone on build host (dgit clone)
283 2.      Edit code on build host (edit, git commit)
284 3.      Build package on build host (dgit build)
285 4.      Test package on build host or elsewhere (dpkg \-i, test)
286 5.      Upload by invoking dgit rpush on host with your GPG key.
287 .TE
289 However, the build-host must be able to ssh to the dgit repos.  If
290 this is not already the case, you must organise it separately, for
291 example by the use of ssh agent forwarding.
293 The remaining arguments are treated just as dgit push would handle
294 them.
296 build-host and build\-dir can be passed as separate
297 arguments; this is assumed to be the case if the first argument
298 contains no : (except perhaps one in [ ], to support IPv6 address
299 literals).
301 You will need similar enough versions of dgit on the build-host and
302 the invocation host.  The build-host needs gnupg installed, with your
303 public key in its keyring (but not your private key, obviously).
304 .TP
305 .B dgit setup-new-tree
306 Configure the current working tree the way that dgit clone would have
307 set it up.  Like running
308 .BR "dgit setup-useremail" ,
309 .B setup-mergechangelogs
310 and
311 .B setup-gitattributes
312 (but only does each thing if dgit is configured to do it automatically).
313 You can use these in any git repository, not just ones used with
314 the other dgit operations.
315 Does
316 .B not
317 run
318 .B update-vcs-git
319 (as that requires Debian packaging information).
320 .TP
321 .B dgit setup-useremail
322 Set the working tree's and from the
323 distro-specific dgit configuration
324 .RB ( dgit-distro. \fIdistro\fR .user-name " and " .user-email ),
326 .TP
327 .B dgit setup-mergechangelogs
328 Configures a git merge helper for the file
329 .B debian/changelog
330 which uses
331 .BR dpkg-mergechangelogs .
332 .TP
333 .B dgit setup-gitattributes
334 Set up the working tree's
335 .B .git/info/attributes
336 to disable all transforming attributes for all files.
337 This is done by defining a macro attribute,
338 .B dgit-defuse-attrs,
339 and applying it to
340 .BR * .
341 For why, see
343 in
344 .BR dgit(7) .
345 Note that only attributes affecting the working tree are suppressed.
346 git-archive may remain exciting.
348 If there is an existing macro attribute line
349 .B [attr]dgit-defuse-attrs
350 in .git/info/attributes,
351 but it is insufficient,
352 because it was made by an earlier version of dgit
353 and git has since introduced new transforming attributes,
354 this modifies the macro to disable the newer transformations.
356 (If there is already a macro attribute line
357 .B [attr]dgit-defuse-attrs
358 in .git/info/attributes
359 which does what dgit requires
360 (whatever files it effects),
361 this operation does nothing further.
362 This fact can be used to defeat or partially defeat
363 dgit setup-gitattributes
364 and hence
365 dgit setup-new-tree.)
366 .TP
367 .B dgit quilt-fixup
368 `3.0 (quilt)' format source packages need changes representing not
369 only in-tree but also as patches in debian/patches.  dgit quilt-fixup
370 checks whether this has been done; if not, dgit will make appropriate
371 patches in debian/patches and also commit the resulting changes to
372 git.
374 This is normally done automatically by dgit build and dgit push.
376 dgit will try to turn each relevant commit in your git history into a
377 new quilt patch.  dgit cannot convert nontrivial merges, or certain
378 other kinds of more exotic history.  If dgit can't find a suitable
379 linearisation of your history, by default it will fail, but you can
380 ask it to generate a single squashed patch instead.
382 When used with a git-debrebase branch,
383 dgit will ask git-debrebase to prepare patches.
384 However,
385 dgit can make patches in some situations where git-debrebase fails,
386 so dgit quilt-fixup can be useful in its own right.
387 To always use dgit's own patch generator
388 instead of git-debrebase make-patches,
389 pass \-\-git-debrebase=true to dgit.
391 See
392 .B FORMAT 3.0 (QUILT)
393 in
394 .BR dgit(7) .
395 .TP
396 \fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch
397 Import a Debian-format source package,
398 specified by its .dsc,
399 into git,
400 the way dgit fetch would do.
402 This does about half the work of dgit fetch:
403 it will convert the .dsc into a new, orphan git branch.
404 Since dgit has no access to a corresponding source package archive
405 or knowledge of the history
406 it does not consider whether this version is newer
407 than any previous import
408 or corresponding git branches;
409 and it therefore does not
410 make a pseudomerge to bind the import
411 into any existing git history.
413 Because a .dsc can contain a Dgit field naming a git commit
414 (which you might not have),
415 and specifying where to find that commit
416 (and any history rewrite table),
417 import-dsc might need online access.
418 If this is a problem
419 (or dgit's efforts to find the commit fail),
420 consider \-\-no-chase-dsc-distro
421 or \-\-force-import-dsc-with-dgit-field.
423 There is only one sub-option:
425 .B \-\-require-valid-signature
426 causes dgit to insist that the signature on the .dsc is valid
427 (using the same criteria as dpkg-source \-x).
428 Otherwise, dgit tries to verify the signature but
429 the outcome is reported only as messages to stderr.
431 If
432 .I branch
433 is prefixed with
434 .B +
435 then if it already exists, it will be simply overwritten,
436 no matter its existing contents.
437 If
438 .I branch
439 is prefixed with
440 .B ..
441 then if it already exists
442 and dgit actually imports the dsc
443 (rather than simply reading the git commit out of the Dgit field),
444 dgit will make a pseudomerge
445 so that the result is necessarily fast forward
446 from the existing branch.
447 Otherwise, if \fIbranch\fR already exists,
448 dgit will stop with an error message.
450 If
451 .I branch
452 does not start with refs/, refs/heads/ is prepended.
453 .TP
454 .B dgit version
455 Prints version information and exits.
456 .TP
457 .BI "dgit clone-dgit-repos-server" " destdir"
458 Tries to fetch a copy of the source code for the dgit-repos-server,
459 as actually being used on the dgit git server, as a git tree.
460 .TP
461 .BI "dgit print-dgit-repos-server-source-url"
462 Prints the url used by dgit clone-dgit-repos-server.
463 This is hopefully suitable for use as a git remote url.
464 It may not be useable in a browser.
465 .TP
466 .BI "dgit print-dpkg-source-ignores"
467 Prints the \-i and \-I arguments which must be passed to dpkg-souce
468 to cause it to exclude exactly the .git directory
469 and nothing else.
470 The separate arguments are unquoted, separated by spaces,
471 and do not contain spaces.
472 .TP
473 .B dgit print-unapplied-treeish
474 Constructs a tree-ish approximating the patches-unapplied state
475 of your 3.0 (quilt) package,
476 and prints the git object name to stdout.
477 This requires appropriate .orig tarballs.
478 This tree object is identical to your .origs
479 as regards upstream files.
480 The contents of the debian subdirectory is not interesting
481 and should not be inspected;
482 except that debian/patches will be identical to your HEAD.
484 To make this operate off-line,
485 the access configuration key
486 which is used to determine the build-products-dir
487 is the uncanonicalised version of the suite name from the changelog,
488 or (of course)
491 This function is primarily provided for the benefit of git-debrebase.
493 .TP
494 .BR \-\-dry-run " | " \-n
495 Go through the motions, fetching all information needed, but do not
496 actually update the output(s).  For push, dgit does
497 the required checks and leaves the new .dsc in a temporary file,
498 but does not sign, tag, push or upload.
499 .TP
500 .BR \-\-damp-run " | " \-L
501 Go through many more of the motions: do everything that doesn't
502 involve either signing things, or making changes on the public
503 servers.
504 .TP
505 .BI \-k keyid
506 Use
507 .I keyid
508 for signing the tag and the upload.  The default comes from the
509 distro's
510 .B keyid
511 config setting (see CONFIGURATION, below), or failing that, the
512 uploader trailer line in debian/changelog.
513 .TP
514 .BR --no-sign
515 does not sign tags or uploads (meaningful only with push).
516 .TP
517 .TP
518 .BI -p package
519 Specifies that we should process source package
520 .I package
521 rather than looking in debian/control or debian/changelog.
522 Valid with dgit fetch and dgit pull, only.
523 .TP
524 .BR --clean=git " | " -wg
525 Use
526 .BR "git clean -xdf"
527 to clean the working tree,
528 rather than running the package's rules clean target.
530 This will delete all files which are not tracked by git.
531 (Including any files you forgot to git add.)
533 .BI --clean= ...
534 options other than dpkg-source
535 are useful when the package's clean target is troublesome, or
536 to avoid needing the build-dependencies.
538 dgit will only actually clean the tree if it needs to
539 (because it needs to build the source package
540 or binaries from your working tree).
541 Otherwise
542 it will just check that there are no untracked unignored files.
543 See --clean=git[-ff],always, below.
544 .TP
545 .BR --clean=git-ff " | " -wgf
546 Use
547 .BR "git clean -xdff"
548 to clean the working tree.
549 Like
550 git clean -xdf
551 but it also removes any subdirectories containing different git
552 trees (which only unusual packages are likely to create).
553 .TP
554 .BR --clean=git "[" -ff "]" ,always " | " -wga " | " -wgfa
555 Like --clean=git, but always does the clean and not just a check,
556 deleting any untracked un-ignored files.
557 .TP
558 .BR --clean=check " | " --clean=check,ignores " | " -wc " | " -wci
559 Merely check that the tree is clean (does not contain uncommitted
560 files).
561 Avoids running rules clean,
562 and can avoid needing the build-dependencies.
564 With
565 .BR ,ignores
566 or
567 .BR \-wci ,
568 untracked files covered by .gitignore are tolerated,
569 so only files which show up as
570 .B ?
571 in git status
572 (ie, ones you maybe forgot to git add)
573 are treated as a problem.
574 .TP
575 .BR \-\-clean=none " | " \-wn
576 Do not clean the tree, nor check that it is clean.
577 Avoids running rules clean,
578 and can avoid needing the build-dependencies.
579 If there are
580 files which are not in git, or if the build creates such files, a
581 subsequent dgit push will fail.
582 .TP
583 .BR --clean=dpkg-source "[" -d "] | " -wd " | " -wdd
584 Use dpkg-buildpackage to do the clean, so that the source package
585 is cleaned by dpkg-source running the package's clean target.
586 --clean=dpkg-source is the default.
588 Without the extra
589 .BR d ,
590 requires the package's build dependencies.
592 With
593 .BR ... -d
594 or
595 .BR -wdd ,
596 the build-dependencies are not checked
597 (due to passing
598 .BR -d
599 to dpkg-buildpackage),
600 which violates policy, but may work in practice.
602 The rules clean target will only be run if it is needed:
603 when dgit is going to build source or binary packages
604 from your working tree,
605 rather than from your git branch
606 (for example because of \-\-include-dirty
607 or because the binary package build uses your working tree).
609 In all cases,
610 dgit will check that there are (after rules clean, if applicable) no
611 untracked un-ignored files,
612 in case these are files you forgot to git add.
613 (Except that this check is not done
614 for a `3.0 (quilt)' package
615 when dgit has to apply patches, dirtily, to the working tree.)
616 If your package does not have a good .gitignore
617 you will probably need --clean=dpkg-source,no-check aka -wdn.
618 .TP
619 .BR --clean=dpkg-source "[" -d "]" ,no-check " | " -wdn " | " -wddn
620 Like --clean=dpkg-source, but
621 does not care about untracked un-ignored files.
622 .TP
623 .BR --clean=dpkg-source "[" -d "]" ,all-check " | " -wda " | " -wdda
624 Like --clean=dpkg-source, but
625 fails even on ignored untracked files.
626 This could perhaps be used to detect bugs in your rules clean target.
627 .TP
628 .BR -N " | " --new
629 The package is or may be new in this suite.  Without this, dgit will
630 refuse to push.
631 It may (for Debian, will) be unable to access the git
632 history for any packages which have been newly pushed and have not yet
633 been published.
634 .TP
635 .BR --include-dirty
636 Do not complain if the working tree does not match your git HEAD,
637 and when building,
638 include the changes from your working tree.
639 This can be useful with build, if you plan to commit later.  (dgit
640 push will still ensure that the .dsc you upload and the git tree
641 you push are identical, so this option won't make broken pushes.)
643 Note that this does
644 .BR not
645 prevent dgit from cleaning your tree, so if the changes in your
646 working tree are in the form of untracked files, those might still be
647 deleted, especially with --clean=git.
648 If you want to include untracked files in the build, you can
649 use --clean=none or --clean=dpkg-source[-d]
650 in addition to --include-dirty.
651 Note that this
652 combination can fail if the untracked files are under
653 \fIdebian/patches/\fR.
654 .TP
655 .BR --ignore-dirty
656 Deprecated alias for --include-dirty.
657 .TP
658 .BR --overwrite [=\fIprevious-version\fR]
659 Declare that your HEAD really does contain
660 all the (wanted) changes
661 from all versions listed in its changelog;
662 or, all (wanted) changes from
663 .IR previous-version .
664 This promise is needed when
665 your git branch is not a descendant
666 of the version in the archive
667 according to the git revision history.
669 It is safer not to specify
670 .IR previous-version ,
671 and usually it's not needed.
672 Just say
673 .BR \-\-overwrite ,
674 unless you know what you are doing.
676 This option is useful if you are the maintainer, and you have
677 incorporated NMU changes into your own git workflow in a way that
678 doesn't make your branch a fast forward from the NMU.
679 It can also be useful when there was an upload made without dgit
680 since the most recent upload made with dgit.
682 This option is also usually necessary
683 the first time a package is pushed with dgit push
684 to a particular suite.
685 See
686 .BR dgit-maint- \fI*\fR (7) .
688 If
689 .I previous-version
690 is not
691 specified, dgit will check that the version in the archive is
692 mentioned in your debian/changelog.
693 (This will avoid losing
694 changes, even with
695 .BR --overwrite ,
696 unless someone committed to git a finalised changelog
697 entry, and then made later changes to that version.)
698 If
699 .IR previous-version
700 is specified, it ought to be the version currently in the archive.
702 dgit push --overwrite
703 will, if necessary, make a
704 pseudo-merge (that is, something that looks like the result
705 of git merge -s ours) to stitch the archive's version into your own
706 git history, so that your push is a fast forward from the archive.
708 (In quilt mode
709 .BR gbp ", " dpm ", " unpatched " or " baredebian *,
710 implying a split between the dgit view and the
711 maintainer view, the pseudo-merge will appear only in the dgit view.)
712 .TP
713 .BR \-\-delayed =\fIdays\fR
714 Upload to a DELAYED queue.
717 If the maintainer responds by cancelling
718 your upload from the queue,
719 and does not make an upload of their own,
720 this will not rewind the git branch on the dgit git server.
721 Other dgit users will then see your push
722 (with a warning message from dgit)
723 even though the maintainer wanted to abolish it.
724 Such users might unwittingly reintroduce your changes.
726 If this situation arises,
727 someone should make a suitable dgit push
728 to update the contents of dgit-repos
729 to a version without the controversial changes.
730 .TP
731 .BR --no-chase-dsc-distro
732 Tells dgit not to look online
733 for additional git repositories
734 containing information about a particular .dsc being imported.
735 Chasing is the default.
737 For most operations
738 (such as fetch and pull),
739 disabling chasing
740 means dgit will access only the git server
741 for the distro you are directly working with,
742 even if the .dsc was copied verbatim from another distro.
743 For import-dsc,
744 disabling chasing
745 means dgit will work completely offline.
747 Disabling chasing can be hazardous:
748 if the .dsc names a git commit which has been rewritten
749 by those in charge of the distro,
750 this option may prevent that rewrite from being effective.
751 Also,
752 it can mean that
753 dgit fails to find necessary git commits.
754 .TP
755 .BR \-\-save-dgit-view= \fIbranch\fR|\fIref\fR
756 Specifies that when split view is in operation,
757 and dgit calculates
758 (or looks up in its cache)
759 a dgit view corresponding to your HEAD,
760 the dgit view will be left in
761 .IR ref .
762 The specified ref is unconditionally overwritten,
763 so don't specify a branch you want to keep.
765 This option is effective only with the following operations:
766 quilt-fixup; push; all builds.
767 And it is only effective when split view is actually in operation.
769 If ref does not start with refs/
770 it is taken to be a branch -
771 i.e. refs/heads/ is prepended.
773 .B \-\-dgit-view-save
774 is a deprecated alias for
775 \-\-save-dgit-view.
776 .TP
777 .BI \-\-deliberately- something
778 Declare that you are deliberately doing
779 .IR something .
780 This can be used to override safety catches, including safety catches
781 which relate to distro-specific policies.
782 The use of \-\-deliberately is declared and published in the signed tags
783 generated for you by dgit,
784 so that the archive software can give effect to your intent,
785 and
786 for the benefit of humans looking at the history.
787 The meanings of
788 .IR something s
789 understood in the context of Debian are discussed below:
790 .TP
791 .BR --deliberately-not-fast-forward
792 Declare that you are deliberately rewriting history.
793 This could be because your branch is not fast forward from the
794 dgit server history,
795 or not fast forward from a locally-synthesised dsc import.
797 When pushing to Debian,
798 use this only when you are making a renewed upload of an entirely
799 new source package whose previous version was not accepted for release
800 from NEW because of problems with copyright or redistributibility;
801 or, exceptionally, for the very first upload with dgit.
803 When split view is in operation,
804 this also prevents the construction by dgit of a pseudomerge
805 to make the dgit view fast forwarding.
806 Normally only one of
807 --overwrite (which creates a suitable pseudomerge)
808 and
809 --deliberately-not-fast-forward
810 (which suppresses the pseudomerge and the fast forward checks)
811 should be needed;
812 --overwrite is usually better.
813 .TP
814 .BR --deliberately-include-questionable-history
815 Declare that you are deliberately including, in the git history of
816 your current push, history which contains a previously-submitted
817 version of this package which was not approved (or has not yet been
818 approved) by the ftpmasters.  When pushing to Debian, only use this
819 option after verifying that: none of the rejected-from-NEW (or
820 never-accepted) versions in the git history of your current push, were
821 rejected by ftpmaster for copyright or redistributability reasons.
822 .TP
823 .BR --deliberately-fresh-repo
824 Declare that you are deliberately rewriting history and want to
825 throw away the existing repo.  Not relevant when pushing to Debian,
826 as the Debian server will do this automatically when necessary.
827 .TP
828 .BR --quilt=linear
829 When fixing up source format `3.0 (quilt)' metadata, insist on
830 generating a linear patch stack: one new patch for each relevant
831 commit.
832 If such a stack cannot be generated, fail.
833 This is the default for Debian.
835 HEAD should be a series of plain commits
836 (not touching debian/patches/),
837 and pseudomerges,
838 with as ancestor a patches-applied branch.
839 .TP
840 .BR --quilt=auto
841 When fixing up source format `3.0 (quilt)' metadata, prefer to
842 generate a linear patch stack
843 (as with --quilt=linear)
844 but if that doesn't seem possible,
845 try to generate a single squashed patch for all the changes made in git
846 (as with --quilt=smash).
847 This is not a good idea for an NMU in Debian.
848 .TP
849 .BR --quilt=smash
850 When fixing up source format `3.0 (quilt)' metadata,
851 generate a single additional patch for all the changes made in git.
852 This is not a good idea for an NMU in Debian.
854 (If HEAD has any in-tree patches already, they must apply cleanly.
855 This will be the case for any trees produced by dgit fetch or clone;
856 if you do not change the upstream version
857 nor make changes in debian/patches,
858 it will remain true.)
859 .TP
860 .BR --quilt=nofix
861 Check whether source format `3.0 (quilt)' metadata would need fixing
862 up, but, if it does, fail.  You must then fix the metadata yourself
863 somehow before pushing.  (NB that dpkg-source --commit will not work
864 because the dgit git tree does not have a
865 .B .pc
866 directory.)
867 .TP
868 .BR --quilt=nocheck " | " --no-quilt-fixup
869 Do not check whether source format `3.0 (quilt)' metadata needs
870 fixing up.  If you use this option and the metadata did in fact need
871 fixing up, dgit push will fail.
872 .TP
873 .BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied " | " -- [ quilt= ] baredebian [ +git | +tarball ]
874 Tell dgit that you are using a nearly-dgit-compatible git branch,
875 aka a
876 .BR "maintainer view" ,
877 and
878 do not want your branch changed by dgit.
880 These quilt modes are known as
881 .BR "splitting quilt modes" .
882 See --split-view, below.
884 .B --gbp
885 (short for
886 .BR --quilt=gbp )
887 is for use with git-buildpackage.
888 Your HEAD is expected to be
889 a patches-unapplied git branch, except that it might contain changes
890 to upstream .gitignore files.  This is the default for dgit gbp-build.
892 .B --dpm
893 (short for
894 .BR --quilt=dpm )
895 is for use with git-dpm.
896 Your HEAD is expected to be
897 a patches-applied git branch,
898 except that it might contain changes to upstream .gitignore files.
900 .B --quilt=unapplied
901 specifies that your HEAD is a patches-unapplied git branch (and
902 that any changes to upstream .gitignore files are represented as
903 patches in debian/patches).
905 .B --quilt=baredebian
906 (or its alias
907 .BR --quilt=baredebian+git )
908 specifies that your HEAD contains only a debian/ directory,
909 with any changes to upstream files represented as
910 patches in debian/patches.
911 The upstream source must be available in git,
912 by default, in a suitably named git tag;
913 see --upstream-commitish.
914 In this mode, dgit cannot check that
915 all edited upstream files are properly represented as patches:
916 dgit relies on
917 debian/patches being correct.
919 .B --quilt=baredebian+tarball
920 is like --quilt=baredebian,
921 but is used when there is no appropriate upstream git history.
922 To construct the dgit view,
923 dgit will import your orig tarballs' contents into git.
924 In this mode, dgit cannot check that
925 the upstream parts of your upload correspond to what you intend:
926 dgit relies on
927 the right orig tarball(s) existing, and
928 debian/patches being correct.
930 With --quilt=gbp|dpm|unapplied|baredebian*,
931 dgit push (or precursors like quilt-fixup and build) will automatically
932 generate a conversion of your git branch into the right form.
933 dgit push will push the
934 dgit-compatible form (the
935 .BR "dgit view" )
936 to the dgit git server.
937 The dgit view will be visible to you
938 in the dgit remote tracking branches, but your own branch will
939 not be modified.
940 dgit push will create a tag
941 .BI debian/ version
942 for the maintainer view, and the dgit tag
943 .BI archive/debian/ version
944 for the dgit view.
945 dgit quilt-fixup will merely do some checks,
946 and cache the maintainer view.
948 .B If you have a branch like this it is essential to specify the appropriate \-\-quilt= option!
949 This is because it is not always possible to tell: a patches-unapplied
950 git branch of a package with one patch, for example, looks very like
951 a patches-applied branch where the user has used git revert to
952 undo the patch, expecting to actually revert it.
953 However, if you fail to specify the right \-\-quilt option,
954 and you aren't too lucky, dgit will notice the problem and stop,
955 with a useful hint.
956 .TP
957 .BR \-d "\fIdistro\fR | " \-\-distro= \fIdistro\fR
958 Specifies that the suite to be operated on is part of distro
959 .IR distro .
960 This overrides the default value found from the git config option
961 .BR dgit-suite. \fIsuite\fR .distro .
962 The only effect is that other configuration variables (used
963 for accessing the archive and dgit-repos) used are
964 .BR dgit-distro. \fIdistro\fR .* .
966 If your suite is part of a distro that dgit already knows about, you
967 can use this option to make dgit work even if your dgit doesn't know
968 about the suite.  For example, specifying
969 .B \-ddebian
970 will work when the suite is an unknown suite in the Debian archive.
972 To define a new distro it is necessary to define methods and URLs
973 for fetching (and, for dgit push, altering) a variety of information both
974 in the archive and in dgit-repos.
975 How to set this up is not yet documented.
976 .TP
977 .BR \-\-split-view=auto | always | never
978 Controls whether dgit operates a split view,
979 separating your own branch (as Debian maintainer)
980 from that shown to users of dgit clone and dgit fetch.
982 When split view is in operation
983 dgit will not make or merge any commits onto your own branch.
984 Specifically, only the dgit view will contain
985 dgit's pseudomerges,
986 which bring into the git history previous uploads made with dgit push,
987 and any commits in debian/patches required
988 to make a correct `3.0 (quilt)' source package.
990 .B auto
991 is the default, and splits the view only when needed:
992 i.e., when you are working with a `3.0 (quilt)' source package
993 and a splitting quilt mode:
994 \-\-[quilt=]gbp, dpm, unpatched or baredebian*.
996 .B always
997 splits the view regardless of the source format and the quilt mode.
999 .B never
1000 will cause dgit to fail if split view is needed.
1002 When split view is in operation, the dgit view is visible
1003 in your local git clone,
1004 but only in refs specific to dgit:
1005 notably
1006 .BI remotes/dgit/dgit/ suite
1007 and
1008 .BR archive/ \fIdistro\fR / \fIversion\fR.
1010 Note that split view does not affect dgit fetch,
1011 and is not compatible with dgit pull.
1012 .TP
1013 .BI \-C changesfile
1014 Specifies the .changes file which is to be uploaded.  By default
1015 dgit push looks for a single .changes file in the parent directory whose
1016 filename suggests it is for the right package and version.
1018 If the specified
1019 .I changesfile
1020 pathname contains slashes, the directory part is also used as
1021 the value for
1022 .BR \-\-build-products-dir ;
1023 otherwise, the changes file is expected in that directory (by
1024 default, in
1025 .BR .. ).
1026 .TP
1027 .BI \-\-upstream-commitish= upstream
1028 For use with --quilt=baredebian only.
1029 Specifies the commit containing the upstream source.
1030 This commit must be identical to your .orig tarball.
1031 The default is to look for one of the git tags
1032 .IB U " v" U " upstream/" U
1033 (in that order), where U is the upstream version.
1034 .TP
1035 .B \-\-rm-old-changes
1036 When doing a build, delete any changes files matching
1037 .IB package _ version _*.changes
1038 before starting.  This ensures that
1039 dgit push (and dgit sbuild) will be able to unambiguously
1040 identify the relevant changes files from the most recent build, even
1041 if there have been previous builds with different tools or options.
1042 The default is not to remove, but
1043 .B \-\-no-rm-old-changes
1044 can be used to override a previous \-\-rm-old-changes
1045 or the .rm-old-changes configuration setting.
1047 Note that \fBdgit push-source\fR will always find the right .changes,
1048 regardless of this option.
1049 .TP
1050 .BI \-\-build-products-dir= directory
1051 Specifies where to find and create tarballs, binary packages,
1052 source packages, .changes files, and so on.
1054 By default, dgit uses the parent directory
1055 .RB ( .. ).
1057 Changing this setting may necessitate
1058 moving .orig tarballs to the new directory,
1059 so it is probably best to
1060 use the
1061 .BI
1062 configuration setting
1063 (see CONFIGURATION, below)
1064 which this command line option overrides).
1065 .TP
1066 .BI --no-rm-on-error
1067 Do not delete the destination directory if clone fails.
1068 .TP
1069 .BI --dep14tag
1070 Generates a DEP-14 tag (eg
1071 .BR debian/ \fIversion\fR)
1072 as well as a dgit tag (eg
1073 .BR archive/debian/ \fIversion\fR).
1074 This is the default.
1075 .TP
1076 .BI --no-dep14tag
1077 Do not generate a DEP-14 tag, except when split view is in operation.
1078 .TP
1079 .BI --always-dep14tag
1080 Obsolete alias for --dep14tag, retained for compatibility.
1081 .TP
1082 .BI -D
1083 Prints debugging information to stderr.  Repeating the option produces
1084 more output (currently, up to -DDDD is meaningfully different).
1085 .TP
1086 .BI -c name = value
1087 Specifies a git configuration option, to be used for this run.
1088 dgit itself is also controlled by git configuration options.
1089 .TP
1090 .RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR
1091 Specifies the
1092 .BI -v version
1093 option to pass to dpkg-genchanges, during builds.  Changes (from
1094 debian/changelog) since this version will be included in the built
1095 changes file, and hence in the upload.  If this option is not
1096 specified, dgit will query the archive and use the latest version
1097 uploaded to the intended suite.
1099 Specifying
1100 .B _
1101 inhibits this, so that no -v option will be passed to dpkg-genchanges
1102 (and as a result, only the last stanza from debian/changelog will
1103 be used for the build and upload).
1104 .TP
1105 .RI \fB-m\fR maintaineraddress
1106 Passed to dpkg-genchanges (eventually).
1107 .TP
1108 .RI \fB--ch:\fR option
1109 Specifies a single additional option to pass, eventually, to
1110 dpkg-genchanges.
1112 Options which are safe to pass include
1113 .BR -C
1114 (and also
1115 .BR "-si -sa -sd"
1116 although these should never be necessary with Debian since dgit
1117 automatically calculates whether .origs need to be uploaded.)
1119 For other options the caveat below applies.
1120 .TP
1121 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
1122 Specifies a single additional option to pass to
1123 .BR curl ,
1124 .BR dput ,
1125 .BR debsign ,
1126 .BR dpkg-source ,
1127 .BR dpkg-buildpackage ,
1128 .BR dpkg-genchanges ,
1129 .BR sbuild ,
1130 .BR pbuilder ,
1131 .BR cowbuilder ,
1132 .BR ssh ,
1133 .BR dgit ,
1134 .BR git-debrebase ,
1135 .BR apt-get ,
1136 .BR apt-cache ,
1137 .BR gbp-pq ,
1138 .BR gbp-build ,
1139 or
1140 .BR mergechanges .
1141 Can be repeated as necessary.
1143 Use of this ability should not normally be necessary.
1144 It is provided for working around bugs,
1145 or other unusual situations.
1146 If you use these options,
1147 you may violate dgit's assumptions
1148 about the behaviour of its subprograms
1149 and cause lossage.
1151 For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
1152 the option applies only when the program is invoked directly by dgit.
1153 Usually, for passing options to dpkg-genchanges, you should use
1154 .BR \-\-ch: \fIoption\fR.
1156 Specifying \-\-git is not effective for some lower-level read-only git
1157 operations performed by dgit, and also not when git is invoked by
1158 another program run by dgit.
1160 See notes below regarding ssh and dgit.
1162 NB that \-\-gpg:option is not supported (because debsign does not
1163 have that facility).
1164 But see
1165 .B \-k
1166 and the
1167 .B keyid
1168 distro config setting.
1169 .TP
1170 .RI \fB\-\-curl!:\fR option " | \fB\-\-dput!:\fR" option " |..."
1171 Specifies an option to remove from the command line for
1172 a program called by dgit, as for
1173 \fB\-\-\fR\fIprogram\fI\fB:\fR\fIoption\fR
1174 (and the same caveats apply).
1176 Any options or arguments exactly identical to
1177 .I option
1178 are removed.
1179 (It is not an error if there were none.)
1181 This can only be used to delete options
1182 which are always passed by default by dgit,
1183 or to undo a previous
1184 \fB\-\-\fR\fIprogram\fI\fB:\fR\fIoption\fR.
1185 It cannot be used to override option(s) dynamically
1186 decided on by dgit.
1187 .TP
1188 .RI \fB\-\-curl=\fR program " | \fB\-\-dput=\fR" program  " |..."
1189 Specifies alternative programs to use instead of
1190 .BR curl ,
1191 .BR dput ,
1192 .BR debsign ,
1193 .BR dpkg-source ,
1194 .BR dpkg-buildpackage ,
1195 .BR dpkg-genchanges ,
1196 .BR sbuild ,
1197 .BR pbuilder ,
1198 .BR cowbuilder ,
1199 .BR gpg ,
1200 .BR ssh ,
1201 .BR dgit ,
1202 .BR git-debrebase ,
1203 .BR apt-get ,
1204 .BR apt-cache ,
1205 .BR git ,
1206 .BR gbp-pq ,
1207 .BR gbp-build ,
1208 or
1209 .BR mergechanges .
1211 For
1212 .BR dpkg-buildpackage ,
1213 .BR dpkg-genchanges ,
1214 .B mergechanges
1215 and
1216 .BR sbuild ,
1217 this applies only when the program is invoked directly by dgit.
1219 For
1220 .BR dgit ,
1221 specifies the command to run on the remote host when dgit
1222 rpush needs to invoke a remote copy of itself.  (dgit also reinvokes
1223 itself as the EDITOR for dpkg-source \-\-commit; this is done using
1224 argv[0], and is not affected by \-\-dgit=).
1226 .BR gbp-build 's
1227 value
1228 is used instead of gbp build or git-buildpackage.  (The default is
1229 the latter unless the former exists on PATH.)
1230 .BR gbp-pq 's
1231 value
1232 is used instead of gbp pq.
1233 In both cases,
1234 unusually, the specified value is split on whitespace
1235 to produce a command and possibly some options and/or arguments.
1237 For pbuilder and cowbuilder, the defaults are
1238 .BR "sudo -E pbuilder"
1239 and
1240 .BR "sudo -E cowbuilder"
1241 respectively.
1242 Like with gbp-build and gbp pq,
1243 the specified value is split on whitespace.
1245 For
1246 .BR ssh ,
1247 the default value is taken from the
1248 .B DGIT_SSH
1249 or
1250 .B GIT_SSH
1251 environment variables, if set (see below).  And, for ssh, when accessing the
1252 archive and dgit-repos, this command line setting is overridden by the
1253 git config variables
1254 .BI dgit-distro. distro .ssh
1255 and
1256 .B .dgit.default.ssh
1257 (which can in turn be overridden with \-c).  Also, when dgit is using
1258 git to access dgit-repos, only git's idea of what ssh to use (eg,
1259 .BR GIT_SSH )
1260 is relevant.
1261 .TP
1262 .BI \-\-existing-package= package
1263 dgit push needs to canonicalise the suite name.  Sometimes, dgit
1264 lacks a way to ask the archive to do this without knowing the
1265 name of an existing package.  Without \-\-new we can just use the
1266 package we are trying to push.  But with \-\-new that will not work, so
1267 we guess
1268 .B dpkg
1269 or use the value of this option.  This option is not needed with the
1270 default mechanisms for accessing the archive.
1271 .TP
1272 .BR \-h | \-\-help
1273 Print a usage summary.
1274 .TP
1275 .BI \-\-initiator-tempdir= directory
1276 dgit rpush uses a temporary directory on the invoking (signing) host.
1277 This option causes dgit to use
1278 .I directory
1279 instead.  Furthermore, the specified directory will be emptied,
1280 removed and recreated before dgit starts, rather than removed
1281 after dgit finishes.  The directory specified must be an absolute
1282 pathname.
1283 .TP
1284 .BI \-\-force- something
1285 Instructs dgit to try to proceed despite detecting
1286 what it thinks is going to be a fatal problem.
1287 .B This is probably not going to work.
1288 These options are provided as an escape hatch,
1289 in case dgit is confused.
1290 (They might also be useful for testing error cases.)
1291 .TP
1292 .B \-\-force-import-dsc-with-dgit-field
1293 Tell dgit import-dsc to treat a .dsc with a Dgit field
1294 like one without it.
1295 The result is a fresh import,
1296 discarding the git history
1297 that the person who pushed that .dsc was working with.
1298 .TP
1299 .B \-\-force-reusing-version
1300 Carry on even though this involves reusing a version number
1301 of a previous push or upload.
1302 It is normally best to give different versions different numbers.
1303 Some servers (including, usually, the Debian server)
1304 will reject attempts to reuse or replace already-pushed versions.
1305 .TP
1306 .B \-\-force-uploading-binaries
1307 Carry on and
1308 upload binaries
1309 even though dgit thinks your distro does not permit that.
1310 .TP
1311 .B \-\-force-uploading-source-only
1312 Carry on and do a source-only upload,
1313 without any binaries,
1314 even though dgit thinks your distro does not permit that,
1315 or does not permit that in this situation.
1316 .TP
1317 .B \-\-force-unrepresentable
1318 Carry on even if
1319 dgit thinks that your git tree contains changes
1320 (relative to your .orig tarballs)
1321 which dpkg-source is not able to represent.
1322 Your build or push will probably fail later.
1323 .TP
1324 .B \-\-force-changes-origs-exactly
1325 Use the set of .origs specified in your .changes, exactly,
1326 without regard to what is in the archive already.
1327 The archive may well reject your upload.
1328 .TP
1329 .B \-\-force-unsupported-source-format
1330 Carry on despite dgit not understanding your source package format.
1331 dgit will probably mishandle it.
1332 .TP
1333 .B \-\-force-dsc-changes-mismatch
1334 Do not check whether .dsc and .changes match.
1335 The archive will probably reject your upload.
1336 .TP
1337 .BR \-\-force-import-gitapply-absurd " | " \-\-force-import-gitapply-no-absurd
1338 Force on or off the use of the absurd git-apply emulation
1339 when running gbp pq import
1340 when importing a package from a .dsc.
1341 See Debian bug #841867.
1342 .TP
1343 .BR \-\-for\-push
1344 Override the dgit-distro.distro.readonly configuration setting,
1345 to specify that we have read/write access
1346 and should use the corresponding git and achieve access approach
1347 even if the operation is a read-only one.
1349 dgit can be configured via the git config system.
1350 You may set keys with git-config (either in system-global or per-tree
1351 configuration), or provide
1352 .BI -c key = value
1353 on the dgit command line.
1354 .LP
1355 Settings likely to be useful for an end user include:
1356 .TP
1357 .BI
1358 Specifies where to find the built files to be uploaded,
1359 when --build-products-dir is not specified.  The default is
1360 the parent directory
1361 .RB ( .. ).
1362 .TP
1363 .BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR"
1364 Specifies the distro for a suite.  dgit keys off the suite name (which
1365 appears in changelogs etc.), and uses that to determine the distro
1366 which is involved.  The config used is thereafter that for the distro.
1368 .I suite
1369 may be a glob pattern.
1370 .TP
1371 .BI dgit.default.distro " distro"
1372 The default distro for an unknown suite.
1374 This is only used if no
1375 .BI /usr/share/distro-info/ somedistro .csv
1376 mentions the specified suite.
1377 .TP
1378 .BI dgit.default.default-suite " suite"
1379 The default suite (eg for clone).
1380 .TP
1381 .BR dgit.default. *
1382 for each
1383 .BR dgit-distro. \fIdistro\fR . *,
1384 the default value used if there is no distro-specific setting.
1385 .TP
1386 .BR dgit-distro. \fIdistro\fR .clean-mode
1387 One of the values for the command line \-\-clean= option; used if
1388 \-\-clean is not specified.
1389 .TP
1390 .BR dgit-distro. \fIdistro\fR .clean-mode-newer
1391 Like .clean-mode,
1392 but ignored if the value is unknown to this version of dgit.
1393 Setting both .clean-mode and .clean-mode-newer is useful
1394 to provide a single git config compatible with different dgit versions.
1395 .TP
1396 .BR dgit-distro. \fIdistro\fR .quilt-mode
1397 One of the values for the command line \-\-quilt= option; used if
1398 \-\-quilt is not specified.
1399 .TP
1400 .BR dgit-distro. \fIdistro\fR .split-view
1401 .TP
1402 .BR dgit-distro. \fIdistro\fR .rm-old-changes
1403 Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes
1404 is specified.  The default is not to remove.
1405 .TP
1406 .BR dgit-distro. \fIdistro\fR .readonly " " auto | a " | " true | t | y | 1 " | " false | f | n | 0
1407 Whether you have push access to the distro.
1408 For Debian, it is OK to use auto, which uses readonly mode if you are
1409 not pushing right now;
1410 but, setting this to false will avoid relying on the mirror of the dgit
1411 git repository server.
1412 .TP
1413 .BI dgit-distro. distro .keyid
1414 See also
1415 .BR \-k .
1416 .TP
1417 .BI dgit-distro. distro .mirror " url"
1418 .TP
1419 .BI dgit-distro. distro .username
1420 Not relevant for Debian.
1421 .TP
1422 .BI dgit-distro. distro .upload-host
1423 Might be useful if you have an intermediate queue server.
1424 .TP
1425 .BI dgit-distro. distro .user-name " " dgit-distro. distro .user-email
1426 Values to configure for and in new git trees.  If
1427 not specified, the DEBFULLNAME and DEBEMAIL environment variables are
1428 used, respectively.  Only used if .setup-usermail is not disabled.
1429 .TP
1430 .BI dgit-distro. distro .setup-useremail
1431 Whether to set and in new git trees.
1432 True by default.  Ignored for dgit setup-useremail, which does it anyway.
1433 .TP
1434 .BI dgit-distro. distro .setup-mergechangelogs
1435 Whether to set up a merge driver which uses dpkg-mergechangelogs for
1436 debian/changelog.  True by default.  Ignored for dgit
1437 setup-mergechangelogs, which does it anyway.
1438 .TP
1439 .BI dgit-distro. distro .setup-gitattributes
1440 Whether to configure .git/info/attributes
1441 to suppress checkin/checkout file content transformations
1442 in new git trees.
1443 True by default.  Ignored for dgit setup-gitattributes, which does it anyway.
1444 .TP
1445 .BI dgit-distro. distro .cmd- cmd
1446 Program to use instead of
1447 .IR cmd .
1448 Works like
1449 .BR \-\- \fIcmd\fR = "... ."
1450 .TP
1451 .BI dgit-distro. distro .opts- cmd
1452 Extra options to pass to
1453 .IR cmd .
1454 Works like
1455 .BR \-\- \fIcmd\fR : "... ."
1456 To pass several options, configure multiple values in git config
1457 (with git config \-\-add).  The options for
1458 .BI dgit.default.opts- cmd
1459 and
1460 .BI dgit-distro. distro /push.opts- cmd
1461 are all used, followed by options from dgit's command line.
1463 There are many other settings which specify how a particular distro's
1464 services (archive and git) are provided.  These should not normally be
1465 adjusted, but are documented for the benefit of distros who wish to
1466 adopt dgit.
1467 .TP
1468 .BI dgit-distro. distro .nominal-distro
1469 Shown in git tags, Dgit fields, and so on.
1470 .TP
1471 .BI dgit-distro. distro .alias-canon
1472 Used for all access configuration lookup.
1473 .TP
1474 .BR dgit-distro. \fIdistro\fR /push. *
1475 If set, overrides corresponding non \fB/push\fR config when
1476 .BR readonly=false ,
1477 or when pushing and
1478 .BR readonly=auto .
1479 .TP
1480 .BI dgit-distro. distro .git-url
1481 .TP
1482 .BR dgit-distro. \fIdistro\fR .git-url [ -suffix ]
1483 .TP
1484 .BI dgit-distro. distro .git-proto
1485 .TP
1486 .BI dgit-distro. distro .git-path
1487 .TP
1488 .BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd
1489 .TP
1490 .BI dgit-distro. distro .git-check-suffix
1491 .TP
1492 .BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR
1493 .TP
1494 .BI dgit-distro. distro .git-create " " ssh-cmd | true
1495 .TP
1496 .BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR  | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR " " | " aptget:"
1497 .TP
1498 .BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )
1499 .TP
1500 .BI dgit-distro. distro .madison-distro
1501 .TP
1502 .BI dgit-distro. distro .archive-query-default-component
1503 .TP
1504 .BI dgit-distro. distro .dgit-tag-format
1505 .TP
1506 .BR dgit-distro. \fIdistro\fR .dep14tag " " want | no [| always ]
1507 .TP
1508 .BI dgit-distro. distro .ssh
1509 .TP
1510 .BI dgit-distro. distro .sshpsql-dbname
1511 .TP
1512 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
1513 .TP
1514 .BI dgit-distro. distro .backports-quirk
1515 .TP
1516 .BI dgit-distro. distro .rewrite-map-enable
1517 .TP
1518 .BR dgit-distro. \fIdistro\fR .source-only-uploads " " ok | always | never | not-wholly-new
1519 .TP
1520 .BI dgit.default.old-dsc-distro
1521 .TP
1522 .BI dgit.dsc-url-proto-ok. protocol
1523 .TP
1524 .BI dgit.dsc-url-proto-ok.bad-syntax
1525 .TP
1526 .BI dgit.default.dsc-url-proto-ok
1527 .TP
1528 .BR dgit.vcs-git.suites " \fIsuite\fR[" ; ...]
1530 .TP
1531 .BR DGIT_SSH ", " GIT_SSH
1532 specify an alternative default program (and perhaps arguments) to use
1533 instead of ssh.  DGIT_SSH is consulted first and may contain arguments;
1534 if it contains any whitespace will be passed to the shell.  GIT_SSH
1535 specifies just the program; no arguments can be specified, so dgit
1536 interprets it the same way as git does.
1537 See
1538 also the \-\-ssh= and \-\-ssh: options.
1539 .TP
1541 Default git and for new trees.  See
1542 .BR "dgit setup-new-tree" .
1543 .TP
1544 .BR gpg ", " dpkg- "..., " debsign ", " git ", [" lib ] curl ", " dput
1545 and other subprograms and modules used by dgit are affected by various
1546 environment variables.  Consult the documentation for those programs
1547 for details.
1548 .SH BUGS
1549 There should be
1550 a `dgit rebase-prep' command or some such to turn a
1551 fast-forwarding branch containing pseudo-merges
1552 back into a rebasing patch stack.
1553 It might have to leave a note
1554 for a future dgit push.
1556 If the dgit push fails halfway through,
1557 it is not necessarily restartable and
1558 idempotent.
1559 It would be good to check that the proposed signing key is
1560 available before starting work.
1562 dgit's build functions, and dgit push, may make changes to
1563 your current HEAD.  Sadly this is necessary for packages in the `3.0
1564 (quilt)' source format.  This is ultimately due to what I consider
1565 design problems in quilt and dpkg-source.
1567 \-\-dry-run does not always work properly, as not doing some of the git
1568 fetches may result in subsequent actions being different.  Doing a
1569 non-dry-run dgit fetch first will help.
1570 \-\-damp-run is likely to work much better.
1572 \fBdgit\fP(7),
1573 \fBdgit-*\fP(7),
1574 \fBcurl\fP(1),
1575 \fBdput\fP(1),
1576 \fBdebsign\fP(1),
1577 \fBgit-config\fP(1),
1578 \fBgit-buildpackage\fP(1),
1579 \fBdpkg-buildpackage\fP(1),
1580 .br