1dgit(1) dgit dgit(1)
2
6 dgit - git integration with the Debian archive
7
9 dgit [dgit-opts] clone [dgit-opts] package [suite] [./dir|/dir]
10 dgit [dgit-opts] fetch|pull [dgit-opts] [suite]
11 dgit [dgit-opts] build|sbuild|build-source [build-opts]
12 dgit [dgit-opts] pbuilder|cowbuilder [debbuildopts]
13 dgit [dgit-opts] push|push-source [dgit-opts] [suite]
14 dgit [dgit-opts] rpush build-host:build-dir [push args...]
15 dgit [dgit-opts] action ...
16
18 dgit allows you to treat the Debian archive as if it were a git reposi‐
19 tory. Conversely, it allows Debian to publish the source of its pack‐
20 ages as git branches, in a format which is directly useable by ordinary
21 people.
22 This is the command line reference. Please read the tutorial(s):
24 dgit-user(7) for users: edit, build and share packages
26 dgit-nmu-simple(7) for DDs: do a straightforward NMU
27 dgit-maint-native(7) for maintainers of Debian-native packages
28 dgit-maint-debrebase(7) for maintainers: a pure-git rebasish workflow
29 dgit-maint-merge(7) for maintainers: a pure-git merging workflow
30 dgit-maint-gbp(7) for maintainers already using git-buildpackage
31 dgit-sponsorship(7) for sponsors and sponsored contributors
32 dgit-downstream-dsc(7) setting up dgit push for a new distro
33 See dgit(7) for detailed information about the data model, common prob‐
35 lems likely to arise with certain kinds of package, etc.
36
38 dgit clone package [suite] [./dir|/dir]
39 Consults the archive and dgit-repos to construct the git view of
40 history for package in suite (sid by default) in a new directory
41 (named ./package by default); also, downloads any necessary orig
42 tarballs.
43 The suite's git tip is left on the local branch dgit/suite ready
45 for work, and on the corresponding dgit remote tracking branch.
46 The origin remote will be set up to point to the package's dgit-
47 repos tree for the distro to which suite belongs.
48 suite may be a combination of several underlying suites in the
50 form mainsuite,subsuite...; see COMBINED SUITES in dgit(7).
51 For your convenience, the vcs-git remote will be set up from the
53 package's Vcs-Git field, if there is one - but note that in the
54 general case the history found there may be different to or even
55 disjoint from dgit's view. (See also dgit update-vcs-git.)
56 dgit fetch [suite]
58 Consults the archive and git-repos to update the git view of
59 history for a specific suite (and downloads any necessary orig
60 tarballs), and updates the remote tracking branch re‐
61 motes/dgit/dgit/suite. If the current branch is dgit/suite then
62 dgit fetch defaults to suite; otherwise it parses de‐
63 bian/changelog and uses the suite specified there. suite may be
64 a combined suite, as for clone.
65 dgit pull [suite]
67 Does dgit fetch, and then merges the new head of the remote
68 tracking branch remotes/dgit/dgit/suite into the current branch.
69 dgit checkout suite
71 Checks out the local branch dgit/suite.
72 If the branch does not exist, dgit checkout creates it, and sets
74 it up the same way as dgit clone would. In that case, if the
75 archive remote tracking branch does not exist, dgit checkout
76 will do a dgit fetch first.
77 NB: dgit checkout will only do a fetch if it has to. If you al‐
79 ready have the suite branch, and want to merge your branch with
80 updates from the archive, use dgit pull.
81 dgit checkout will normally need to access the archive server,
83 to canonicalise the provided suite name. The exception is if
84 you specify the canonical name, and the branch (or tracking
85 branch) already exists.
86 dgit build ...
88 Runs dpkg-buildpackage with some suitable options. Options and
89 arguments after build will be passed on to dpkg-buildpackage.
90 It is not necessary to use dgit build when using dgit; it is OK
91 to use any approach which ensures that the generated source
92 package corresponds to the relevant git commit.
93 Tagging, signing and actually uploading should be left to dgit
95 push.
96 dgit's build operations access the network, to get the -v option
98 right. See -v, below.
99 dgit build-source ...
101 Builds the source package, and a changes file for a prospective
102 source-only upload, using dpkg-source. The output is left in
103 package_version.dsc and package_version_source.changes.
104 Tagging, signing and actually uploading should be left to dgit
106 push-source, or dgit push.
107 dgit clean
109 Cleans the current working tree (according to the --clean= op‐
110 tion in force).
111 dgit update-vcs-git [suite|.] [--] [git fetch options]
113 dgit update-vcs-git [suite|.] -
114 Sets up, or updates the url of, the vcs-git remote, and (unless
115 - was specified) runs git fetch on it.
116 By default, the Vcs-Git field of the .dsc from Debian sid is
118 used, as that is probably most up to date. Another suite may be
119 specified, or . to indicate that the Vcs-Git of the cwd's de‐
120 bian/control should be used instead.
121 dgit help
123 Print a usage summary.
124 dgit sbuild ...
126 Constructs the source package, uses sbuild to do a binary build,
127 and uses mergechanges to merge the source and binary changes
128 files. Options and arguments after sbuild will be passed on to
129 sbuild. The output is left in package_version_multi.changes.
130 Tagging, signing and actually uploading should be left to dgit
132 push.
133 dgit pbuilder [debbuildopts]
135 Constructs the source package, uses pbuilder to do a binary
136 build, and uses mergechanges to merge the source and binary
137 changes files. The output is left in package_ver‐
138 sion_multi.changes.
139 You should ensure that your dgit --build-products-dir setting
141 matches your pbuilder --buildresult.
142 The debbuildopts are passed to pbuilder using its --debbuildopts
144 option. If you want to pass other options to pbuilder, use the
145 --pbuilder: dgit option as described below (remember that dgit
146 options should appear between dgit and pbuilder).
147 You should ensure that in your pbuilderrc you do not have the
149 setting SOURCE_ONLY_CHANGES=yes as this may cause trouble.
150 dgit cowbuilder [debbuildopts]
152 Like dgit pbuilder, but uses cowbuilder instead of pbuilder.
153 dgit gbp-build ...
155 Runs git-buildpackage with some suitable options. Options and
156 arguments after gbp-build will be passed on to git-buildpackage.
157 By default this uses --quilt=gbp, so HEAD should be a git-build‐
159 package style branch, not a patches-applied branch.
160 Tagging, signing and actually uploading should be left to dgit
162 push.
163 dgit push [suite]
165 Does an `upload', pushing the current HEAD to the archive (as a
166 source package) and to dgit-repos (as git commits). The package
167 must already have been built ready for upload, with the .dsc and
168 .changes left in the parent directory. It is normally best to
169 do the build with dgit too (eg with dgit sbuild): some existing
170 build tools pass unhelpful options to dpkg-source et al by de‐
171 fault, which can result in the built source package not being
172 identical to the git tree.
173 In more detail: dgit push checks that the current HEAD corre‐
175 sponds to the .dsc. It then pushes the HEAD to the suite's
176 dgit-repos branch, adjusts the .changes to include any .origs
177 which the archive lacks and exclude .origs which the archive has
178 (so -sa and -sd are not needed when building for dgit push),
179 makes a signed git tag, edits the .dsc to contain the dgit meta‐
180 data field, runs debsign to sign the upload (.dsc and .changes),
181 pushes the signed tag, and finally uses dput to upload the
182 .changes to the archive.
183 dgit push always uses the package, suite and version specified
185 in the debian/changelog and the .dsc, which must agree. If the
186 command line specifies a suite then that must match too.
187 When used on a git-debrebase branch, dgit calls git-debrebase to
189 prepare the branch for source package upload and push.
190 dgit push-source [suite]
192 Without -C, builds a source package and dgit pushes it. Saying
193 dgit push-source is like saying "update the source code in the
194 archive to match my git HEAD, and let the autobuilders do the
195 rest."
196 With -C, performs a dgit push, additionally ensuring that no bi‐
198 nary packages are uploaded.
199 dgit rpush build-host:build-dir [push args...]
201 Pushes the contents of the specified directory on a remote ma‐
202 chine. This is like running dgit push on build-host with build-
203 dir as the current directory; however, signing operations are
204 done on the invoking host. This allows you to do a push when
205 the system which has the source code and the build outputs has
206 no access to the key:
207 1. Clone on build host (dgit clone)
210 2. Edit code on build host (edit, git commit)
211 3. Build package on build host (dgit build)
212 4. Test package on build host or elsewhere (dpkg -i, test)
213 5. Upload by invoking dgit rpush on host with your GPG key.
214 However, the build-host must be able to ssh to the dgit repos.
216 If this is not already the case, you must organise it sepa‐
217 rately, for example by the use of ssh agent forwarding.
218 The remaining arguments are treated just as dgit push would han‐
220 dle them.
221 build-host and build-dir can be passed as separate arguments;
223 this is assumed to be the case if the first argument contains no
224 : (except perhaps one in [ ], to support IPv6 address literals).
225 You will need similar enough versions of dgit on the build-host
227 and the invocation host. The build-host needs gnupg installed,
228 with your public key in its keyring (but not your private key,
229 obviously).
230 dgit setup-new-tree
232 Configure the current working tree the way that dgit clone would
233 have set it up. Like running dgit setup-useremail, setup-
234 mergechangelogs and setup-gitattributes (but only does each
235 thing if dgit is configured to do it automatically). You can
236 use these in any git repository, not just ones used with the
237 other dgit operations. Does not run update-vcs-git (as that re‐
238 quires Debian packaging information).
239 dgit setup-useremail
241 Set the working tree's user.name and user.email from the distro-
242 specific dgit configuration (dgit-distro.distro.user-name and
243 .user-email), or DEBFULLNAME or DEBEMAIL.
244 dgit setup-mergechangelogs
246 Configures a git merge helper for the file debian/changelog
247 which uses dpkg-mergechangelogs.
248 dgit setup-gitattributes
250 Set up the working tree's .git/info/attributes to disable all
251 transforming attributes for all files. This is done by defining
252 a macro attribute, dgit-defuse-attrs, and applying it to *. For
253 why, see GITATTRIBUTES in dgit(7). Note that only attributes
254 affecting the working tree are suppressed. git-archive may re‐
255 main exciting.
256 If there is an existing macro attribute line [attr]dgit-defuse-
258 attrs in .git/info/attributes, but it is insufficient, because
259 it was made by an earlier version of dgit and git has since in‐
260 troduced new transforming attributes, this modifies the macro to
261 disable the newer transformations.
262 (If there is already a macro attribute line [attr]dgit-defuse-
264 attrs in .git/info/attributes which does what dgit requires
265 (whatever files it effects), this operation does nothing fur‐
266 ther. This fact can be used to defeat or partially defeat dgit
267 setup-gitattributes and hence dgit setup-new-tree.)
268 dgit quilt-fixup
270 `3.0 (quilt)' format source packages need changes representing
271 not only in-tree but also as patches in debian/patches. dgit
272 quilt-fixup checks whether this has been done; if not, dgit will
273 make appropriate patches in debian/patches and also commit the
274 resulting changes to git.
275 This is normally done automatically by dgit build and dgit push.
277 dgit will try to turn each relevant commit in your git history
279 into a new quilt patch. dgit cannot convert nontrivial merges,
280 or certain other kinds of more exotic history. If dgit can't
281 find a suitable linearisation of your history, by default it
282 will fail, but you can ask it to generate a single squashed
283 patch instead.
284 When used with a git-debrebase branch, dgit will ask git-debre‐
286 base to prepare patches. However, dgit can make patches in some
287 situations where git-debrebase fails, so dgit quilt-fixup can be
288 useful in its own right. To always use dgit's own patch genera‐
289 tor instead of git-debrebase make-patches, pass --git-debre‐
290 base=true to dgit.
291 See FORMAT 3.0 (QUILT) in dgit(7).
293 dgit import-dsc [sub-options] ../path/to/.dsc [+|..]branch
295 Import a Debian-format source package, specified by its .dsc,
296 into git, the way dgit fetch would do.
297 This does about half the work of dgit fetch: it will convert the
299 .dsc into a new, orphan git branch. Since dgit has no access to
300 a corresponding source package archive or knowledge of the his‐
301 tory it does not consider whether this version is newer than any
302 previous import or corresponding git branches; and it therefore
303 does not make a pseudomerge to bind the import into any existing
304 git history.
305 Because a .dsc can contain a Dgit field naming a git commit
307 (which you might not have), and specifying where to find that
308 commit (and any history rewrite table), import-dsc might need
309 online access. If this is a problem (or dgit's efforts to find
310 the commit fail), consider --no-chase-dsc-distro or --force-im‐
311 port-dsc-with-dgit-field.
312 There is only one sub-option:
314 --require-valid-signature causes dgit to insist that the signa‐
316 ture on the .dsc is valid (using the same criteria as dpkg-
317 source -x). Otherwise, dgit tries to verify the signature but
318 the outcome is reported only as messages to stderr.
319 If branch is prefixed with + then if it already exists, it will
321 be simply overwritten, no matter its existing contents. If
322 branch is prefixed with .. then if it already exists and dgit
323 actually imports the dsc (rather than simply reading the git
324 commit out of the Dgit field), dgit will make a pseudomerge so
325 that the result is necessarily fast forward from the existing
326 branch. Otherwise, if branch already exists, dgit will stop
327 with an error message.
328 If branch does not start with refs/, refs/heads/ is prepended.
330 dgit version
332 Prints version information and exits.
333 dgit clone-dgit-repos-server destdir
335 Tries to fetch a copy of the source code for the dgit-repos-
336 server, as actually being used on the dgit git server, as a git
337 tree.
338 dgit print-dgit-repos-server-source-url
340 Prints the url used by dgit clone-dgit-repos-server. This is
341 hopefully suitable for use as a git remote url. It may not be
342 useable in a browser.
343 dgit print-dpkg-source-ignores
345 Prints the -i and -I arguments which must be passed to dpkg-
346 souce to cause it to exclude exactly the .git directory and
347 nothing else. The separate arguments are unquoted, separated by
348 spaces, and do not contain spaces.
349 dgit print-unapplied-treeish
351 Constructs a tree-ish approximating the patches-unapplied state
352 of your 3.0 (quilt) package, and prints the git object name to
353 stdout. This requires appropriate .orig tarballs. This tree
354 object is identical to your .origs as regards upstream files.
355 The contents of the debian subdirectory is not interesting and
356 should not be inspected; except that debian/patches will be
357 identical to your HEAD.
358 To make this operate off-line, the access configuration key
360 which is used to determine the build-products-dir is the un‐
361 canonicalised version of the suite name from the changelog, or
362 (of course) dgit.default.build-products-dir. See ACCESS CONFIG‐
363 URATION, below.
364 This function is primarily provided for the benefit of git-de‐
366 brebase.
367
369 --dry-run | -n
370 Go through the motions, fetching all information needed, but do
371 not actually update the output(s). For push, dgit does the re‐
372 quired checks and leaves the new .dsc in a temporary file, but
373 does not sign, tag, push or upload.
374 --damp-run | -L
376 Go through many more of the motions: do everything that doesn't
377 involve either signing things, or making changes on the public
378 servers.
379 -kkeyid
381 Use keyid for signing the tag and the upload. The default comes
382 from the distro's keyid config setting (see CONFIGURATION, be‐
383 low), or failing that, the uploader trailer line in de‐
384 bian/changelog.
385 --no-sign
387 does not sign tags or uploads (meaningful only with push).
388 -ppackage
391 Specifies that we should process source package package rather
392 than looking in debian/control or debian/changelog. Valid with
393 dgit fetch and dgit pull, only.
394 --clean=git | -wg
396 Use git clean -xdf to clean the working tree, rather than run‐
397 ning the package's rules clean target.
398 This will delete all files which are not tracked by git. (In‐
400 cluding any files you forgot to git add.)
401 --clean=... options other than dpkg-source are useful when the
403 package's clean target is troublesome, or to avoid needing the
404 build-dependencies.
405 dgit will only actually clean the tree if it needs to (because
407 it needs to build the source package or binaries from your work‐
408 ing tree). Otherwise it will just check that there are no un‐
409 tracked unignored files. See --clean=git[-ff],always, below.
410 --clean=git-ff | -wgf
412 Use git clean -xdff to clean the working tree. Like git clean
413 -xdf but it also removes any subdirectories containing different
414 git trees (which only unusual packages are likely to create).
415 --clean=git[-ff],always | -wga | -wgfa
417 Like --clean=git, but always does the clean and not just a
418 check, deleting any untracked un-ignored files.
419 --clean=check | --clean=check,ignores | -wc | -wci
421 Merely check that the tree is clean (does not contain uncommit‐
422 ted files). Avoids running rules clean, and can avoid needing
423 the build-dependencies.
424 With ,ignores or -wci, untracked files covered by .gitignore are
426 tolerated, so only files which show up as ? in git status (ie,
427 ones you maybe forgot to git add) are treated as a problem.
428 --clean=none | -wn
430 Do not clean the tree, nor check that it is clean. Avoids run‐
431 ning rules clean, and can avoid needing the build-dependencies.
432 If there are files which are not in git, or if the build creates
433 such files, a subsequent dgit push will fail.
434 --clean=dpkg-source[-d] | -wd | -wdd
436 Use dpkg-buildpackage to do the clean, so that the source pack‐
437 age is cleaned by dpkg-source running the package's clean tar‐
438 get. --clean=dpkg-source is the default.
439 Without the extra d, requires the package's build dependencies.
441 With ...-d or -wdd, the build-dependencies are not checked (due
443 to passing -d to dpkg-buildpackage), which violates policy, but
444 may work in practice.
445 The rules clean target will only be run if it is needed: when
447 dgit is going to build source or binary packages from your work‐
448 ing tree, rather than from your git branch (for example because
449 of --include-dirty or because the binary package build uses your
450 working tree).
451 In all cases, dgit will check that there are (after rules clean,
453 if applicable) no untracked un-ignored files, in case these are
454 files you forgot to git add. (Except that this check is not
455 done for a `3.0 (quilt)' package when dgit has to apply patches,
456 dirtily, to the working tree.) If your package does not have a
457 good .gitignore you will probably need --clean=dpkg-source,no-
458 check aka -wdn.
459 --clean=dpkg-source[-d],no-check | -wdn | -wddn
461 Like --clean=dpkg-source, but does not care about untracked un-
462 ignored files.
463 --clean=dpkg-source[-d],all-check | -wda | -wdda
465 Like --clean=dpkg-source, but fails even on ignored untracked
466 files. This could perhaps be used to detect bugs in your rules
467 clean target.
468 -N | --new
470 The package is or may be new in this suite. Without this, dgit
471 will refuse to push. It may (for Debian, will) be unable to ac‐
472 cess the git history for any packages which have been newly
473 pushed and have not yet been published.
474 --include-dirty
476 Do not complain if the working tree does not match your git
477 HEAD, and when building, include the changes from your working
478 tree. This can be useful with build, if you plan to commit
479 later. (dgit push will still ensure that the .dsc you upload
480 and the git tree you push are identical, so this option won't
481 make broken pushes.)
482 Note that this does not prevent dgit from cleaning your tree, so
484 if the changes in your working tree are in the form of untracked
485 files, those might still be deleted, especially with
486 --clean=git. If you want to include untracked files in the
487 build, you can use --clean=none or --clean=dpkg-source[-d] in
488 addition to --include-dirty. Note that this combination can
489 fail if the untracked files are under debian/patches/.
490 --ignore-dirty
492 Deprecated alias for --include-dirty.
493 --overwrite[=previous-version]
495 Declare that your HEAD really does contain all the (wanted)
496 changes from all versions listed in its changelog; or, all
497 (wanted) changes from previous-version. This promise is needed
498 when your git branch is not a descendant of the version in the
499 archive according to the git revision history.
500 It is safer not to specify previous-version, and usually it's
502 not needed. Just say --overwrite, unless you know what you are
503 doing.
504 This option is useful if you are the maintainer, and you have
506 incorporated NMU changes into your own git workflow in a way
507 that doesn't make your branch a fast forward from the NMU. It
508 can also be useful when there was an upload made without dgit
509 since the most recent upload made with dgit.
510 This option is also usually necessary the first time a package
512 is pushed with dgit push to a particular suite. See dgit-
513 maint-*[1m(7).
514 If previous-version is not specified, dgit will check that the
516 version in the archive is mentioned in your debian/changelog.
517 (This will avoid losing changes, even with --overwrite, unless
518 someone committed to git a finalised changelog entry, and then
519 made later changes to that version.) If previous-version is
520 specified, it ought to be the version currently in the archive.
521 dgit push --overwrite will, if necessary, make a pseudo-merge
523 (that is, something that looks like the result of git merge -s
524 ours) to stitch the archive's version into your own git history,
525 so that your push is a fast forward from the archive.
526 (In quilt mode gbp, dpm, unpatched or baredebian*, implying a
528 split between the dgit view and the maintainer view, the pseudo-
529 merge will appear only in the dgit view.)
530 --delayed=days
532 Upload to a DELAYED queue.
533 WARNING: If the maintainer responds by cancelling your upload
535 from the queue, and does not make an upload of their own, this
536 will not rewind the git branch on the dgit git server. Other
537 dgit users will then see your push (with a warning message from
538 dgit) even though the maintainer wanted to abolish it. Such
539 users might unwittingly reintroduce your changes.
540 If this situation arises, someone should make a suitable dgit
542 push to update the contents of dgit-repos to a version without
543 the controversial changes.
544 --no-chase-dsc-distro
546 Tells dgit not to look online for additional git repositories
547 containing information about a particular .dsc being imported.
548 Chasing is the default.
549 For most operations (such as fetch and pull), disabling chasing
551 means dgit will access only the git server for the distro you
552 are directly working with, even if the .dsc was copied verbatim
553 from another distro. For import-dsc, disabling chasing means
554 dgit will work completely offline.
555 Disabling chasing can be hazardous: if the .dsc names a git com‐
557 mit which has been rewritten by those in charge of the distro,
558 this option may prevent that rewrite from being effective.
559 Also, it can mean that dgit fails to find necessary git commits.
560 --save-dgit-view=branch|ref
562 Specifies that when split view is in operation, and dgit calcu‐
563 lates (or looks up in its cache) a dgit view corresponding to
564 your HEAD, the dgit view will be left in ref. The specified ref
565 is unconditionally overwritten, so don't specify a branch you
566 want to keep.
567 This option is effective only with the following operations:
569 quilt-fixup; push; all builds. And it is only effective when
570 split view is actually in operation.
571 If ref does not start with refs/ it is taken to be a branch -
573 i.e. refs/heads/ is prepended.
574 --dgit-view-save is a deprecated alias for --save-dgit-view.
576 --deliberately-something
578 Declare that you are deliberately doing something. This can be
579 used to override safety catches, including safety catches which
580 relate to distro-specific policies. The use of --deliberately
581 is declared and published in the signed tags generated for you
582 by dgit, so that the archive software can give effect to your
583 intent, and for the benefit of humans looking at the history.
584 The meanings of somethings understood in the context of Debian
585 are discussed below:
586 --deliberately-not-fast-forward
588 Declare that you are deliberately rewriting history. This could
589 be because your branch is not fast forward from the dgit server
590 history, or not fast forward from a locally-synthesised dsc im‐
591 port.
592 When pushing to Debian, use this only when you are making a re‐
594 newed upload of an entirely new source package whose previous
595 version was not accepted for release from NEW because of prob‐
596 lems with copyright or redistributibility; or, exceptionally,
597 for the very first upload with dgit.
598 When split view is in operation, this also prevents the con‐
600 struction by dgit of a pseudomerge to make the dgit view fast
601 forwarding. Normally only one of --overwrite (which creates a
602 suitable pseudomerge) and --deliberately-not-fast-forward (which
603 suppresses the pseudomerge and the fast forward checks) should
604 be needed; --overwrite is usually better.
605 --deliberately-include-questionable-history
607 Declare that you are deliberately including, in the git history
608 of your current push, history which contains a previously-sub‐
609 mitted version of this package which was not approved (or has
610 not yet been approved) by the ftpmasters. When pushing to De‐
611 bian, only use this option after verifying that: none of the re‐
612 jected-from-NEW (or never-accepted) versions in the git history
613 of your current push, were rejected by ftpmaster for copyright
614 or redistributability reasons.
615 --deliberately-fresh-repo
617 Declare that you are deliberately rewriting history and want to
618 throw away the existing repo. Not relevant when pushing to De‐
619 bian, as the Debian server will do this automatically when nec‐
620 essary.
621 --quilt=linear
623 When fixing up source format `3.0 (quilt)' metadata, insist on
624 generating a linear patch stack: one new patch for each relevant
625 commit. If such a stack cannot be generated, fail. This is the
626 default for Debian.
627 HEAD should be a series of plain commits (not touching de‐
629 bian/patches/), and pseudomerges, with as ancestor a patches-ap‐
630 plied branch.
631 --quilt=auto
633 When fixing up source format `3.0 (quilt)' metadata, prefer to
634 generate a linear patch stack (as with --quilt=linear) but if
635 that doesn't seem possible, try to generate a single squashed
636 patch for all the changes made in git (as with --quilt=smash).
637 This is not a good idea for an NMU in Debian.
638 --quilt=smash
640 When fixing up source format `3.0 (quilt)' metadata, generate a
641 single additional patch for all the changes made in git. This
642 is not a good idea for an NMU in Debian.
643 (If HEAD has any in-tree patches already, they must apply
645 cleanly. This will be the case for any trees produced by dgit
646 fetch or clone; if you do not change the upstream version nor
647 make changes in debian/patches, it will remain true.)
648 --quilt=nofix
650 Check whether source format `3.0 (quilt)' metadata would need
651 fixing up, but, if it does, fail. You must then fix the meta‐
652 data yourself somehow before pushing. (NB that dpkg-source
653 --commit will not work because the dgit git tree does not have a
654 .pc directory.)
655 --quilt=nocheck | --no-quilt-fixup
657 Do not check whether source format `3.0 (quilt)' metadata needs
658 fixing up. If you use this option and the metadata did in fact
659 need fixing up, dgit push will fail.
660 --[quilt=]gbp | --[quilt=]dpm | --quilt=unapplied | --[quilt=]barede‐
662 bian[+git|+tarball]
663 Tell dgit that you are using a nearly-dgit-compatible git
664 branch, aka a maintainer view, and do not want your branch
665 changed by dgit.
666 These quilt modes are known as splitting quilt modes. See
668 --split-view, below.
669 --gbp (short for --quilt=gbp) is for use with git-buildpackage.
671 Your HEAD is expected to be a patches-unapplied git branch, ex‐
672 cept that it might contain changes to upstream .gitignore files.
673 This is the default for dgit gbp-build.
674 --dpm (short for --quilt=dpm) is for use with git-dpm. Your
676 HEAD is expected to be a patches-applied git branch, except that
677 it might contain changes to upstream .gitignore files.
678 --quilt=unapplied specifies that your HEAD is a patches-unap‐
680 plied git branch (and that any changes to upstream .gitignore
681 files are represented as patches in debian/patches).
682 --quilt=baredebian (or its alias --quilt=baredebian+git) speci‐
684 fies that your HEAD contains only a debian/ directory, with any
685 changes to upstream files represented as patches in de‐
686 bian/patches. The upstream source must be available in git, by
687 default, in a suitably named git tag; see --upstream-commitish.
688 In this mode, dgit cannot check that all edited upstream files
689 are properly represented as patches: dgit relies on de‐
690 bian/patches being correct.
691 --quilt=baredebian+tarball is like --quilt=baredebian, but is
693 used when there is no appropriate upstream git history. To con‐
694 struct the dgit view, dgit will import your orig tarballs' con‐
695 tents into git. In this mode, dgit cannot check that the up‐
696 stream parts of your upload correspond to what you intend: dgit
697 relies on the right orig tarball(s) existing, and debian/patches
698 being correct.
699 With --quilt=gbp|dpm|unapplied|baredebian*, dgit push (or pre‐
701 cursors like quilt-fixup and build) will automatically generate
702 a conversion of your git branch into the right form. dgit push
703 will push the dgit-compatible form (the dgit view) to the dgit
704 git server. The dgit view will be visible to you in the dgit
705 remote tracking branches, but your own branch will not be modi‐
706 fied. dgit push will create a tag debian/version for the main‐
707 tainer view, and the dgit tag archive/debian/version for the
708 dgit view. dgit quilt-fixup will merely do some checks, and
709 cache the maintainer view.
710 If you have a branch like this it is essential to specify the
712 appropriate --quilt= option! This is because it is not always
713 possible to tell: a patches-unapplied git branch of a package
714 with one patch, for example, looks very like a patches-applied
715 branch where the user has used git revert to undo the patch, ex‐
716 pecting to actually revert it. However, if you fail to specify
717 the right --quilt option, and you aren't too lucky, dgit will
718 notice the problem and stop, with a useful hint.
719 -ddistro | --distro=distro
721 Specifies that the suite to be operated on is part of distro
722 distro. This overrides the default value found from the git
723 config option dgit-suite.suite.distro. The only effect is that
724 other configuration variables (used for accessing the archive
725 and dgit-repos) used are dgit-distro.distro.*.
726 If your suite is part of a distro that dgit already knows about,
728 you can use this option to make dgit work even if your dgit
729 doesn't know about the suite. For example, specifying -ddebian
730 will work when the suite is an unknown suite in the Debian ar‐
731 chive.
732 To define a new distro it is necessary to define methods and
734 URLs for fetching (and, for dgit push, altering) a variety of
735 information both in the archive and in dgit-repos. How to set
736 this up is not yet documented.
737 --split-view=auto|always|never
739 Controls whether dgit operates a split view, separating your own
740 branch (as Debian maintainer) from that shown to users of dgit
741 clone and dgit fetch.
742 When split view is in operation dgit will not make or merge any
744 commits onto your own branch. Specifically, only the dgit view
745 will contain dgit's pseudomerges, which bring into the git his‐
746 tory previous uploads made with dgit push, and any commits in
747 debian/patches required to make a correct `3.0 (quilt)' source
748 package.
749 auto is the default, and splits the view only when needed: i.e.,
751 when you are working with a `3.0 (quilt)' source package and a
752 splitting quilt mode: --[quilt=]gbp, dpm, unpatched or barede‐
753 bian*.
754 always splits the view regardless of the source format and the
756 quilt mode.
757 never will cause dgit to fail if split view is needed.
759 When split view is in operation, the dgit view is visible in
761 your local git clone, but only in refs specific to dgit: notably
762 remotes/dgit/dgit/suite and archive/distro/version.
763 Note that split view does not affect dgit fetch, and is not com‐
765 patible with dgit pull.
766 -Cchangesfile
768 Specifies the .changes file which is to be uploaded. By default
769 dgit push looks for a single .changes file in the parent direc‐
770 tory whose filename suggests it is for the right package and
771 version.
772 If the specified changesfile pathname contains slashes, the di‐
774 rectory part is also used as the value for --build-products-dir;
775 otherwise, the changes file is expected in that directory (by
776 default, in ..).
777 --upstream-commitish=upstream
779 For use with --quilt=baredebian only. Specifies the commit con‐
780 taining the upstream source. This commit must be identical to
781 your .orig tarball. The default is to look for one of the git
782 tags U vU upstream/U (in that order), where U is the upstream
783 version.
784 --rm-old-changes
786 When doing a build, delete any changes files matching pack‐
787 age_version_*.changes before starting. This ensures that dgit
788 push (and dgit sbuild) will be able to unambiguously identify
789 the relevant changes files from the most recent build, even if
790 there have been previous builds with different tools or options.
791 The default is not to remove, but --no-rm-old-changes can be
792 used to override a previous --rm-old-changes or the .rm-old-
793 changes configuration setting.
794 Note that dgit push-source will always find the right .changes,
796 regardless of this option.
797 --build-products-dir=directory
799 Specifies where to find and create tarballs, binary packages,
800 source packages, .changes files, and so on.
801 By default, dgit uses the parent directory (..).
803 Changing this setting may necessitate moving .orig tarballs to
805 the new directory, so it is probably best to use the dgit.de‐
806 fault.build-products-dir configuration setting (see CONFIGURA‐
807 TION, below) which this command line option overrides).
808 --no-rm-on-error
810 Do not delete the destination directory if clone fails.
811 --dep14tag
813 Generates a DEP-14 tag (eg debian/version) as well as a dgit tag
814 (eg archive/debian/version). This is the default.
815 --no-dep14tag
817 Do not generate a DEP-14 tag, except when split view is in oper‐
818 ation.
819 --always-dep14tag
821 Obsolete alias for --dep14tag, retained for compatibility.
822 -D Prints debugging information to stderr. Repeating the option
824 produces more output (currently, up to -DDDD is meaningfully
825 different).
826 -cname=value
828 Specifies a git configuration option, to be used for this run.
829 dgit itself is also controlled by git configuration options.
830 -vversion|_ | --since-version=version|_
832 Specifies the -vversion option to pass to dpkg-genchanges, dur‐
833 ing builds. Changes (from debian/changelog) since this version
834 will be included in the built changes file, and hence in the up‐
835 load. If this option is not specified, dgit will query the ar‐
836 chive and use the latest version uploaded to the intended suite.
837 Specifying _ inhibits this, so that no -v option will be passed
839 to dpkg-genchanges (and as a result, only the last stanza from
840 debian/changelog will be used for the build and upload).
841 -mmaintaineraddress
843 Passed to dpkg-genchanges (eventually).
844 --ch:option
846 Specifies a single additional option to pass, eventually, to
847 dpkg-genchanges.
848 Options which are safe to pass include -C (and also -si -sa -sd
850 although these should never be necessary with Debian since dgit
851 automatically calculates whether .origs need to be uploaded.)
852 For other options the caveat below applies.
854 --curl:option | --dput:option |...
856 Specifies a single additional option to pass to curl, dput, deb‐
857 sign, dpkg-source, dpkg-buildpackage, dpkg-genchanges, sbuild,
858 pbuilder, cowbuilder, ssh, dgit, git-debrebase, apt-get, apt-
859 cache, gbp-pq, gbp-build, or mergechanges. Can be repeated as
860 necessary.
861 Use of this ability should not normally be necessary. It is
863 provided for working around bugs, or other unusual situations.
864 If you use these options, you may violate dgit's assumptions
865 about the behaviour of its subprograms and cause lossage.
866 For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
868 the option applies only when the program is invoked directly by
869 dgit. Usually, for passing options to dpkg-genchanges, you
870 should use --ch:option.
871 Specifying --git is not effective for some lower-level read-only
873 git operations performed by dgit, and also not when git is in‐
874 voked by another program run by dgit.
875 See notes below regarding ssh and dgit.
877 NB that --gpg:option is not supported (because debsign does not
879 have that facility). But see -k and the keyid distro config
880 setting.
881 --curl!:option | --dput!:option |...
883 Specifies an option to remove from the command line for a pro‐
884 gram called by dgit, as for --program:option (and the same
885 caveats apply).
886 Any options or arguments exactly identical to option are re‐
888 moved. (It is not an error if there were none.)
889 This can only be used to delete options which are always passed
891 by default by dgit, or to undo a previous --program:option. It
892 cannot be used to override option(s) dynamically decided on by
893 dgit.
894 --curl=program | --dput=program |...
896 Specifies alternative programs to use instead of curl, dput,
897 debsign, dpkg-source, dpkg-buildpackage, dpkg-genchanges,
898 sbuild, pbuilder, cowbuilder, gpg, ssh, dgit, git-debrebase,
899 apt-get, apt-cache, git, gbp-pq, gbp-build, or mergechanges.
900 For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
902 this applies only when the program is invoked directly by dgit.
903 For dgit, specifies the command to run on the remote host when
905 dgit rpush needs to invoke a remote copy of itself. (dgit also
906 reinvokes itself as the EDITOR for dpkg-source --commit; this is
907 done using argv[0], and is not affected by --dgit=).
908 gbp-build's value is used instead of gbp build or git-buildpack‐
910 age. (The default is the latter unless the former exists on
911 PATH.) gbp-pq's value is used instead of gbp pq. In both
912 cases, unusually, the specified value is split on whitespace to
913 produce a command and possibly some options and/or arguments.
914 For pbuilder and cowbuilder, the defaults are sudo -E pbuilder
916 and sudo -E cowbuilder respectively. Like with gbp-build and
917 gbp pq, the specified value is split on whitespace.
918 For ssh, the default value is taken from the DGIT_SSH or GIT_SSH
920 environment variables, if set (see below). And, for ssh, when
921 accessing the archive and dgit-repos, this command line setting
922 is overridden by the git config variables dgit-distro.distro.ssh
923 and .dgit.default.ssh (which can in turn be overridden with -c).
924 Also, when dgit is using git to access dgit-repos, only git's
925 idea of what ssh to use (eg, GIT_SSH) is relevant.
926 --existing-package=package
928 dgit push needs to canonicalise the suite name. Sometimes, dgit
929 lacks a way to ask the archive to do this without knowing the
930 name of an existing package. Without --new we can just use the
931 package we are trying to push. But with --new that will not
932 work, so we guess dpkg or use the value of this option. This
933 option is not needed with the default mechanisms for accessing
934 the archive.
935 -h|--help
937 Print a usage summary.
938 --initiator-tempdir=directory
940 dgit rpush uses a temporary directory on the invoking (signing)
941 host. This option causes dgit to use directory instead. Fur‐
942 thermore, the specified directory will be emptied, removed and
943 recreated before dgit starts, rather than removed after dgit
944 finishes. The directory specified must be an absolute pathname.
945 --force-something
947 Instructs dgit to try to proceed despite detecting what it
948 thinks is going to be a fatal problem. This is probably not go‐
949 ing to work. These options are provided as an escape hatch, in
950 case dgit is confused. (They might also be useful for testing
951 error cases.)
952 --force-import-dsc-with-dgit-field
954 Tell dgit import-dsc to treat a .dsc with a Dgit field like one
955 without it. The result is a fresh import, discarding the git
956 history that the person who pushed that .dsc was working with.
957 --force-reusing-version
959 Carry on even though this involves reusing a version number of a
960 previous push or upload. It is normally best to give different
961 versions different numbers. Some servers (including, usually,
962 the Debian server) will reject attempts to reuse or replace al‐
963 ready-pushed versions.
964 --force-uploading-binaries
966 Carry on and upload binaries even though dgit thinks your distro
967 does not permit that.
968 --force-uploading-source-only
970 Carry on and do a source-only upload, without any binaries, even
971 though dgit thinks your distro does not permit that, or does not
972 permit that in this situation.
973 --force-unrepresentable
975 Carry on even if dgit thinks that your git tree contains changes
976 (relative to your .orig tarballs) which dpkg-source is not able
977 to represent. Your build or push will probably fail later.
978 --force-changes-origs-exactly
980 Use the set of .origs specified in your .changes, exactly, with‐
981 out regard to what is in the archive already. The archive may
982 well reject your upload.
983 --force-unsupported-source-format
985 Carry on despite dgit not understanding your source package for‐
986 mat. dgit will probably mishandle it.
987 --force-dsc-changes-mismatch
989 Do not check whether .dsc and .changes match. The archive will
990 probably reject your upload.
991 --force-import-gitapply-absurd | --force-import-gitapply-no-absurd
993 Force on or off the use of the absurd git-apply emulation when
994 running gbp pq import when importing a package from a .dsc. See
995 Debian bug #841867.
996 --for-push
998 Override the dgit-distro.distro.readonly configuration setting,
999 to specify that we have read/write access and should use the
1000 corresponding git and achieve access approach even if the opera‐
1001 tion is a read-only one.
1002
1004 dgit can be configured via the git config system. You may set keys
1005 with git-config (either in system-global or per-tree configuration), or
1006 provide -ckey=value on the dgit command line.
1007 Settings likely to be useful for an end user include:
1009 dgit.default.build-products-dir
1011 Specifies where to find the built files to be uploaded, when
1012 --build-products-dir is not specified. The default is the par‐
1013 ent directory (..).
1014 dgit-suite.suite.distro distro
1016 Specifies the distro for a suite. dgit keys off the suite name
1017 (which appears in changelogs etc.), and uses that to determine
1018 the distro which is involved. The config used is thereafter
1019 that for the distro.
1020 suite may be a glob pattern.
1022 dgit.default.distro distro
1024 The default distro for an unknown suite.
1025 This is only used if no /usr/share/distro-info/somedistro.csv
1027 mentions the specified suite.
1028 dgit.default.default-suite suite
1030 The default suite (eg for clone).
1031 dgit.default.*
1033 for each dgit-distro.distro.*, the default value used if there
1034 is no distro-specific setting.
1035 dgit-distro.distro.clean-mode
1037 One of the values for the command line --clean= option; used if
1038 --clean is not specified.
1039 dgit-distro.distro.clean-mode-newer
1041 Like .clean-mode, but ignored if the value is unknown to this
1042 version of dgit. Setting both .clean-mode and .clean-mode-newer
1043 is useful to provide a single git config compatible with differ‐
1044 ent dgit versions.
1045 dgit-distro.distro.quilt-mode
1047 One of the values for the command line --quilt= option; used if
1048 --quilt is not specified.
1049 dgit-distro.distro.split-view
1051 dgit-distro.distro.rm-old-changes
1053 Boolean, used if neither --rm-old-changes nor --no-rm-old-
1054 changes is specified. The default is not to remove.
1055 dgit-distro.distro.readonly auto|a | true|t|y|1 | false|f|n|0
1057 Whether you have push access to the distro. For Debian, it is
1058 OK to use auto, which uses readonly mode if you are not pushing
1059 right now; but, setting this to false will avoid relying on the
1060 mirror of the dgit git repository server.
1061 dgit-distro.distro.keyid
1063 See also -k.
1064 dgit-distro.distro.mirror url
1066 dgit-distro.distro.username
1068 Not relevant for Debian.
1069 dgit-distro.distro.upload-host
1071 Might be useful if you have an intermediate queue server.
1072 dgit-distro.distro.user-name dgit-distro.distro.user-email
1074 Values to configure for user.name and user.email in new git
1075 trees. If not specified, the DEBFULLNAME and DEBEMAIL environ‐
1076 ment variables are used, respectively. Only used if .setup-
1077 usermail is not disabled.
1078 dgit-distro.distro.setup-useremail
1080 Whether to set user.name and user.email in new git trees. True
1081 by default. Ignored for dgit setup-useremail, which does it
1082 anyway.
1083 dgit-distro.distro.setup-mergechangelogs
1085 Whether to set up a merge driver which uses dpkg-mergechangelogs
1086 for debian/changelog. True by default. Ignored for dgit setup-
1087 mergechangelogs, which does it anyway.
1088 dgit-distro.distro.setup-gitattributes
1090 Whether to configure .git/info/attributes to suppress
1091 checkin/checkout file content transformations in new git trees.
1092 True by default. Ignored for dgit setup-gitattributes, which
1093 does it anyway.
1094 dgit-distro.distro.cmd-cmd
1096 Program to use instead of cmd. Works like --cmd=... .
1097 dgit-distro.distro.opts-cmd
1099 Extra options to pass to cmd. Works like --cmd:... . To pass
1100 several options, configure multiple values in git config (with
1101 git config --add). The options for dgit.default.opts-cmd and
1102 dgit-distro.distro/push.opts-cmd are all used, followed by op‐
1103 tions from dgit's command line.
1104
1106 There are many other settings which specify how a particular distro's
1107 services (archive and git) are provided. These should not normally be
1108 adjusted, but are documented for the benefit of distros who wish to
1109 adopt dgit.
1110 dgit-distro.distro.nominal-distro
1112 Shown in git tags, Dgit fields, and so on.
1113 dgit-distro.distro.alias-canon
1115 Used for all access configuration lookup.
1116 dgit-distro.distro/push.*
1118 If set, overrides corresponding non /push config when read‐
1119 only=false, or when pushing and readonly=auto.
1120 dgit-distro.distro.git-url
1122 dgit-distro.distro.git-url[-suffix]
1124 dgit-distro.distro.git-proto
1126 dgit-distro.distro.git-path
1128 dgit-distro.distro.git-check true|false|url|ssh-cmd
1130 dgit-distro.distro.git-check-suffix
1132 dgit-distro.distro.diverts.divert new-distro|/distro-suffix
1134 dgit-distro.distro.git-create ssh-cmd|true
1136 dgit-distro.distro.archive-query ftpmasterapi: | madison:distro | dum‐
1138 mycat:/path | sshpsql:user@host:dbname | aptget:
1139 dgit-distro.distro.archive-query-(url|tls-key|curl-ca-args)
1141 dgit-distro.distro.madison-distro
1143 dgit-distro.distro.archive-query-default-component
1145 dgit-distro.distro.dgit-tag-format
1147 dgit-distro.distro.dep14tag want|no[|always]
1149 dgit-distro.distro.ssh
1151 dgit-distro.distro.sshpsql-dbname
1153 dgit-distro.distro.(git|sshpsql)-(user|host|user-force)
1155 dgit-distro.distro.backports-quirk
1157 dgit-distro.distro.rewrite-map-enable
1159 dgit-distro.distro.source-only-uploads ok|always|never|not-wholly-new
1161 dgit.default.old-dsc-distro
1163 dgit.dsc-url-proto-ok.protocol
1165 dgit.dsc-url-proto-ok.bad-syntax
1167 dgit.default.dsc-url-proto-ok
1169 dgit.vcs-git.suites suite[;...]
1171
1173 DGIT_SSH, GIT_SSH
1174 specify an alternative default program (and perhaps arguments)
1175 to use instead of ssh. DGIT_SSH is consulted first and may con‐
1176 tain arguments; if it contains any whitespace will be passed to
1177 the shell. GIT_SSH specifies just the program; no arguments can
1178 be specified, so dgit interprets it the same way as git does.
1179 See also the --ssh= and --ssh: options.
1180 DEBEMAIL, DEBFULLNAME
1182 Default git user.email and user.name for new trees. See dgit
1183 setup-new-tree.
1184 gpg, dpkg-..., debsign, git, [lib]curl, dput
1186 and other subprograms and modules used by dgit are affected by
1187 various environment variables. Consult the documentation for
1188 those programs for details.
1189
1191 There should be a `dgit rebase-prep' command or some such to turn a
1192 fast-forwarding branch containing pseudo-merges back into a rebasing
1193 patch stack. It might have to leave a note for a future dgit push.
1194 If the dgit push fails halfway through, it is not necessarily
1196 restartable and idempotent. It would be good to check that the pro‐
1197 posed signing key is available before starting work.
1198 dgit's build functions, and dgit push, may make changes to your current
1200 HEAD. Sadly this is necessary for packages in the `3.0 (quilt)' source
1201 format. This is ultimately due to what I consider design problems in
1202 quilt and dpkg-source.
1203 --dry-run does not always work properly, as not doing some of the git
1205 fetches may result in subsequent actions being different. Doing a non-
1206 dry-run dgit fetch first will help. --damp-run is likely to work much
1207 better.
1208
1210 dgit(7), dgit-*[22m(7), curl(1), dput(1), debsign(1), git-config(1), git-
1211 buildpackage(1), dpkg-buildpackage(1),
1212 https://browse.dgit.debian.org/
1213Debian Project dgit(1)