From f96da1c7befb3fc02c684739e249d35a6d7dfe0a Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Thu, 29 Aug 2013 00:11:09 +0100 Subject: New manpage section on FILES IN THE SOURCE PACKAGE BUT NOT IN GIT. Closes: #721186. --- dgit.1 | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) (limited to 'dgit.1') 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 -- cgit v1.2.3