X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=dgit.git;a=blobdiff_plain;f=dgit.7;h=7ad5abaee9446462544d85cdd3fb89452783a3d8;hp=acc7cc1a36d71f3dfc67b740ff3aa31a4e1663f2;hb=8900e2002df925ebdf4941d18094fc5ca408e027;hpb=edf2e3761f78147bf4fe4fcb0c23f0c3a227d1c8

diff --git a/dgit.7 b/dgit.7
index acc7cc1a..7ad5abae 100644
--- a/dgit.7
+++ b/dgit.7
@@ -197,6 +197,17 @@ import existing vcs history
 (which might not be faithful to dgit's invariants)
 or previous non-Dgit uploads
 (which would not provide a very rich history).
+
+git represents only file executability.
+git does not represent empty directories,
+or any leaf objects other than plain files and symlinks.
+The behaviour of Debian source package formats
+on objects with unusual permissions is complicated.
+Some pathological Debian source packages will no longer build
+if empty directories are pruned
+(or if other things not reproduced by git are changed).
+Such sources cannot be worked with properly in git,
+and therefore not with dgit either.
 .SH READ-ONLY DISTROS
 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
@@ -205,6 +216,9 @@ is configured this way.
 git has features which can automatically transform files
 as they are being copied between the working tree
 and the git history.
+The attributes can be specified in the source tree itself,
+in
+.BR .gitattributes .
 See \fBgitattributes\fP(5).
 
 These transformations are context-sensitive
@@ -213,25 +227,46 @@ 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),
+where the transforming gitattributes are defused,
 to achieve this.)
 
-If transforming gitattributes used,
+If transforming gitattributes are used,
 they can cause trouble,
 because the working tree files can differ from
 the git revision history
 (and therefore from the source packages).
+dgit warns if it finds a .gitattributes file
+(in a package being fetched or imported),
+unless the transforming gitattributes have been defused.
 
-So dgit clone
+dgit clone
 and dgit setup-new-tree
 disable transforming gitattributes
 by default,
-by creating a .git/info/attributes.
+by creating a suitable .git/info/attributes.
+See
+.B dgit setup-new-tree
+and
+.B dgit setup-gitattributes
+in dgit(1).
 .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
 in git.  If the package is a `3.0 (quilt)' package, the patch stack
 will usually not be represented in the git history.
+.SH FILE EXECUTABILITY
+Debian source package formats
+do not always faithfully reproduce
+changes to executability.
+But dgit insists that the result of dgit clone is identical
+(as far as git can represent - see Limitations, above)
+to the result of dpkg-source -x.
+
+So files that are executable in your git tree
+must be executable in the result of dpkg-source -x
+(but often aren't).
+If a package has such troublesome files,
+they have to be non-executable in dgit-compatible git branches.
 .SH FORMAT 3.0 (QUILT)
 For a format `3.0 (quilt)' source package, dgit may have to make a
 commit on your current branch to contain metadata used by quilt and