[PATCH] docs: document --textconv diff option

[Jeff King <peff@peff.net>]

On Wed, Jul 06, 2011 at 06:59:53AM -0700, Jakub Narebski wrote:

> Actually I think neither git-format-patch (which is used by 'patch'
> and 'patches' views), not git-diff-tree (used by 'commitdiff' and
> 'blobdiff' views, and their *_plain versions) supports --textconv,
> and that it is supported only by git-diff.  But you better check that.

I did. It works for both.

> Nb documentation as of 1.7.5 is entirely unhelpful.  Only git-cat-file
> is documented as using --textconv... though this option is examined
> in diff.c, and there is test for git-blame supporting it.

Patch below.

> By the way, I don't know if git read .gitattributes file (which
> defines textconv... unless you use per repository instance
> .git/info/attributes) from tree for given commit, or only from working
> area.

It's not currently read from the tree; see earlier in the thread for
some discussion.

-Peff

-- >8 --
Subject: [PATCH] docs: document --textconv diff option

This has been there since textconv existed, but was never
documented. There is some overlap with what's in
gitattributes(5), but it's important to warn in both places
that textconv diffs probably can't be applied.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/diff-options.txt |   11 +++++++++++
 1 files changed, 11 insertions(+), 0 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 4235302..b620b3a 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -422,6 +422,17 @@ endif::git-format-patch[]
 --no-ext-diff::
 	Disallow external diff drivers.
 
+--textconv::
+--no-textconv::
+	Allow (or disallow) external text conversion filters to be run
+	when comparing binary files. See linkgit:gitattributes[5] for
+	details. Because textconv filters are typically a one-way
+	conversion, the resulting diff is suitable for human
+	consumption, but cannot be applied. For this reason, textconv
+	filters are enabled by default only for linkgit:git-diff[1] and
+	linkgit:git-log[1], but not for linkgit:git-format-patch[1] or
+	diff plumbing commands.
+
 --ignore-submodules[=<when>]::
 	Ignore changes to submodules in the diff generation. <when> can be
 	either "none", "untracked", "dirty" or "all", which is the default
-- 
1.7.6.20.g45f3f.dirty