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

[Jakub Narebski <jnareb@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.

> +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).

> +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