From a738f98cb36e7f1dfe995d16426c475eced61ee2 Mon Sep 17 00:00:00 2001
From: Ian Jackson <ijackson@chiark.greenend.org.uk>
Date: Sun, 15 Jan 2017 22:45:31 +0000
Subject: [PATCH] gitattributes: Docs and message wordsmithing

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
---
 dgit   |  2 +-
 dgit.1 | 28 ++++++++++++++++++++++++++--
 dgit.7 | 19 ++++++++++---------
 3 files changed, 37 insertions(+), 12 deletions(-)

diff --git a/dgit b/dgit
index 3d81558f..e4cc92c0 100755
--- a/dgit
+++ b/dgit
@@ -3392,7 +3392,7 @@ sub check_gitattrs ($$) {
 	# oh dear, found one
 	print STDERR <<END;
 dgit: warning: $what contains .gitattributes
-dgit: .gitattributes have not been defused.  See GITATTRIBUTES in dgit(7).
+dgit: .gitattributes have not been defused.  Recommended: dgit setup-new-tree.
 END
 	close $gafl;
 	return;
diff --git a/dgit.1 b/dgit.1
index 8cf3928a..88691496 100644
--- a/dgit.1
+++ b/dgit.1
@@ -216,9 +216,10 @@ public key in its keyring (but not your private key, obviously).
 .B dgit setup-new-tree
 Configure the current working tree the way that dgit clone would have
 set it up.  Like running
-.B dgit setup-useremail
-and
+.BR "dgit setup-useremail" ,
 .B setup-mergechangelogs
+and
+.B setup-gitattributes
 (but only does each thing if dgit is configured to do it automatically).
 You can use these in any git repository, not just ones used with
 the other dgit operations.
@@ -235,6 +236,29 @@ Configures a git merge helper for the file
 which uses
 .BR dpkg-mergechangelogs .
 .TP
+.B dgit setup-gitattributes
+Set up the working tree's
+.B .git/info/attributes
+to disable all transforming attributes for all files.
+This is done by defining a macro attribute
+.B dgit-defuse-attrs
+and applying it to
+.BR * .
+For why, see
+.B GITATTRIBUTES
+in
+.BR dgit(7) .
+
+(If there is already a macro attribute line
+.B [attr]dgit-defuse-attrs
+in .git/info/attributes
+(whatever its effects),
+this operation does nothing further.
+This fact can be used to defeat or partially defeat
+dgit setup-gitattributes
+and hence
+dgit setup-new-tree.)
+.TP
 .B dgit quilt-fixup
 `3.0 (quilt)' format source packages need changes representing not
 only in-tree but also as patches in debian/patches.  dgit quilt-fixup
diff --git a/dgit.7 b/dgit.7
index 09bb8f44..70165a1b 100644
--- a/dgit.7
+++ b/dgit.7
@@ -205,6 +205,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 +216,23 @@ 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.
-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).
-
+by creating a suitable .git/info/attributes.
 See
 .B dgit setup-new-tree
 and
-- 
2.30.2