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