gitattributes: Issue a warning on un-defused .gitattributes

[dgit.git] / dgit.7

diff --git a/dgit.7 b/dgit.7
index 635dc132e8ab67d7c30b154127fae82093309e93..09bb8f4424f9d235e8ca115b61c593980bfd93ae 100644 (file)
--- a/dgit.7
+++ b/dgit.7
@@ -201,6 +201,42 @@ 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.
 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).
+
+So dgit clone
+and dgit setup-new-tree
+disable transforming gitattributes
+by default,
+by creating a .git/info/attributes.
+When fetching or importing sources
+dgit warns if it finds .gitattributes file
+and the transforming gitattributes have not been defused
+(e.g. in the case of a tree not made with dgit clone).
+
+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
 .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