summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorIan Jackson <ijackson@chiark.greenend.org.uk>2013-08-29 00:11:09 +0100
committerIan Jackson <ijackson@chiark.greenend.org.uk>2013-08-29 00:11:09 +0100
commitf96da1c7befb3fc02c684739e249d35a6d7dfe0a (patch)
treef51bd45f3379f3fd52aff957ebb09db387d630c1
parentcac7ba06fef058f47ad6dd3b1670a5332420b4e2 (diff)
New manpage section on FILES IN THE SOURCE PACKAGE BUT NOT IN GIT. Closes: #721186.
-rw-r--r--debian/changelog2
-rw-r--r--dgit.145
2 files changed, 47 insertions, 0 deletions
diff --git a/debian/changelog b/debian/changelog
index c179505..b318f0f 100644
--- 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 d2b2b7c..5c5a55e 100644
--- 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