Tagging, signing and actually uploading should be left to dgit push.
.TP
+.B dgit help
+Print a usage summary.
+.TP
\fBdgit sbuild\fR ...
Constructs the source package, uses
.B sbuild
Tagging, signing and actually uploading should be left to dgit push.
.TP
-.B dgit push
+\fBdgit push\fR [\fIsuite\fP]
Does an `upload', pushing the current HEAD to the archive (as a source
package) and to dgit-repos (as git commits). The package must already
have been built ready for upload, with the .dsc and .changes
archive.
dgit push always uses the package, suite and version specified in the
-debian/changelog and the .dsc, which must agree.
+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.
make a commit of the changes it has made.
This is normally done automatically by dgit build and dgit push.
+.TP
+.B dgit version
+Prints version information and exits.
.SH OPTIONS
.TP
.BR --dry-run | -n
dgit quilt-fixup.
We recommend against the use of `3.0 (quilt)'.
+.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT
+This section is mainly of interest to maintainers who want to use dgit
+with their existing git history for the Debian package.
+
+Some developers like to have an extra-clean git tree which lacks files
+which are normally found in source tarballs and therefore in Debian
+source packages. For example, it is conventional to ship ./configure
+in the source tarball, but some people prefer not to have it present
+in the git view of their project.
+
+dgit requires that the source package unpacks to exactly the same
+files as are in the git commit on which dgit push operates. So if you
+just try to dgit push directly from one of these extra-clean git
+branches, it will fail.
+
+As the maintainer you therefore have the following options:
+.TP
+\(bu
+Persuade upstream that the source code in their git history and the
+source they ship as tarballs should be identical. Of course simply
+removing the files from the tarball may make the tarball hard for
+people to use.
+.IP
+One answer is to commit the (maybe autogenerated)
+files, perhaps with some simple automation to deal with conflicts and
+spurious changes. This has the advantage that someone who clones
+the git repository finds the program just as easy to build as someone
+who uses the tarball.
+.TP
+\(bu
+Have separate git branches which do contain the extra files, and after
+regenerating the extra files (whenever you would have to anyway),
+commit the result onto those branches.
+.TP
+\(bu
+Provide source packages which lack the files you don't want
+in git, and arrange for your package build to create them as needed.
+This may mean not using upstream source tarballs and makes the Debian
+source package less useful for people without Debian build
+infrastructure.
+.LP
+Of course it may also be that the differences are due to build system
+bugs, which cause unintended files to end up in the source package.
+dgit will notice this and complain. You may have to fix these bugs
+before you can unify your existing git history with dgit's.
.SH CONFIGURATION
dgit looks at the following git config keys to control its behaviour.
You may set them with git-config (either in system-global or per-tree