X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.7;h=c3e581853701e1b820d53cdb8be3f52b511cd04b;hp=584632cb24d8a3075b36d8a008cf6711fcb53ca9;hb=8ac258a499a5d034684d47c6144be82b87535c24;hpb=302a82c5e9e200fe93befefbdeb2b9ccfac00239

diff --git a/dgit.7 b/dgit.7
index 584632cb..c3e58185 100644
--- a/dgit.7
+++ b/dgit.7
@@ -58,9 +58,10 @@ Uploads made by dgit contain an additional field
 in the source package .dsc.  (This is added by dgit push.)
 This specifies: a commit (an ancestor of the dgit/suite
 branch) whose tree is identical to the unpacked source upload;
-and the distro and suite to which the upload was made
-(and a url,
-in case the client seeing this .dsc does not know of that distro).
+the distro to which the upload was made;
+a tag name which can be used to fetch the git commits;
+and
+a url to use as a hint for the dgit git server for that distro.
 
 Uploads not made by dgit are represented in git by commits which are
 synthesised by dgit.  The tree of each such commit corresponds to the
@@ -200,6 +201,26 @@ or previous non-Dgit uploads
 Distros which do not maintain a set of dgit history git repositories
 can still be used in a read-only mode with dgit.  Currently Ubuntu
 is configured this way.
+.SH GITATTRIBUTES
+git has features which can automatically transform files
+as they are being copied between the working tree
+and the git history.
+See \fBgitattributes\fP(5).
+
+These transformations are context-sensitive
+and not, in general, reversible,
+so dgit operates on the principle that
+the dgit git history contains the actual contents of the package.
+(When dgit is manipulating a .dsc,
+it does so in a private area,
+where the transforming gitattributes are defused (disabled),
+to achieve this.)
+
+If transforming gitattributes used,
+they can cause trouble,
+because the working tree files can differ from
+the git revision history
+(and therefore from the source packages).
 .SH PACKAGE SOURCE FORMATS
 If you are not the maintainer, you do not need to worry about the
 source format of the package.  You can just make changes as you like
@@ -263,7 +284,7 @@ is a patches-applied or patches-unapplied tree.
 Split view conversions are cached in the ref
 dgit-intern/quilt-cache.
 This should not be manipulated directly.
-.SH FILES IN THE SOURCE PACKAGE BUT NOT IN GIT - AUTOTOOLS ETC.
+.SH FILES IN THE ORIG TARBALL BUT NOT IN GIT - AUTOTOOLS ETC.
 This section is mainly of interest to maintainers who want to use dgit
 with their existing git history for the Debian package.
 
@@ -281,6 +302,17 @@ branches, it will fail.
 As the maintainer you therefore have the following options:
 .TP
 \(bu
+Delete the files from your git branches,
+and your Debian source packages,
+and carry the deletion as a delta from upstream.
+(With `3.0 (quilt)' this means represeting the deletions as patches.
+You may need to pass --include-removal to dpkg-source --commit,
+or pass corresponding options to other tools.)
+This can make the Debian
+source package less useful for people without Debian build
+infrastructure.
+.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
@@ -291,18 +323,6 @@ 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.
@@ -326,7 +346,7 @@ to delete these files.
 .LP
 dpkg-source does not
 (with any of the commonly used source formats)
-represent deletion of files (outside debian/) present in upstream.
+represent deletion of binaries (outside debian/) present in upstream.
 Thus deleting such files in a dpkg-source working tree does not
 actually result in them being deleted from the source package.
 Thus