# [PATCH] diff-options.txt: document --[no]-textconv 4 messages from 2011-05-24 to 2011-05-24. Participants: Jay Soffian, Junio C Hamano, Jeff King. Thread: https://gitlist.dev/t/27439 ## Jay Soffian, 2011-05-24 00:27 Subject: [PATCH] diff-options.txt: document --[no]-textconv Message-ID: <1306196874-64687-1-git-send-email-jaysoffian@gmail.com> URL: https://gitlist.dev/e/1306196874-64687-1-git-send-email-jaysoffian%40gmail.com ``` Signed-off-by: Jay Soffian --- 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[=]:: Ignore changes to submodules in the diff generation. can be either "none", "untracked", "dirty" or "all", which is the default -- 1.7.5.2.323.g00f3d ``` ## Junio C Hamano, 2011-05-24 01:30 Subject: Re: [PATCH] diff-options.txt: document --[no]-textconv Message-ID: <7vlixwanrl.fsf@alter.siamese.dyndns.org> URL: https://gitlist.dev/e/7vlixwanrl.fsf%40alter.siamese.dyndns.org In-Reply-To: <1306196874-64687-1-git-send-email-jaysoffian@gmail.com> ``` Jay Soffian writes: > Signed-off-by: Jay Soffian > --- > 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. ``` ## Jeff King, 2011-05-24 19:43 Subject: Re: [PATCH] diff-options.txt: document --[no]-textconv Message-ID: <20110524194322.GC584@sigill.intra.peff.net> URL: https://gitlist.dev/e/20110524194322.GC584%40sigill.intra.peff.net In-Reply-To: <1306196874-64687-1-git-send-email-jaysoffian@gmail.com> ``` 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 ``` ## Jeff King, 2011-05-24 19:45 Subject: [PATCH] doc: discuss textconv versus external diff drivers Message-ID: <20110524194527.GD584@sigill.intra.peff.net> URL: https://gitlist.dev/e/20110524194527.GD584%40sigill.intra.peff.net In-Reply-To: <1306196874-64687-1-git-send-email-jaysoffian@gmail.com> ``` 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 --- 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 ```