do substition for $dgit_version in rules

[dgit.git] / dgit.1

diff --git a/dgit.1 b/dgit.1
index d2b2b7cb94f9bcf3ef2c18840158c44d0eaf2f5b..251af593181580eb1d818bf6f74bb9f830bbbdae 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -102,6 +102,9 @@ and
 
 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
@@ -148,6 +151,9 @@ by making a new debian/ patch containing your unquilty changes) and
 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
@@ -439,6 +445,51 @@ You can explicitly request that dgit do just this fixup, by running
 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