.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] \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
.I suite
belongs.
+.I suite
+may be a combination of several underlying suites in the form
+.IR mainsuite \fB,\fR subsuite ...;
+see COMBINED SUITES in dgit(7).
+
For your convenience, the
.B vcs-git
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
.IR suite ;
otherwise it parses debian/changelog and uses the suite specified
there.
+suite may be a combined suite, as for clone.
.TP
\fBdgit pull\fR [\fIsuite\fP]
Does dgit fetch, and then merges the new head of the remote tracking
.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 aceess 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 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
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
passed on to sbuild.
The output is left in
.IR package \fB_\fR version \fB_multi.changes\fR.
-
+.IP
+Note that by default
+sbuild does not build arch-independent packages.
+You probably want to pass -A, to request those.
+.IP
Tagging, signing and actually uploading should be left to dgit push.
.TP
\fBdgit gbp-build\fR ...
debian/changelog and the .dsc, which must agree. If the command line
specifies a suite then that must match too.
-If dgit push fails while uploading, it is fine to simply retry the
-dput on the .changes file at your leisure.
+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.
invoking host. This allows you to do a push when the system which has
the source code and the build outputs has no access to the key:
+.TS
+l l.
1. Clone on build host (dgit clone)
-.br
2. Edit code on build host (edit, git commit)
-.br
3. Build package on build host (dgit build)
-.br
4. Test package on build host or elsewhere (dpkg -i, test)
-.br
5. Upload by invoking dgit rpush on host with your GPG key.
+.TE
However, the build-host must be able to ssh to the dgit repos. If
this is not already the case, you must organise it separately, for
.B dgit setup-new-tree
Configure the current working tree the way that dgit clone would have
set it up. Like running
-.B dgit setup-useremail
-and
+.BR "dgit setup-useremail" ,
.B setup-mergechangelogs
+and
+.B setup-gitattributes
(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
which uses
.BR dpkg-mergechangelogs .
.TP
+.B dgit setup-gitattributes
+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
+and applying it to
+.BR * .
+For why, see
+.B GITATTRIBUTES
+in
+.BR dgit(7) .
+
+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,
+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
+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
+and hence
+dgit setup-new-tree.)
+.TP
.B dgit quilt-fixup
`3.0 (quilt)' format source packages need changes representing not
only in-tree but also as patches in debian/patches. dgit quilt-fixup
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,
make a pseudomerge to bind the import
into any existing git history.
+Because a .dsc can contain a Dgit field naming a git commit
+(which you might not have),
+and specifying where to find that commit
+(and any history rewrite table),
+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.
+
There is only only sub-option:
.B --require-valid-signature
If
.I branch
does not start with refs/, refs/heads/ is prepended.
-The specified branch is unconditionally updated.
-
-If the specified .dsc contains a Dgit field,
-dgit will simply make a branch of that commit.
-If you cannot manage to find that commit anywhere,
-consider --force-import-dsc-with-dgit-field.
.TP
.B dgit version
Prints version information and exits.
.BI "dgit clone-dgit-repos-server" " destdir"
Tries to fetch a copy of the source code for the dgit-repos-server,
as actually being used on the dgit git server, as a git tree.
+.TP
+.BI "dgit print-dgit-repos-server-source-url"
+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 diredcory
+and nothing else.
+The separate arguments are unquoted, separated by spaces,
+and do not contain spaces.
.SH OPTIONS
.TP
.BR --dry-run " | " -n
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.)
.TP
-.BR --overwrite =\fIprevious-version\fR
-Declare that even though your git branch is not a descendant
+.BR --overwrite [=\fIprevious-version\fR]
+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.
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.
-.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.
to update the contents of dgit-repos
to a version without the controversial changes.
.TP
+.BR --no-chase-dsc-distro
+Tells dgit not to look online
+for additional git repositories
+containing information about a particular .dsc being imported.
+Chasing is the default.
+
+For most operations
+(such as fetch and pull),
+disabling chasing
+means dgit will access only the git server
+for the distro you are directly working with,
+even if the .dsc was copied verbatim from another distro.
+For import-dsc,
+disabling chasing
+means dgit will work completely offline.
+
+Disabling chasing can be hazardous:
+if the .dsc names a git commit which has been rewritten
+by those in charge of the distro,
+this option may prevent that rewrite from being effective.
+Also,
+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,
and dgit calculates
Debian, use this 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.
+
+In split view quilt modes,
+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
.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.
.BI --no-rm-on-error
Do not delete the destination directory if clone fails.
.TP
+.BI --dep14tag
+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.
+.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.)
+.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.
+.TP
.BI -D
Prints debugging information to stderr. Repeating the option produces
more output (currently, up to -DDDD is meaningfully different).
.BR sbuild ,
.BR ssh ,
.BR dgit ,
+.BR git-debrebase ,
.BR apt-get ,
.BR apt-cache ,
.BR gbp-pq ,
.BR gpg ,
.BR ssh ,
.BR dgit ,
+.BR git-debrebase ,
.BR apt-get ,
.BR apt-cache ,
.BR git ,
in case dgit is confused.
(They might also be useful for testing error cases.)
.TP
-.B --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-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
.BI dgit.default.distro " distro"
The default distro for an unknown suite.
.TP
+.BI dgit.default.default-suite " suite"
+The default suite (eg for clone).
+.TP
.BR dgit.default. *
for each
.BR dgit-distro. \fIdistro\fR . *,
debian/changelog. True by default. Ignored for dgit
setup-mergechangelogs, which does it anyway.
.TP
+.BI dgit-distro. distro .setup-gitattributes
+Whether to configure .git/info/attributes
+to suppress checkin/checkout file content transformations
+in new git trees.
+True by default. Ignored for dgit setup-gitattributes, which does it anyway.
+.TP
.BI dgit-distro. distro .cmd- cmd
Program to use instead of
.IR cmd .
adjusted, but are documented for the benefit of distros who wish to
adopt dgit.
.TP
+.BI dgit-distro. distro .nominal-distro
+Shown in git tags, Dgit fields, and so on.
+.TP
+.BI dgit-distro. distro .alias-canon
+Used for all access configuration lookup.
+.TP
.BR dgit-distro. \fIdistro\fR /push. *
If set, overrides corresponding non \fB/push\fR config when
.BR readonly=false ,
.TP
.BI dgit-distro. distro .dgit-tag-format
.TP
+.BR dgit-distro. \fIdistro\fR .dep14tag " " want | no | always
+.TP
.BI dgit-distro. distro .ssh
.TP
.BI dgit-distro. distro .sshpsql-dbname
.BR dgit-distro. \fIdistro\fR . ( git | sshpsql ) - ( user | host | user-force )
.TP
.BI dgit-distro. distro .backports-quirk
+.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
+.TP
+.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
~ianmdlvl / dgit.git / blobdiff