2 .TH dgit 1 "" "Debian Project" "dgit"
4 dgit \- git integration with the Debian archive
8 [\fIdgit\-opts\fP] \fBclone\fP [\fIdgit\-opts\fP]
9 \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
12 [\fIdgit\-opts\fP] \fBfetch\fP|\fBpull\fP [\fIdgit\-opts\fP]
16 [\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP
20 [\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
24 [\fIdgit\-opts\fP] \fBrpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR
28 [\fIdgit\-opts\fP] \fIaction\fR ...
31 allows you to treat the Debian archive as if it were a git
34 it allows Debian to publish the source of its packages
35 as git branches, in a format which is directly useable
38 This is the command line reference.
39 Please read the tutorial(s):
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
51 See \fBdgit(7)\fP for detailed information about the data
53 common problems likely to arise with certain kinds of package,
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
65 in a new directory (named
68 also, downloads any necessary orig tarballs.
70 The suite's git tip is
71 left on the local branch
73 ready for work, and on the corresponding dgit remote tracking branch.
76 remote will be set up to point to the package's dgit-repos tree
77 for the distro to which
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
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.)
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
100 then dgit fetch defaults to
102 otherwise it parses debian/changelog and uses the suite specified
104 suite may be a combined suite, as for clone.
106 \fBdgit pull\fR [\fIsuite\fP]
107 Does dgit fetch, and then merges the new head of the remote tracking
109 .BI remotes/dgit/dgit/ suite
110 into the current branch.
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.
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,
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
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.
143 \fBdgit build-source\fR ...
144 Builds the source package, and a changes file for a prospective
145 source-only upload, using
147 The output is left in
148 .IR package \fB_\fR version \fB.dsc\fR
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.
156 Cleans the current working tree (according to the --clean= option in
159 \fBdgit update-vcs-git\fR [\fIsuite\fP|\fB.\fR] [\fB--\fR] [\fIgit fetch options\fR]
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
170 to indicate that the Vcs-Git of the cwd's debian/control should
174 Print a usage summary.
176 \fBdgit sbuild\fR ...
177 Constructs the source package, uses
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
182 The output is left in
183 .IR package \fB_\fR version \fB_multi.changes\fR.
186 sbuild does not build arch-independent packages.
187 You probably want to pass -A, to request those.
189 Tagging, signing and actually uploading should be left to dgit push.
191 \fBdgit gbp-build\fR ...
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.
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
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.
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."
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:
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.
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
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
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).
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
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.
284 (as that requires Debian packaging information).
286 .B dgit setup-useremail
287 Set the working tree's user.name and user.email from the
288 distro-specific dgit configuration
289 .RB ( dgit-distro. \fIdistro\fR .user-name " and " .user-email ),
290 or DEBFULLNAME or DEBEMAIL.
292 .B dgit setup-mergechangelogs
293 Configures a git merge helper for the file
296 .BR dpkg-mergechangelogs .
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
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
328 dgit setup-new-tree.)
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
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.
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.
355 .B FORMAT 3.0 (QUILT)
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,
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.
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.
398 then if it already exists, it will be simply ovewritten,
399 no matter its existing contents.
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.
415 does not start with refs/, refs/heads/ is prepended.
418 Prints version information and exits.
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.
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.
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
433 The separate arguments are unquoted, separated by spaces,
434 and do not contain spaces.
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.
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
451 for signing the tag and the upload. The default comes from the
454 config setting (see CONFIGURATION, below), or failing that, the
455 uploader trailer line in debian/changelog.
458 does not sign tags or uploads (meaningful only with push).
462 Specifies that we should process source package
464 rather than looking in debian/control or debian/changelog.
465 Valid with dgit fetch and dgit pull, only.
467 .BR --clean=git " | " -wg
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.)
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.
481 .BR --clean=git-ff " | " -wgf
483 .BR "git clean -xdff"
484 to clean the working tree.
487 but it also removes any subdirectories containing different git
488 trees (which only unusual packages are likely to create).
490 .BR --clean=check " | " -wc
491 Merely check that the tree is clean (does not contain uncommitted
493 Avoids running rules clean,
494 and can avoid needing the build-dependencies.
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.
501 files which are not in git, or if the build creates such files, a
502 subsequent dgit push will fail.
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.
508 Requires the package's build dependencies.
510 .BR --clean=dpkg-source-d " | " -wdd
512 .B dpkg-buildpackage -d
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
518 which violates policy, but may work in practice.
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
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.)
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.
551 .BR dgit-maint- \fI*\fR (7) .
556 specified, dgit will check that the version in the archive is
557 mentioned in your debian/changelog.
558 (This will avoid losing
561 unless someone committed to git a finalised changelog
562 entry, and then made later changes to that 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.
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.)
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.
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.
603 (such as fetch and pull),
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.
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.
618 dgit fails to find necessary git commits.
620 .BR --dgit-view-save= \fIbranch\fR|\fIref\fR
621 Specifies that when a split view quilt mode is in operation,
623 (or looks up in its cache)
624 a dgit view corresponding to your HEAD,
625 the dgit view will be left in
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
637 If ref does not start with refs/
638 it is taken to to be a branch -
639 i.e. refs/heads/ is prepended.
641 .BI --deliberately- something
642 Declare that you are deliberately doing
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,
650 for the benefit humans looking at the history.
653 understood in the context of Debian are discussed below:
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.
665 --overwrite (which creates a suitable pseudomerge)
667 --deliberately-not-fast-forward
668 (which suppresses the pseudomerge and the fast forward checks)
670 --overwrite is usually better.
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.
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.
687 When fixing up source format `3.0 (quilt)' metadata, insist on
688 generating a linear patch stack: one new patch for each relevant
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/),
696 with as ancestor a patches-applied branch.
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.
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.)
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
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.
731 .BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied
732 Tell dgit that you are using a nearly-dgit-compatible git branch,
734 .BR "maintainer view" ,
736 do not want your branch changed by dgit.
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.
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.
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
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
769 dgit push will create a tag
771 for the maintainer view, and the dgit tag
772 .BI archive/debian/ version
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,
786 .BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
787 Specifies that the suite to be operated on is part of 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
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.
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.
813 pathname contains slashes, the directory part is also used as
815 .BR --build-products-dir ;
816 otherwise, the changes file is expected in that directory (by
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.
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
841 Do not delete the destination directory if clone fails.
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.
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.)
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.
862 Prints debugging information to stderr. Repeating the option produces
863 more output (currently, up to -DDDD is meaningfully different).
866 Specifies a git configuration option, to be used for this run.
867 dgit itself is also controlled by git configuration options.
869 .RI \fB-v\fR version "|\fB_\fR | " \fB--since-version=\fR version |\fB_\fR
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.
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).
884 .RI \fB-m\fR maintaineraddress
885 Passed to dpkg-genchanges (eventually).
887 .RI \fB--ch:\fR option
888 Specifies a single additional option to pass, eventually, to
891 Options which are safe to pass include
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.
900 .RI \fB--curl:\fR option " | \fB--dput:\fR" option " |..."
901 Specifies a single additional option to pass to
906 .BR dpkg-buildpackage ,
907 .BR dpkg-genchanges ,
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
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
945 distro config setting.
947 .RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..."
948 Specifies alternative programs to use instead of
953 .BR dpkg-buildpackage ,
954 .BR dpkg-genchanges ,
969 .BR dpkg-buildpackage ,
970 .BR dpkg-genchanges ,
974 this applies only when the program is invoked directly by 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=).
985 is used instead of gbp build or git-buildpackage. (The default is
986 the latter unless the former exists on PATH.)
989 is used instead of gbp pq.
991 unusually, the specified value is split on whitespace
992 to produce a command and possibly some options and/or arguments.
996 the default value is taken from the
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
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,
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
1018 or use the value of this option. This option is not needed with the
1019 default mechanisms for accessing the archive.
1022 Print a usage summary.
1024 .BI --initiator-tempdir= directory
1025 dgit rpush uses a temporary directory on the invoking (signing) host.
1026 This option causes dgit to use
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
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.)
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.
1048 .B --force-unrepresentable
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.
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.
1060 .B --force-unsupported-source-format
1061 Carry on despite dgit not understanding your source package format.
1062 dgit will probably mishandle it.
1064 .B --force-dsc-changes-mismatch
1065 Do not check whether .dsc and .changes match.
1066 The archive will probably reject your upload.
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
1078 on the dgit command line.
1080 Settings likely to be useful for an end user include:
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.
1088 may be a glob pattern.
1090 .BI dgit.default.distro " distro"
1091 The default distro for an unknown suite.
1093 .BI dgit.default.default-suite " suite"
1094 The default suite (eg for clone).
1098 .BR dgit-distro. \fIdistro\fR . *,
1099 the default value used if there is no distro-specific setting.
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.
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.
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.
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.
1120 .BI dgit-distro. distro .keyid
1124 .BI dgit-distro. distro .mirror " url"
1126 .BI dgit-distro. distro .username
1127 Not relevant for Debian.
1129 .BI dgit-distro. distro .upload-host
1130 Might be useful if you have an intermediate queue server.
1132 .BI dgit-distro. distro .user-name " " dgit-distro. distro .user-email
1133 Values to configure for user.name and user.email 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.
1137 .BI dgit-distro. distro .setup-useremail
1138 Whether to set user.name and user.email in new git trees.
1139 True by default. Ignored for dgit setup-setup-useremail, which does it anyway.
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.
1146 .BI dgit-distro. distro .setup-gitattributes
1147 Whether to configure .git/info/attributes
1148 to suppress checkin/checkout file content transformations
1150 True by default. Ignored for dgit setup-gitattributes, which does it anyway.
1152 .BI dgit-distro. distro .cmd- cmd
1153 Program to use instead of
1156 .BR -- \fIcmd\fR = "... ."
1158 .BI dgit-distro. distro .opts- cmd
1159 Extra options to pass to
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.
1168 .SH ACCESS CONFIGURATION
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
1174 .BI dgit-distro. distro .nominal-distro
1175 Shown in git tags, Dgit fields, and so on.
1177 .BI dgit-distro. distro .alias-canon
1178 Used for all access configuration lookup.
1180 .BR dgit-distro. \fIdistro\fR /push. *
1181 If set, overrides corresponding non \fB/push\fR config when
1182 .BR readonly=false ,
1186 .BI dgit-distro. distro .git-url
1188 .BR dgit-distro. \fIdistro\fR .git-url [ -suffix ]
1190 .BI dgit-distro. distro .git-proto
1192 .BI dgit-distro. distro .git-path
1194 .BR dgit-distro. \fIdistro\fR .git-check " " true | false | url | ssh-cmd
1196 .BI dgit-distro. distro .git-check-suffix
1198 .BR dgit-distro. \fIdistro\fR .diverts.divert " " new-distro | / \fIdistro-suffix\fR
1200 .BI dgit-distro. distro .git-create " " ssh-cmd | true
1202 .BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR
1204 .BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )
1206 .BI dgit-distro. distro .madison-distro
1208 .BI dgit-distro. distro .archive-query-default-component
1210 .BI dgit-distro. distro .dgit-tag-format
1212 .BR dgit-distro. \fIdistro\fR .dep14tag " " want | no | always
1214 .BI dgit-distro. distro .ssh
1216 .BI dgit-distro. distro .sshpsql-dbname
1218 .BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
1220 .BI dgit-distro. distro .backports-quirk
1222 .BI dgit-distro. distro .rewrite-map-enable
1224 .BI dgit.default.old-dsc-distro
1226 .BI dgit.dsc-url-proto-ok. protocol
1228 .BI dgit.dsc-url-proto-ok.bad-syntax
1230 .BI dgit.default.dsc-url-proto-ok
1232 .BR dgit.vcs-git.suites " \fIsuite\fR[" ; ...]
1233 .SH ENVIRONMENT VARIABLES
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.
1242 also the --ssh= and --ssh: options.
1244 .BR DEBEMAIL ", " DEBFULLNAME
1245 Default git user.email and user.name for new trees. See
1246 .BR "dgit setup-new-tree" .
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
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
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.
1281 \fBgit-config\fP(1),
1282 \fBgit-buildpackage\fP(1),
1283 \fBdpkg-buildpackage\fP(1),
1285 https://browse.dgit.debian.org/