Merge branch 'jk/diff-not-so-quick'

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index a282adb31e336b425c322605f2fafdfc0e27341d..412c55b549354471a56a4e56ca5533277c83bc54 100644 (file)
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -504,6 +504,8 @@ patterns are available:
 
 - `pascal` suitable for source code in the Pascal/Delphi language.
 
+- `perl` suitable for source code in the Perl language.
+
 - `php` suitable for source code in the PHP language.
 
 - `python` suitable for source code in the Python language.
@@ -591,6 +593,37 @@ 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).
 
+Choosing textconv versus external diff
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to show differences between binary or specially-formatted
+blobs in your repository, you can choose to use either an external diff
+command, or to use textconv to convert them to a diff-able text format.
+Which method you choose depends on your exact situation.
+
+The advantage of using an external diff command is flexibility. You are
+not bound to find line-oriented changes, nor is it necessary for the
+output to resemble unified diff. You are free to locate and report
+changes in the most appropriate way for your data format.
+
+A textconv, by comparison, is much more limiting. You provide a
+transformation of the data into a line-oriented text format, and git
+uses its regular diff tools to generate the output. There are several
+advantages to choosing this method:
+
+1. Ease of use. It is often much simpler to write a binary to text
+   transformation than it is to perform your own diff. In many cases,
+   existing programs can be used as textconv filters (e.g., exif,
+   odt2txt).
+
+2. Git diff features. By performing only the transformation step
+   yourself, you can still utilize many of git's diff features,
+   including colorization, word-diff, and combined diffs for merges.
+
+3. Caching. Textconv caching can speed up repeated diffs, such as those
+   you might trigger by running `git log -p`.
+
+
 Marking files as binary
 ^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -630,7 +663,7 @@ Performing a three-way merge
 `merge`
 ^^^^^^^
 
-The attribute `merge` affects how three versions of a file is
+The attribute `merge` affects how three versions of a file are
 merged when a file-level merge is necessary during `git merge`,
 and other commands such as `git revert` and `git cherry-pick`.
 
@@ -644,15 +677,15 @@ Unset::
 
        Take the version from the current branch as the
        tentative merge result, and declare that the merge has
-       conflicts.  This is suitable for binary files that does
+       conflicts.  This is suitable for binary files that do
        not have a well-defined merge semantics.
 
 Unspecified::
 
        By default, this uses the same built-in 3-way merge
-       driver as is the case the `merge` attribute is set.
-       However, `merge.default` configuration variable can name
-       different merge driver to be used for paths to which the
+       driver as is the case when the `merge` attribute is set.
+       However, the `merge.default` configuration variable can name
+       different merge driver to be used with paths for which the
        `merge` attribute is unspecified.
 
 String::