.br
.B dgit
[\fIdgit\-opts\fP] \fBbuild\fP|\fBsbuild\fP|\fBbuild-source\fP
-[\fIbuild\-opts\fp]
+[\fIbuild\-opts\fP]
.br
.B dgit
-[\fIdgit\-opts\fP] \fBpush\fP [\fIdgit\-opts\fP]
+[\fIdgit\-opts\fP] \fBpbuilder\fP|\fBcowbuilder\fP
+[\fIdebbuildopts\fP]
+.br
+.B dgit
+[\fIdgit\-opts\fP] \fBpush\fP|\fBpush-source\fP [\fIdgit\-opts\fP]
[\fIsuite\fP]
.br
.B dgit
.B dgit
allows you to treat the Debian archive as if it were a git
repository.
+Conversely,
+it allows Debian to publish the source of its packages
+as git branches, in a format which is directly useable
+by ordinary people.
This is the command line reference.
Please read the tutorial(s):
.TS
lb l.
-dgit-user(7) for users: editing, building and sharing packages
-dgit-nmu-simple(7) for DDs: doing a straightforward NMU
+dgit-user(7) for users: edit, build and share packages
+dgit-nmu-simple(7) for DDs: do a straightforward NMU
dgit-maint-native(7) for maintainers of Debian-native packages
-dgit-maint-merge(7) for maintainers who want a pure git workflow
+dgit-maint-debrebase(7) for maintainers: a pure-git rebasish workflow
+dgit-maint-merge(7) for maintainers: a pure-git merging workflow
dgit-maint-gbp(7) for maintainers already using git-buildpackage
dgit-sponsorship(7) for sponsors and sponsored contributors
+dgit-downstream-dsc(7) setting up dgit push for a new distro
.TE
.LP
See \fBdgit(7)\fP for detailed information about the data
remote will be set up from the package's Vcs-Git field, if there is
one - but note that in the general case the history found there may be
different to or even disjoint from dgit's view.
+(See also dgit update-vcs-git.)
.TP
\fBdgit fetch\fR [\fIsuite\fP]
Consults the archive and git-repos to update the git view of
.BI remotes/dgit/dgit/ suite
into the current branch.
.TP
+\fBdgit checkout\fR \fIsuite\fR
+Checks out the local branch
+.BR dgit/ \fIsuite\fR.
+
+If the branch does not exist,
+dgit checkout creates it,
+and sets it up the same way as dgit clone would.
+In that case, if
+the archive remote tracking branch does not exist,
+dgit checkout will do a dgit fetch first.
+
+NB: dgit checkout will only do a fetch if it has to.
+If you already have the suite branch,
+and want to merge your branch with updates from the archive,
+use dgit pull.
+
+dgit checkout will normally need to access the archive server,
+to canonicalise the provided suite name.
+The exception is if you specify the canonical name,
+and the branch (or tracking branch) already exists.
+.TP
\fBdgit build\fR ...
Runs
.B dpkg-buildpackage
commit.
Tagging, signing and actually uploading should be left to dgit push.
+
+dgit's build operations access the network,
+to get the \-v option right.
+See \-v, below.
.TP
\fBdgit build-source\fR ...
Builds the source package, and a changes file for a prospective
and
.IR package \fB_\fR version \fB_source.changes\fR.
-Tagging, signing and actually uploading should be left to dgit push.
+Tagging, signing and actually uploading should be left to dgit
+push-source, or dgit push.
.TP
.B dgit clean
-Cleans the current working tree (according to the --clean= option in
+Cleans the current working tree (according to the \-\-clean= option in
force).
.TP
+\fBdgit update-vcs-git\fR [\fIsuite\fP|\fB.\fR] [\fB\-\-\fR] [\fIgit fetch options\fR]
+.TQ
+\fBdgit update-vcs-git\fR [\fIsuite|\fP\fB.\fR] \fB\-\fR
+Sets up, or updates the url of, the vcs-git remote, and
+(unless \fB-\fR was specified)
+runs git fetch on it.
+
+By default, the Vcs-Git field of the .dsc from Debian sid is used,
+as that is probably most up to date.
+Another suite may be specified, or
+.B .
+to indicate that the Vcs-Git of the cwd's debian/control should
+be used instead.
+.TP
.B dgit help
Print a usage summary.
.TP
.IP
Note that by default
sbuild does not build arch-independent packages.
-You probably want to pass -A, to request those.
+You probably want to pass \-A, to request those.
.IP
Tagging, signing and actually uploading should be left to dgit push.
.TP
+\fBdgit pbuilder\fR [\fIdebbuildopts\fP]
+Constructs the source package, uses
+.B pbuilder
+to do a binary build, and uses mergechanges to merge the source and
+binary changes files.
+The output is left in
+.IR package \fB_\fR version \fB_multi.changes\fR.
+
+You should ensure that your dgit \-\-build-products-dir setting matches
+your pbuilder \-\-buildresult.
+
+The \fIdebbuildopts\fP are passed to pbuilder using its \-\-debbuildopts
+option. If you want to pass other options to pbuilder, use the
+\fB\-\-pbuilder:\fR dgit option as described below
+(remember that dgit options should appear between \fBdgit\fR and
+\fBpbuilder\fR).
+
+You should ensure that in your pbuilderrc you do
+.B not
+have the setting
+.B SOURCE_ONLY_CHANGES=yes
+as this may cause trouble.
+.TP
+\fBdgit cowbuilder\fR [\fIdebbuildopts\fP]
+Like \fBdgit pbuilder\fR, but uses
+.B cowbuilder
+instead of
+.B pbuilder.
+.TP
\fBdgit gbp-build\fR ...
Runs
.B git-buildpackage
the .dsc. It then pushes the HEAD to the suite's dgit-repos branch,
adjusts the .changes to include any .origs which the archive lacks
and exclude .origs which the archive has
-(so -sa and -sd are not needed when building for dgit push),
+(so \-sa and \-sd are not needed when building for dgit push),
makes a signed git tag, edits the .dsc to contain the dgit metadata
field, runs debsign to sign the upload (.dsc and .changes), pushes the
signed tag, and finally uses dput to upload the .changes to the
dgit push always uses the package, suite and version specified in the
debian/changelog and the .dsc, which must agree. If the command line
specifies a suite then that must match too.
+
+When used on a git-debrebase branch,
+dgit calls git-debrebase
+to prepare the branch
+for source package upload and push.
+.TP
+\fBdgit push-source\fR [\fIsuite\fP]
+Without \fB\-C\fR, builds a source package and dgit pushes it. Saying
+\fBdgit push-source\fR is like saying "update the source code in the
+archive to match my git HEAD, and let the autobuilders do the rest."
+
+With \fB\-C\fR, performs a dgit push, additionally ensuring that no
+binary packages are uploaded.
.TP
\fBdgit rpush\fR \fIbuild-host\fR\fB:\fR\fIbuild-dir\fR [\fIpush args...\fR]
Pushes the contents of the specified directory on a remote machine.
1. Clone on build host (dgit clone)
2. Edit code on build host (edit, git commit)
3. Build package on build host (dgit build)
-4. Test package on build host or elsewhere (dpkg -i, test)
+4. Test package on build host or elsewhere (dpkg \-i, test)
5. Upload by invoking dgit rpush on host with your GPG key.
.TE
(but only does each thing if dgit is configured to do it automatically).
You can use these in any git repository, not just ones used with
the other dgit operations.
+Does
+.B not
+run
+.B update-vcs-git
+(as that requires Debian packaging information).
.TP
.B dgit setup-useremail
Set the working tree's user.name and user.email from the
Set up the working tree's
.B .git/info/attributes
to disable all transforming attributes for all files.
-This is done by defining a macro attribute
-.B dgit-defuse-attrs
+This is done by defining a macro attribute,
+.B dgit-defuse-attrs,
and applying it to
.BR * .
For why, see
.B GITATTRIBUTES
in
.BR dgit(7) .
+Note that only attributes affecting the working tree are suppressed.
+git-archive may remain exciting.
+
+If there is an existing macro attribute line
+.B [attr]dgit-defuse-attrs
+in .git/info/attributes,
+but it is insufficient,
+because it was made by an earlier version of dgit
+and git has since introduced new transforming attributes,
+this modifies the macro to disable the newer transformations.
(If there is already a macro attribute line
.B [attr]dgit-defuse-attrs
in .git/info/attributes
-(whatever its effects),
+which does what dgit requires
+(whatever files it effects),
this operation does nothing further.
This fact can be used to defeat or partially defeat
dgit setup-gitattributes
other kinds of more exotic history. If dgit can't find a suitable
linearisation of your history, by default it will fail, but you can
ask it to generate a single squashed patch instead.
+
+When used with a git-debrebase branch,
+dgit will ask git-debrebase to prepare patches.
+However,
+dgit can make patches in some situations where git-debrebase fails,
+so dgit quilt-fixup can be useful in its own right.
+To always use dgit's own patch generator
+instead of git-debrebase make-patches,
+pass \-\-git-debrebase=true to dgit.
+
+See
+.B FORMAT 3.0 (QUILT)
+in
+.BR dgit(7) .
.TP
\fBdgit import-dsc\fR [\fIsub-options\fR] \fI../path/to/.dsc\fR [\fB+\fR|\fB..\fR]branch
Import a Debian-format source package,
import-dsc might need online access.
If this is a problem
(or dgit's efforts to find the commit fail),
-consider --no-chase-dsc-distro
-or --force-import-dsc-with-dgit-field.
+consider \-\-no-chase-dsc-distro
+or \-\-force-import-dsc-with-dgit-field.
-There is only only sub-option:
+There is only one sub-option:
-.B --require-valid-signature
+.B \-\-require-valid-signature
causes dgit to insist that the signature on the .dsc is valid
-(using the same criteria as dpkg-source -x).
+(using the same criteria as dpkg-source \-x).
Otherwise, dgit tries to verify the signature but
the outcome is reported only as messages to stderr.
.I branch
is prefixed with
.B +
-then if it already exists, it will be simply ovewritten,
+then if it already exists, it will be simply overwritten,
no matter its existing contents.
If
.I branch
dgit will make a pseudomerge
so that the result is necessarily fast forward
from the existing branch.
-Otherwise, if branch already exists,
+Otherwise, if \fIbranch\fR already exists,
dgit will stop with an error message.
If
Prints the url used by dgit clone-dgit-repos-server.
This is hopefully suitable for use as a git remote url.
It may not be useable in a browser.
+.TP
+.BI "dgit print-dpkg-source-ignores"
+Prints the \-i and \-I arguments which must be passed to dpkg-souce
+to cause it to exclude exactly the .git directory
+and nothing else.
+The separate arguments are unquoted, separated by spaces,
+and do not contain spaces.
+.TP
+.B dgit print-unapplied-treeish
+Constructs a tree-ish approximating the patches-unapplied state
+of your 3.0 (quilt) package,
+and prints the git object name to stdout.
+This requires appropriate .orig tarballs.
+This tree object is identical to your .origs
+as regards upstream files.
+The contents of the debian subdirectory is not interesting
+and should not be inspected;
+except that debian/patches will be identical to your HEAD.
+
+To make this operate off-line,
+the access configuration key
+which is used to determine the build-products-dir
+is the uncanonicalised version of the suite name from the changelog,
+or (of course) dgit.default.build-products-dir.
+See ACCESS CONFIGURATION, below.
+
+This function is primarily provided for the benefit of git-debrebase.
.SH OPTIONS
.TP
-.BR --dry-run " | " -n
+.BR \-\-dry-run " | " \-n
Go through the motions, fetching all information needed, but do not
actually update the output(s). For push, dgit does
the required checks and leaves the new .dsc in a temporary file,
but does not sign, tag, push or upload.
.TP
-.BR --damp-run " | " -L
+.BR \-\-damp-run " | " \-L
Go through many more of the motions: do everything that doesn't
involve either signing things, or making changes on the public
servers.
.TP
-.BI -k keyid
+.BI \-k keyid
Use
.I keyid
for signing the tag and the upload. The default comes from the
options other than dpkg-source
are useful when the package's clean target is troublesome, or
to avoid needing the build-dependencies.
+
+dgit will only actually clean the tree if it needs to
+(because it needs to build the source package
+or binaries from your working tree).
+Otherwise
+it will just check that there are no untracked unignored files.
+See --clean=git[-ff],always, below.
.TP
.BR --clean=git-ff " | " -wgf
Use
but it also removes any subdirectories containing different git
trees (which only unusual packages are likely to create).
.TP
-.BR --clean=check " | " -wc
+.BR --clean=git "[" -ff "]" ,always " | " -wga " | " -wgfa
+Like --clean=git, but always does the clean and not just a check,
+deleting any untracked un-ignored files.
+.TP
+.BR --clean=check " | " --clean=check,ignores " | " -wc " | " -wci
Merely check that the tree is clean (does not contain uncommitted
files).
Avoids running rules clean,
and can avoid needing the build-dependencies.
-.TP
-.BR --clean=none " | " -wn
+
+With
+.BR ,ignores
+or
+.BR \-wci ,
+untracked files covered by .gitignore are tolerated,
+so only files which show up as
+.B ?
+in git status
+(ie, ones you maybe forgot to git add)
+are treated as a problem.
+.TP
+.BR \-\-clean=none " | " \-wn
Do not clean the tree, nor check that it is clean.
Avoids running rules clean,
and can avoid needing the build-dependencies.
files which are not in git, or if the build creates such files, a
subsequent dgit push will fail.
.TP
-.BR --clean=dpkg-source " | " -wd
+.BR --clean=dpkg-source "[" -d "] | " -wd " | " -wdd
Use dpkg-buildpackage to do the clean, so that the source package
is cleaned by dpkg-source running the package's clean target.
-This is the default.
-Requires the package's build dependencies.
-.TP
-.BR --clean=dpkg-source-d " | " -wdd
-Use
-.B dpkg-buildpackage -d
-to do the clean,
-so that the source package
-is cleaned by dpkg-source running the package's clean target.
-The build-dependencies are not checked (due to
-.BR -d ),
+--clean=dpkg-source is the default.
+
+Without the extra
+.BR d ,
+requires the package's build dependencies.
+
+With
+.BR ... -d
+or
+.BR -wdd ,
+the build-dependencies are not checked
+(due to passing
+.BR -d
+to dpkg-buildpackage),
which violates policy, but may work in practice.
+
+The rules clean target will only be run if it is needed:
+when dgit is going to build source or binary packages
+from your working tree,
+rather than from your git branch
+(for example because of \-\-include-dirty
+or because the binary package build uses your working tree).
+
+In all cases,
+dgit will check that there are (after rules clean, if applicable) no
+untracked un-ignored files,
+in case these are files you forgot to git add.
+(Except that this check is not done
+for a `3.0 (quilt)' package
+when dgit has to apply patches, dirtily, to the working tree.)
+If your package does not have a good .gitignore
+you will probably need --clean=dpkg-source,no-check aka -wdn.
+.TP
+.BR --clean=dpkg-source "[" -d "]" ,no-check " | " -wdn " | " -wddn
+Like --clean=dpkg-source, but
+does not care about untracked un-ignored files.
+.TP
+.BR --clean=dpkg-source "[" -d "]" ,all-check " | " -wda " | " -wdda
+Like --clean=dpkg-source, but
+fails even on ignored untracked files.
+This could perhaps be used to detect bugs in your rules clean target.
.TP
.BR -N " | " --new
The package is or may be new in this suite. Without this, dgit will
-refuse to push. It may (for Debian, will) be unable to access the git
+refuse to push.
+It may (for Debian, will) be unable to access the git
history for any packages which have been newly pushed and have not yet
been published.
.TP
-.BR --ignore-dirty
-Do not complain if the working tree does not match your git HEAD.
+.BR --include-dirty
+Do not complain if the working tree does not match your git HEAD,
+and when building,
+include the changes from your working tree.
This can be useful with build, if you plan to commit later. (dgit
push will still ensure that the .dsc you upload and the git tree
you push are identical, so this option won't make broken pushes.)
+
+Note that this does
+.BR not
+prevent dgit from cleaning your tree, so if the changes in your
+working tree are in the form of untracked files, those might still be
+deleted, especially with --clean=git.
+If you want to include untracked files in the build, you can
+use --clean=none or --clean=dpkg-source[-d]
+in addition to --include-dirty.
+Note that this
+combination can fail if the untracked files are under
+\fIdebian/patches/\fR.
+.TP
+.BR --ignore-dirty
+Deprecated alias for --include-dirty.
.TP
.BR --overwrite [=\fIprevious-version\fR]
-Declare that even though your git branch is not a descendant
+Declare that your HEAD really does contain
+all the (wanted) changes
+from all versions listed in its changelog;
+or, all (wanted) changes from
+.IR previous-version .
+This promise is needed when
+your git branch is not a descendant
of the version in the archive
-according to the revision history,
-it really does contain
-all the (wanted) changes from that version.
+according to the git revision history.
+
+It is safer not to specify
+.IR previous-version ,
+and usually it's not needed.
+Just say
+.BR \-\-overwrite ,
+unless you know what you are doing.
This option is useful if you are the maintainer, and you have
incorporated NMU changes into your own git workflow in a way that
doesn't make your branch a fast forward from the NMU.
+It can also be useful when an intermediate upload was not done with dgit.
-.I previous-version
-ought to be the version currently in the archive. If
+This option is also usually necessary
+the first time a package is pushed with dgit push
+to a particular suite.
+See
+.BR dgit-maint- \fI*\fR (7) .
+
+If
.I previous-version
is not
specified, dgit will check that the version in the archive is
mentioned in your debian/changelog.
(This will avoid losing
-changes unless someone committed to git a finalised changelog
+changes, even with
+.BR --overwrite ,
+unless someone committed to git a finalised changelog
entry, and then made later changes to that version.)
+If
+.IR previous-version
+is specified, it ought to be the version currently in the archive.
dgit push --overwrite
-will make a
+will, if necessary, make a
pseudo-merge (that is, something that looks like the result
of git merge -s ours) to stitch the archive's version into your own
git history, so that your push is a fast forward from the archive.
(In quilt mode
-.BR gbp ", " dpm " or " unpatched ,
+.BR gbp ", " dpm ", " unpatched " or " baredebian *,
implying a split between the dgit view and the
maintainer view, the pseudo-merge will appear only in the dgit view.)
.TP
-.BR --delayed =\fIdays\fR
+.BR \-\-delayed =\fIdays\fR
Upload to a DELAYED queue.
.B WARNING:
it can mean that
dgit fails to find necessary git commits.
.TP
-.BR --dgit-view-save= \fIbranch\fR|\fIref\fR
-Specifies that when a split view quilt mode is in operation,
+.BR \-\-save-dgit-view= \fIbranch\fR|\fIref\fR
+Specifies that when split view is in operation,
and dgit calculates
(or looks up in its cache)
a dgit view corresponding to your HEAD,
This option is effective only with the following operations:
quilt-fixup; push; all builds.
-And it is only effective with
---[quilt=]gbp,
---[quilt=]dpm,
---quilt=unpatched.
+And it is only effective when split view is actually in operation.
If ref does not start with refs/
-it is taken to to be a branch -
+it is taken to be a branch -
i.e. refs/heads/ is prepended.
+
+.B \-\-dgit-view-save
+is a deprecated alias for
+\-\-save-dgit-view.
.TP
-.BI --deliberately- something
+.BI \-\-deliberately- something
Declare that you are deliberately doing
.IR something .
This can be used to override safety catches, including safety catches
which relate to distro-specific policies.
-The use of --deliberately is declared and published in the signed tags
+The use of \-\-deliberately is declared and published in the signed tags
generated for you by dgit,
so that the archive software can give effect to your intent,
and
-for the benefit humans looking at the history.
+for the benefit of humans looking at the history.
The meanings of
.IR something s
understood in the context of Debian are discussed below:
.TP
.BR --deliberately-not-fast-forward
-Declare that you are deliberately rewinding history. When pushing to
-Debian, use this when you are making a renewed upload of an entirely
+Declare that you are deliberately rewinding history.
+This could be because your branch is not fast forward from the
+dgit server history,
+or not fast forward from a locally-synthesised dsc import.
+
+When pushing to Debian,
+use this only when you are making a renewed upload of an entirely
new source package whose previous version was not accepted for release
-from NEW because of problems with copyright or redistributibility.
+from NEW because of problems with copyright or redistributibility;
+or, exceptionally, for the very first upload with dgit.
+
+When split view is in operation,
+this also prevents the construction by dgit of a pseudomerge
+to make the dgit view fast forwarding.
+Normally only one of
+--overwrite (which creates a suitable pseudomerge)
+and
+--deliberately-not-fast-forward
+(which suppresses the pseudomerge and the fast forward checks)
+should be needed;
+--overwrite is usually better.
.TP
.BR --deliberately-include-questionable-history
Declare that you are deliberately including, in the git history of
.BR --quilt=auto
When fixing up source format `3.0 (quilt)' metadata, prefer to
generate a linear patch stack
-(as with --quilt=auto)
+(as with --quilt=linear)
but if that doesn't seem possible,
try to generate a single squashed patch for all the changes made in git
(as with --quilt=smash).
directory.)
.TP
.BR --quilt=nocheck " | " --no-quilt-fixup
-Do not check whether up source format `3.0 (quilt)' metadata needs
+Do not check whether source format `3.0 (quilt)' metadata needs
fixing up. If you use this option and the metadata did in fact need
fixing up, dgit push will fail.
.TP
-.BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied
+.BR -- [ quilt= ] gbp " | " -- [ quilt= ] dpm " | " --quilt=unapplied " | " -- [ quilt= ] baredebian [ +git | +tarball ]
Tell dgit that you are using a nearly-dgit-compatible git branch,
aka a
.BR "maintainer view" ,
and
do not want your branch changed by dgit.
+These quilt modes are known as
+.BR "splitting quilt modes" .
+See --split-view, below.
+
.B --gbp
(short for
.BR --quilt=gbp )
that any changes to upstream .gitignore files are represented as
patches in debian/patches).
-With --quilt=gbp|dpm|unapplied,
+.B --quilt=baredebian
+(or its alias
+.BR --quilt=baredebian+git )
+specifies that your HEAD contains only a debian/ directory,
+with any changes to upstream files represented as
+patches in debian/patches.
+The upstream source must be available in git,
+by default, in a suitably named git tag;
+see --upstream-commitish.
+In this mode, dgit cannot check that
+all edited upstream files are properly represented as patches:
+dgit relies on
+debian/patches being correct.
+
+.B --quilt=baredebian+tarball
+is like --quilt=baredebian,
+but is used when there is no appropriate upstream git history.
+To construct the dgit view,
+dgit will import your orig tarballs' contents into git.
+In this mode, dgit cannot check that
+the upstream parts of your upload correspond to what you intend:
+dgit relies on
+the right orig tarball(s) existing, and
+debian/patches being correct.
+
+With --quilt=gbp|dpm|unapplied|baredebian*,
dgit push (or precursors like quilt-fixup and build) will automatically
generate a conversion of your git branch into the right form.
dgit push will push the
dgit quilt-fixup will merely do some checks,
and cache the maintainer view.
-.B If you have a branch like this it is essential to specify the appropriate --quilt= option!
+.B If you have a branch like this it is essential to specify the appropriate \-\-quilt= option!
This is because it is not always possible to tell: a patches-unapplied
git branch of a package with one patch, for example, looks very like
a patches-applied branch where the user has used git revert to
undo the patch, expecting to actually revert it.
However, if you fail to specify the right \-\-quilt option,
and you aren't too lucky, dgit will notice the problem and stop,
-with a useful hint.
+with a useful hint.
.TP
-.BR -d "\fIdistro\fR | " --distro= \fIdistro\fR
+.BR \-d "\fIdistro\fR | " \-\-distro= \fIdistro\fR
Specifies that the suite to be operated on is part of distro
.IR distro .
This overrides the default value found from the git config option
If your suite is part of a distro that dgit already knows about, you
can use this option to make dgit work even if your dgit doesn't know
about the suite. For example, specifying
-.B -ddebian
+.B \-ddebian
will work when the suite is an unknown suite in the Debian archive.
To define a new distro it is necessary to define methods and URLs
in the archive and in dgit-repos.
How to set this up is not yet documented.
.TP
-.BI -C changesfile
+.BR \-\-split-view=auto | always | never
+Controls whether dgit operates a split view,
+separating your own branch (as Debian maintainer)
+from that shown to users of dgit clone and dgit fetch.
+
+When split view is in operation
+dgit will not make or merge any commits onto your own branch.
+Specifically, only the dgit view will contain
+dgit's pseudomerges,
+which bring into the git history previous uploads made with dgit push,
+and any commits in debian/patches required
+to make a correct `3.0 (quilt)' source package.
+
+.B auto
+is the default, and splits the view only when needed:
+i.e., when you are working with a `3.0 (quilt)' source package
+and a splitting quilt mode:
+\-\-[quilt=]gbp, dpm, unpatched or baredebian*.
+
+.B always
+splits the view regardless of the source format and the quilt mode.
+
+.B never
+will cause dgit to fail if split view is needed.
+
+When split view is in operation, the dgit view is visible
+in your local git clone,
+but only in refs specific to dgit:
+notably
+.BI remotes/dgit/dgit/ suite
+and
+.BR archive/ \fIdistro\fR / \fIversion\fR.
+
+Note that split view does not affect dgit fetch,
+and is not compatible with dgit pull.
+.TP
+.BI \-C changesfile
Specifies the .changes file which is to be uploaded. By default
-dgit push looks for single .changes file in the parent directory whose
+dgit push looks for a single .changes file in the parent directory whose
filename suggests it is for the right package and version.
If the specified
.I changesfile
pathname contains slashes, the directory part is also used as
the value for
-.BR --build-products-dir ;
+.BR \-\-build-products-dir ;
otherwise, the changes file is expected in that directory (by
default, in
.BR .. ).
.TP
-.B --rm-old-changes
+.BI \-\-upstream-commitish= upstream
+For use with --quilt=baredebian only.
+Specifies the commit containing the upstream source.
+This commit must be identical to your .orig tarball.
+The default is to look for one of the git tags
+.IB U " v" U " upstream/" U
+(in that order), where U is the upstream version.
+.TP
+.B \-\-rm-old-changes
When doing a build, delete any changes files matching
.IB package _ version _*.changes
before starting. This ensures that
-dgit push (and dgit sbuild) will be able to unambigously
+dgit push (and dgit sbuild) will be able to unambiguously
identify the relevant changes files from the most recent build, even
if there have been previous builds with different tools or options.
The default is not to remove, but
.B \-\-no-rm-old-changes
can be used to override a previous \-\-rm-old-changes
or the .rm-old-changes configuration setting.
+
+Note that \fBdgit push-source\fR will always find the right .changes,
+regardless of this option.
.TP
-.BI --build-products-dir= directory
-Specifies where to find the built files to be uploaded.
-By default, dgit looks in the parent directory
+.BI \-\-build-products-dir= directory
+Specifies where to find and create tarballs, binary packages,
+source packages, .changes files, and so on.
+
+By default, dgit uses the parent directory
.RB ( .. ).
+
+Changing this setting may necessitate
+moving .orig tarballs to the new directory,
+so it is probably best to
+use the
+.BI dgit.default.build-products-dir
+configuration setting
+(see CONFIGURATION, below)
+which this command line option overrides).
.TP
.BI --no-rm-on-error
Do not delete the destination directory if clone fails.
Generates a DEP-14 tag (eg
.BR debian/ \fIversion\fR)
as well as a dgit tag (eg
-.BR archive/debian/ \fIversion\fR)
-where possible. This is the default.
+.BR archive/debian/ \fIversion\fR).
+This is the default.
.TP
.BI --no-dep14tag
-Do not generate a DEP-14 tag, except in split quilt view mode.
-(On servers where only the old tag format is supported,
-the dgit tag will have the DEP-14 name.
-This option does not prevent that.)
+Do not generate a DEP-14 tag, except when split view is in operation.
.TP
-.BI --dep14tag-always
-Insist on generating a DEP-14 tag
-as well as a dgit tag.
-If the server does not support that, dgit push will fail.
+.BI --always-dep14tag
+Obsolete alias for --dep14tag, retained for compatibility.
.TP
.BI -D
Prints debugging information to stderr. Repeating the option produces
.BR dpkg-buildpackage ,
.BR dpkg-genchanges ,
.BR sbuild ,
+.BR pbuilder ,
+.BR cowbuilder ,
.BR ssh ,
.BR dgit ,
+.BR git-debrebase ,
.BR apt-get ,
.BR apt-cache ,
.BR gbp-pq ,
For dpkg-buildpackage, dpkg-genchanges, mergechanges and sbuild,
the option applies only when the program is invoked directly by dgit.
Usually, for passing options to dpkg-genchanges, you should use
-.BR --ch: \fIoption\fR.
+.BR \-\-ch: \fIoption\fR.
-Specifying --git is not effective for some lower-level read-only git
+Specifying \-\-git is not effective for some lower-level read-only git
operations performed by dgit, and also not when git is invoked by
another program run by dgit.
See notes below regarding ssh and dgit.
-NB that --gpg:option is not supported (because debsign does not
+NB that \-\-gpg:option is not supported (because debsign does not
have that facility).
But see
-.B -k
+.B \-k
and the
.B keyid
distro config setting.
.TP
-.RI \fB--curl=\fR program " | \fB--dput=\fR" program " |..."
+.RI \fB\-\-curl!:\fR option " | \fB\-\-dput!:\fR" option " |..."
+Specifies an option to remove from the command line for
+a program called by dgit, as for
+\fB\-\-\fR\fIprogram\fI\fB:\fR\fIoption\fR
+(and the same caveats apply).
+
+Any options or arguments exactly identical to
+.I option
+are removed.
+(It is not an error if there were none.)
+
+This can only be used to delete options
+which are always passed by default by dgit,
+or to undo a previous
+\fB\-\-\fR\fIprogram\fI\fB:\fR\fIoption\fR.
+It cannot be used to override option(s) dynamically
+decided on by dgit.
+.TP
+.RI \fB\-\-curl=\fR program " | \fB\-\-dput=\fR" program " |..."
Specifies alternative programs to use instead of
.BR curl ,
.BR dput ,
.BR dpkg-buildpackage ,
.BR dpkg-genchanges ,
.BR sbuild ,
+.BR pbuilder ,
+.BR cowbuilder ,
.BR gpg ,
.BR ssh ,
.BR dgit ,
+.BR git-debrebase ,
.BR apt-get ,
.BR apt-cache ,
.BR git ,
.BR dgit ,
specifies the command to run on the remote host when dgit
rpush needs to invoke a remote copy of itself. (dgit also reinvokes
-itself as the EDITOR for dpkg-source --commit; this is done using
-argv[0], and is not affected by --dgit=).
+itself as the EDITOR for dpkg-source \-\-commit; this is done using
+argv[0], and is not affected by \-\-dgit=).
.BR gbp-build 's
value
unusually, the specified value is split on whitespace
to produce a command and possibly some options and/or arguments.
+For pbuilder and cowbuilder, the defaults are
+.BR "sudo -E pbuilder"
+and
+.BR "sudo -E cowbuilder"
+respectively.
+Like with gbp-build and gbp pq,
+the specified value is split on whitespace.
+
For
.BR ssh ,
the default value is taken from the
.BI dgit-distro. distro .ssh
and
.B .dgit.default.ssh
-(which can in turn be overridden with -c). Also, when dgit is using
+(which can in turn be overridden with \-c). Also, when dgit is using
git to access dgit-repos, only git's idea of what ssh to use (eg,
.BR GIT_SSH )
is relevant.
.TP
-.BI --existing-package= package
+.BI \-\-existing-package= package
dgit push needs to canonicalise the suite name. Sometimes, dgit
lacks a way to ask the archive to do this without knowing the
-name of an existing package. Without --new we can just use the
-package we are trying to push. But with --new that will not work, so
+name of an existing package. Without \-\-new we can just use the
+package we are trying to push. But with \-\-new that will not work, so
we guess
.B dpkg
or use the value of this option. This option is not needed with the
default mechanisms for accessing the archive.
.TP
-.BR -h | --help
+.BR \-h | \-\-help
Print a usage summary.
.TP
-.BI --initiator-tempdir= directory
+.BI \-\-initiator-tempdir= directory
dgit rpush uses a temporary directory on the invoking (signing) host.
This option causes dgit to use
.I directory
after dgit finishes. The directory specified must be an absolute
pathname.
.TP
-.BI --force- something
+.BI \-\-force- something
Instructs dgit to try to proceed despite detecting
what it thinks is going to be a fatal problem.
.B This is probably not going to work.
in case dgit is confused.
(They might also be useful for testing error cases.)
.TP
-.B --force-import-dsc-with-dgit-field
+.B \-\-force-import-dsc-with-dgit-field
Tell dgit import-dsc to treat a .dsc with a Dgit field
like one without it.
The result is a fresh import,
discarding the git history
that the person who pushed that .dsc was working with.
.TP
-.B --force-unrepresentable
+.B \-\-force-reusing-version
+Carry on even though this involves reusing a version number
+of a previous push or upload.
+It is normally best to give different versions different numbers.
+Some servers (including, usually, the Debian server)
+will reject attempts to reuse or replace already-pushed versions.
+.TP
+.B \-\-force-uploading-binaries
+Carry on and
+upload binaries
+even though dgit thinks your distro does not permit that.
+.TP
+.B \-\-force-uploading-source-only
+Carry on and do a source-only upload,
+without any binaries,
+even though dgit thinks your distro does not permit that,
+or does not permit that in this situation.
+.TP
+.B \-\-force-unrepresentable
Carry on even if
dgit thinks that your git tree contains changes
(relative to your .orig tarballs)
which dpkg-source is not able to represent.
Your build or push will probably fail later.
.TP
-.B --force-changes-origs-exactly
+.B \-\-force-changes-origs-exactly
Use the set of .origs specified in your .changes, exactly,
without regard to what is in the archive already.
The archive may well reject your upload.
.TP
-.B --force-unsupported-source-format
+.B \-\-force-unsupported-source-format
Carry on despite dgit not understanding your source package format.
dgit will probably mishandle it.
.TP
-.B --force-dsc-changes-mismatch
+.B \-\-force-dsc-changes-mismatch
Do not check whether .dsc and .changes match.
The archive will probably reject your upload.
.TP
-.BR --force-import-gitapply-absurd " | " --force-import-gitapply-no-absurd
+.BR \-\-force-import-gitapply-absurd " | " \-\-force-import-gitapply-no-absurd
Force on or off the use of the absurd git-apply emulation
when running gbp pq import
when importing a package from a .dsc.
See Debian bug #841867.
+.TP
+.BR \-\-for\-push
+Override the dgit-distro.distro.readonly configuration setting,
+to specify that we have read/write access
+and should use the corresponding git and achieve access approach
+even if the operation is a read-only one.
.SH CONFIGURATION
dgit can be configured via the git config system.
You may set keys with git-config (either in system-global or per-tree
.LP
Settings likely to be useful for an end user include:
.TP
+.BI dgit.default.build-products-dir
+Specifies where to find the built files to be uploaded,
+when --build-products-dir is not specified. The default is
+the parent directory
+.RB ( .. ).
+.TP
.BR dgit-suite. \fIsuite\fR .distro " \fIdistro\fR"
Specifies the distro for a suite. dgit keys off the suite name (which
appears in changelogs etc.), and uses that to determine the distro
.TP
.BI dgit.default.distro " distro"
The default distro for an unknown suite.
+
+This is only used if no
+.BI /usr/share/distro-info/ somedistro .csv
+mentions the specified suite.
.TP
.BI dgit.default.default-suite " suite"
The default suite (eg for clone).
the default value used if there is no distro-specific setting.
.TP
.BR dgit-distro. \fIdistro\fR .clean-mode
-One of the values for the command line --clean= option; used if
---clean is not specified.
+One of the values for the command line \-\-clean= option; used if
+\-\-clean is not specified.
+.TP
+.BR dgit-distro. \fIdistro\fR .clean-mode-newer
+Like .clean-mode,
+but ignored if the value is unknown to this version of dgit.
+Setting both .clean-mode and .clean-mode-newer is useful
+to provide a single git config compatible with different dgit versions.
.TP
.BR dgit-distro. \fIdistro\fR .quilt-mode
-One of the values for the command line --quilt= option; used if
---quilt is not specified.
+One of the values for the command line \-\-quilt= option; used if
+\-\-quilt is not specified.
+.TP
+.BR dgit-distro. \fIdistro\fR .split-view
.TP
.BR dgit-distro. \fIdistro\fR .rm-old-changes
Boolean, used if neither \-\-rm-old-changes nor \-\-no-rm-old-changes
.TP
.BI dgit-distro. distro .keyid
See also
-.BR -k .
+.BR \-k .
.TP
.BI dgit-distro. distro .mirror " url"
.TP
.TP
.BI dgit-distro. distro .setup-useremail
Whether to set user.name and user.email in new git trees.
-True by default. Ignored for dgit setup-setup-useremail, which does it anyway.
+True by default. Ignored for dgit setup-useremail, which does it anyway.
.TP
.BI dgit-distro. distro .setup-mergechangelogs
-Whether to setup a merge driver which uses dpkg-mergechangelogs for
+Whether to set up a merge driver which uses dpkg-mergechangelogs for
debian/changelog. True by default. Ignored for dgit
setup-mergechangelogs, which does it anyway.
.TP
Program to use instead of
.IR cmd .
Works like
-.BR -- \fIcmd\fR = "... ."
+.BR \-\- \fIcmd\fR = "... ."
.TP
.BI dgit-distro. distro .opts- cmd
Extra options to pass to
.IR cmd .
Works like
-.BR -- \fIcmd\fR : "... ."
+.BR \-\- \fIcmd\fR : "... ."
To pass several options, configure multiple values in git config
-(with git config --add). The options for
+(with git config \-\-add). The options for
.BI dgit.default.opts- cmd
+and
.BI dgit-distro. distro /push.opts- cmd
-and are all used, followed by options from dgit's command line.
+are all used, followed by options from dgit's command line.
.SH ACCESS CONFIGURATION
There are many other settings which specify how a particular distro's
services (archive and git) are provided. These should not normally be
.TP
.BI dgit-distro. distro .git-create " " ssh-cmd | true
.TP
-.BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR
+.BR dgit-distro. \fIdistro\fR .archive-query " " ftpmasterapi: " | " madison: "\fIdistro\fR | " dummycat: "\fI/path\fR | " sshpsql: \fIuser\fR @ \fIhost\fR : \fIdbname\fR " " | " aptget:"
.TP
.BR dgit-distro. \fIdistro\fR .archive-query- ( url | tls-key | curl-ca-args )
.TP
.TP
.BI dgit-distro. distro .dgit-tag-format
.TP
-.BR dgit-distro. \fIdistro\fR .dep14tag " " want | no | always
+.BR dgit-distro. \fIdistro\fR .dep14tag " " want | no [| always ]
.TP
.BI dgit-distro. distro .ssh
.TP
.TP
.BI dgit-distro. distro .rewrite-map-enable
.TP
+.BR dgit-distro. \fIdistro\fR .source-only-uploads " " ok | always | never | not-wholly-new
+.TP
.BI dgit.default.old-dsc-distro
.TP
.BI dgit.dsc-url-proto-ok. protocol
.BI dgit.dsc-url-proto-ok.bad-syntax
.TP
.BI dgit.default.dsc-url-proto-ok
+.TP
+.BR dgit.vcs-git.suites " \fIsuite\fR[" ; ...]
.SH ENVIRONMENT VARIABLES
.TP
.BR DGIT_SSH ", " GIT_SSH
specifies just the program; no arguments can be specified, so dgit
interprets it the same way as git does.
See
-also the --ssh= and --ssh: options.
+also the \-\-ssh= and \-\-ssh: options.
.TP
.BR DEBEMAIL ", " DEBFULLNAME
Default git user.email and user.name for new trees. See
.BR "dgit setup-new-tree" .
.TP
-.BR gpg ", " dpkg- "..., " debsign ", " git ", " curl ", " dput ", " LWP::UserAgent
+.BR gpg ", " dpkg- "..., " debsign ", " git ", [" lib ] curl ", " dput
and other subprograms and modules used by dgit are affected by various
-environment variables. Consult the documentaton for those programs
+environment variables. Consult the documentation for those programs
for details.
.SH BUGS
There should be
(quilt)' source format. This is ultimately due to what I consider
design problems in quilt and dpkg-source.
---dry-run does not always work properly, as not doing some of the git
+\-\-dry-run does not always work properly, as not doing some of the git
fetches may result in subsequent actions being different. Doing a
non-dry-run dgit fetch first will help.
---damp-run is likely to work much better.
+\-\-damp-run is likely to work much better.
.SH SEE ALSO
\fBdgit\fP(7),
\fBdgit-*\fP(7),
~ianmdlvl / dgit.git / blobdiff