Re: [PATCH] Documentation: Document diff.<tool>.* and filter.<driver>.* in config

From: Jakub Narebski <jnareb@gmail.com>
Date: Apr 1, 2011, 09:18 UTC
Message-ID: <m3ipuy49fg.fsf@localhost.localdomain>
In-Reply-To: <1301647658-28047-1-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> Although the gitattributes page contains comprehensive information
> about these configuration options, they should be included in the
> config documentation for completeness.

Good idea.

Show 18 quoted lines

> +diff.<tool>.command::
> +	Defines a human-readable name for a custom low-level diff
> +	tool.  See linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.xfuncname::
> +	Defines the command that implements a custom low-level merge
> +	tool.  See linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.textconv::
> +	Names a low-level merge tool to be used when performing an
> +	internal merge between common ancestors.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.cachetextconv::
> +	Names a low-level merge tool to be used when performing an
> +	internal merge between common ancestors.  See
> +	linkgit:gitattributes[5] for details.
> +

WTF?!? You have seriously messed up matching description to config variables.

The human readable-name for a custom diff tool or file-level (contents) merge driver is the '<tool>' part of e.g. `diff.<tool>.command`, not the value of said config variable.

It should IMVHO be something like this:

  +diff.<tool>.command::
  +	Defines command to be called to generate diff for files
  +	with `diff=<tool>` gitattribute.  See linkgit:gitattributes[5]
  +	for details.
  +
  +diff.<tool>.xfuncname::
  +	Specifies a regular expression that matches a line that you
  +	would want to appear as hunk header for files with `diff=<tool>`
  +	gitattribute, similarly to `--show-function-line=REGEXP` option
  +	of GNU diff.  See linkgit:gitattributes[5] for details.
  +
  +diff.<tool>.textconv::
  +	Defines command to be called to generate text-converted version
  +	of a binary file with `diff=<tool>` gitattribute.  The result of
  +	the conversion is used to generate human-readable diff.  See
  +	linkgit:gitattributes[5] for details.
  +
  +diff.<tool>.cachetextconv::
  +	Set to true to enable caching of text conversion.  See
  +	linkgit:gitattributes[5] for details.

There is also `diff.<tool>.wordRegex` to be described. And probably some more (I didn't check which of gitattribute-related config variables are already described).

Show 9 quoted lines

> +filter.<driver>.clean::
> +	Defines the command to be used to convert the contents of
> +	worktree file upon checkin.  See linkgit:gitattributes[5] for
> +	details.
> +
> +filter.<driver>.smudge::
> +	Defines the command to be used to convert the blob object to
> +	worktree file upon checkout.  See linkgit:gitattributes[5] for
> +	details.

This one is correct.

-- 
Jakub Narebski
Poland
ShadeHawk on #git