2 files changed, 47 insertions, 0 deletions
diff --git a/debian/changelog b/debian/changelog
index c179505..b318f0f 100644
@@ -15,6 +15,8 @@ dgit (0.13) unstable; urgency=low
* 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.
@@ -439,6 +439,51 @@ You can explicitly request that dgit do just this fixup, by running
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:
+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.
+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.
+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.
+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
+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.
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