[PATCH] docs: explain diff.*.binary option

[Jeff King <peff@peff.net>]

This was added long ago as part of the userdiff refactoring
for textconv, as internally it made the code simpler and
cleaner. However, there was never a concrete use case for
actually using the config variable.

Now that Matthieu Moy has provided such a use case, it's
easy to explain it using his example.

Signed-off-by: Jeff King <peff@peff.net>
---
On Sun, Jan 09, 2011 at 07:55:43PM +0100, Matthieu Moy wrote:

> Jeff King <peff@peff.net> writes:
> 
> > you can get what you want with:
> >
> >   echo '*.ps diff=ps' >.gitattributes
> >   git config diff.ps.textconv ps2ascii
> >   git config diff.ps.binary true
> 
> Yes, this works great. Thanks.
> 
> Did I miss something, or is this undocumented? I can't find that in
> either man gitattributes or man git-config.

Nope, it was never documented, probably because I never figured out what
it was good for. :)

 Documentation/gitattributes.txt |   33 +++++++++++++++++++++++++++++++++
 1 files changed, 33 insertions(+), 0 deletions(-)

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 22b8582..a282adb 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -591,6 +591,39 @@ and now produces better output), you can remove the cache
 manually with `git update-ref -d refs/notes/textconv/jpg` (where
 "jpg" is the name of the diff driver, as in the example above).
 
+Marking files as binary
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Git usually guesses correctly whether a blob contains text or binary
+data by examining the beginning of the contents. However, sometimes you
+may want to override its decision, either because a blob contains binary
+data later in the file, or because the content, while technically
+composed of text characters, is opaque to a human reader. For example,
+many postscript files contain only ascii characters, but produce noisy
+and meaningless diffs.
+
+The simplest way to mark a file as binary is to unset the diff
+attribute in the `.gitattributes` file:
+
+------------------------
+*.ps -diff
+------------------------
+
+This will cause git to generate `Binary files differ` (or a binary
+patch, if binary patches are enabled) instead of a regular diff.
+
+However, one may also want to specify other diff driver attributes. For
+example, you might want to use `textconv` to convert postscript files to
+an ascii representation for human viewing, but otherwise treat them as
+binary files. You cannot specify both `-diff` and `diff=ps` attributes.
+The solution is to use the `diff.*.binary` config option:
+
+------------------------
+[diff "ps"]
+  textconv = ps2ascii
+  binary = true
+------------------------
+
 Performing a three-way merge
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- 
1.7.3.5.4.g0dc52