[PATCH] diff-options.txt: document --[no]-textconv

[PATCH] diff-options.txt: document --[no]-textconv

[Jay Soffian]

Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
---
textconv also seems to be supported by blame, it isn't clear to me whether
it respects --no-textconv.

 Documentation/diff-options.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index c7ed946357..8b311a60ea 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -412,6 +412,15 @@ endif::git-format-patch[]
 --no-ext-diff::
 	Disallow external diff drivers.
 
+--textconv::
+	Text conversion of binary files is enabled by default if configured
+	according to "Performing text diffs of binary files" in
+	linkgit:gitattributes[5], but may be disabled with `--no-textconv`.
+	This option overrides a previously given `--no-textconv`.
+
+--no-textconv::
+	Disable text conversion of binary files.
+
 --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.5.2.323.g00f3d

Re: [PATCH] diff-options.txt: document --[no]-textconv

[Junio C Hamano]

Jay Soffian <jaysoffian@gmail.com> writes:

> Signed-off-by: Jay Soffian <jaysoffian@gmail.com>
> ---
> textconv also seems to be supported by blame, it isn't clear to me whether
> it respects --no-textconv.

I think it would, as it shares the command line parser with the rest of
the commands in the "log" family.

Re: [PATCH] diff-options.txt: document --[no]-textconv

[Jeff King]

On Mon, May 23, 2011 at 08:27:54PM -0400, Jay Soffian wrote:

> textconv also seems to be supported by blame, it isn't clear to me whether
> it respects --no-textconv.

Yeah, it should, via the regular diff option parser.

> +--textconv::
> +	Text conversion of binary files is enabled by default if configured
> +	according to "Performing text diffs of binary files" in
> +	linkgit:gitattributes[5], but may be disabled with `--no-textconv`.
> +	This option overrides a previously given `--no-textconv`.

It's only on by default for porcelain commands (log, show, diff).
Plumbing commands do not allow textconv unless --textconv is given.

I don't offhand recall whether it is on by default for blame.

-Peff

[PATCH] doc: discuss textconv versus external diff drivers

[Jeff King]

We already talk about how to use each one and how they work,
but it is a reasonable question to wonder why one might use
one over the other.

Signed-off-by: Jeff King <peff@peff.net>
---
This can probably go with Jay's --textconv documentation topic.

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

diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt
index 15aebc6..412c55b 100644
--- a/Documentation/gitattributes.txt
+++ b/Documentation/gitattributes.txt
@@ -593,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
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-- 
1.7.4.5.7.g2e01