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