New manpage section on FILES IN THE SOURCE PACKAGE BUT NOT IN GIT. Closes: #721186.

diff --git a/debian/changelog b/debian/changelog
index c1795058831106f3f1ec61c5ca68b153ba3c0322..b318f0f0d859b3c1b47ee242cbb8ca851e204c9f 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -15,6 +15,8 @@ dgit (0.13) unstable; urgency=low
     Closes: #720956.
   * Fix references in manpage to old Vcs-Dgit-Master field name.
   * Reorganise manpage sections to be in a more conventional order.
+  * New manpage section on FILES IN THE SOURCE PACKAGE BUT NOT IN GIT.
+    Closes: #721186.
 
  --
 

diff --git a/dgit.1 b/dgit.1
index d2b2b7cb94f9bcf3ef2c18840158c44d0eaf2f5b..5c5a55e34c7732749ba168637a2a3269ed61b54a 100644 (file)
--- a/dgit.1
+++ b/dgit.1
@@ -439,6 +439,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