+'\" t
.TH dgit 1 "" "Debian Project" "dgit"
.SH NAME
dgit \- git integration with the Debian archive
.SH DESCRIPTION
.B dgit
allows you to treat the Debian archive as if it were a git
-repository. See \fBdgit\fP(7) for detailed information about the data
-model, common problems likely to arise with certain kinds of package,
+repository.
+
+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/DMs: doing a straightforward NMU
+dgit-maint-native(7) for maintainers of Debian-native packages
+dgit-maint-merge(7) for maintainers: using a merging git workflow
+dgit-maint-gbp(7) for maintainers: using git-buildpackage
+dgit-sponsorship(7) for sponsors and sponsored contributors
+.TE
+.LP
+See \fBdgit(7)\fP for detailed information about the data
+model,
+common problems likely to arise with certain kinds of package,
etc.
-
-The usual workflow is:
-.br
-1. \fBdgit clone\fR or \fBfetch\fR;
-.br
-2. make, do dev tests, and commit changes in git as desired;
-.br
-3. build packages for upload, using e.g. \fBdgit sbuild\fR
-.br
-4. do pre-upload tests of the proposed upload;
-.br
-5. \fBdgit push\fR.
.SH OPERATIONS
.TP
\fBdgit clone\fR \fIpackage\fP [\fIsuite\fP] [\fB./\fP\fIdir|\fB/\fP\fIdir\fR]
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 meanings of
+which relate to distro-specific policies.
+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.
+The meanings of
.IR something s
understood in the context of Debian are discussed below:
.TP
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
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.
-.B --quilt=gbp
+.B --gbp
+(short for
+.BR --quilt=gbp )
is for use with git-buildpackage.
Your HEAD is expected to be
a patches-unapplied git branch, except that it might contain changes
to upstream .gitignore files. This is the default for dgit gbp-build.
-.B --quilt=dpm
+.B --dpm
+(short for
+.BR --quilt=dpm )
is for use with git-dpm.
Your HEAD is expected to be
a patches-applied git branch,
and you aren't too lucky, dgit will notice the problem and stop,
with a useful hint.
.TP
+.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
+.BR dgit-suite. \fIsuite\fR .distro .
+The only effect is that other configuration variables (used
+for accessing the archive and dgit-repos) used are
+.BR dgit-distro. \fIdistro\fR .* .
+
+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
+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
+for fetching (and, for dgit push, altering) a variety of information both
+in the archive and in dgit-repos.
+How to set this up is not yet documented.
+.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
+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 ;
+otherwise, the changes file is expected in that directory (by
+default, in
+.BR .. ).
+.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
+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.
+.TP
+.BI --build-products-dir= directory
+Specifies where to find the built files to be uploaded.
+By default, dgit looks in the parent directory
+.RB ( .. ).
+.TP
+.BI --no-rm-on-error
+Do not delete the destination directory if clone fails.
+.TP
.BI -D
Prints debugging information to stderr. Repeating the option produces
more output (currently, up to -DDDD is meaningfully different).
.BR GIT_SSH )
is relevant.
.TP
-.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
-.BR dgit-suite. \fIsuite\fR .distro .
-The only effect is that other configuration variables (used
-for accessing the archive and dgit-repos) used are
-.BR dgit-distro. \fIdistro\fR .* .
-
-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
-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
-for fetching (and, for dgit push, altering) a variety of information both
-in the archive and in dgit-repos.
-How to set this up is not yet documented.
-.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
-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 ;
-otherwise, the changes file is expected in that directory (by
-default, in
-.BR .. ).
-.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
-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.
-.TP
-.BI --build-products-dir= directory
-Specifies where to find the built files to be uploaded.
-By default, dgit looks in the parent directory
-.RB ( .. ).
-.TP
.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
after dgit finishes. The directory specified must be an absolute
pathname.
.TP
-.BI --no-rm-on-error
-Do not delete the destination directory if clone fails.
-.SH WORKFLOW - SIMPLE
-It is always possible with dgit to clone or fetch a package, make
-changes in git (using git-commit) on the suite branch
-.RB ( "git checkout dgit/" \fIsuite\fR)
-and then dgit push. You can use whatever gitish techniques you like
-to construct the commits to push;
-the only requirement is that what you push is a
-descendant of the state of the archive, as provided by dgit in the
-remote tracking branch
-.BR remotes/dgit/dgit/ \fIsuite\fR.
-
-If you are using dgit to do an NMU (in Debian),
-and don't know about the
-maintainers' preferred packaging workflows, you should make your
-changes as a linear series of (logicially separated) commits on top of
-what's already in the archive.
-
-If you are lucky the other uploaders have also used dgit and
-integrated the other relevant git history; if not you can fetch it
-into your tree and cherry-pick etc. as you wish.
-.SH WORKFLOW - INTEGRATING BETWEEN DGIT AND OTHER GIT HISTORY
-If you are the maintainer of a package dealing with uploads made
-without dgit, you will probably want to merge the synthetic commits
-(made by dgit to represent the uploads) into your git history.
-Normally you can just merge the dgit branch into your own master, or
-indeed if you do your work on the dgit local suite branch
-.BI dgit/ suite
-you can just use dgit pull.
-
-However the first time dgit is used it will generate a new origin
-commit from the archive which won't be linked into the rest of your
-git history. You will need to merge this.
-
-If last upload was in fact made with git, you should usually proceed
-as follows: identify the commit which was actually used to build the
-package. (Hopefully you have a tag for this.) Check out the dgit
-branch
-.RB ( "git checkout dgit/" \fIsuite\fR)
-and merge that other commit
-.RB ( "git merge debian/" \fIversion\fR).
-Hopefully this merge will be trivial because the two trees should
-be very similar. The resulting branch head can be merged into your
-working branches
-.RB ( "git checkout master && git merge dgit/" \fIsuite\fR).
-
-If last upload was not made with git, a different approach is required
-to start using dgit. First, do
-.B dgit fetch
-(or clone) to obtain a git history representation of what's in the
-archive and record it in the
-.BI remotes/dgit/dgit/ suite
-tracking branch. Then somehow, using your other git history
-plus appropriate diffs and cherry picks from the dgit remote tracking
-branch, construct a git commit whose tree corresponds to the tree to use for the
-next upload.
-
-between what's in the archive and what you intend to upload.
-Then run
-.BR "dgit push"
-to actually upload the result.
-
-If the commit-to-be-uploaded is not a descendant of the
-dgit remote tracking branch, you will need to pass
-.B --overwrite
-to dgit.
+.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.
+These options are provided as an escape hatch,
+in case dgit is confused.
+(They might also be useful for testing error cases.)
+.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-unsupported-source-format
+Carry on despite dgit not understanding your source package format.
+dgit will probably mishandle it.
+.TP
+.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
+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.
.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
environment variables. Consult the documentaton for those programs
for details.
.SH BUGS
-dgit's git representation of format `3.0 (quilt)' source packages does
-not represent the patch stack as git commits. Currently the patch
-series representation cannot round trip between git and the archive.
-Ideally dgit would represent a quilty package with an origin commit of
-some kind followed by the patch stack as a series of commits followed
-by a pseudo-merge (to make the branch fast-forwarding). This would
-also mean a new `dgit rebase-prep' command or some such to turn such a
-fast-forwarding branch back into a rebasing patch stack, and a `force'
-option to dgit push (perhaps enabled automatically by a note left by
-rebase-prep) which will make the required pseudo-merge.
-
-If the dgit push fails halfway through, it should be restartable and
-idempotent. However this is not true for the git tag operation.
-Also, it would be good to check that the proposed signing key is
+There should be
+a `dgit rebase-prep' command or some such to turn a
+fast-forwarding branch containing pseudo-merges
+back into a rebasing patch stack.
+It might have to leave a note
+for a future dgit push.
+
+If the dgit push fails halfway through,
+it is not necessarily restartable and
+idempotent.
+It would be good to check that the proposed signing key is
available before starting work.
-dgit's handling of .orig.tar.gz is not very sophisticated. Ideally
-the .orig.tar.gz could be transported via the git repo as git tags.
-Doing this is made more complicated by the possibility of a `3.0
-(quilt)' package with multiple .orig tarballs.
-
-dgit's build functions, and dgit push, should not make any changes to
+dgit's build functions, and dgit push, may make changes to
your current HEAD. Sadly this is necessary for packages in the `3.0
(quilt)' source format. This is ultimately due to what I consider
design problems in quilt and dpkg-source.
-There should be an option which arranges for the `3.0 (quilt)'
-autocommit(s) to not appear on your HEAD, but instead only in the
-remote tracking suite branch.
-
--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.
.SH SEE ALSO
\fBdgit\fP(7),
-\fBdgit-maint-merge\fP(7),
+\fBdgit-*\fP(7),
\fBcurl\fP(1),
\fBdput\fP(1),
\fBdebsign\fP(1),