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

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

[Ramkumar Ramachandra]

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

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8ea55d4..db1801e 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -875,6 +875,24 @@ diff.tool::
 	the same valid values as `merge.tool` minus "tortoisemerge"
 	and plus "kompare".
 
+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.
+
 difftool.<tool>.path::
 	Override the path for the given tool.  This is useful in case
 	your tool is not in the PATH.
@@ -973,6 +991,16 @@ format.signoff::
     the rights to submit this work under the same open source license.
     Please see the 'SubmittingPatches' document for further discussion.
 
+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.
+
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
 	algorithm used by 'git gc --aggressive'.  This defaults
-- 
1.7.4.rc1.7.g2cf08.dirty

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

[Jakub Narebski]

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

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

[Ramkumar Ramachandra]

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

Helped-by: Jakub Narebski <jnareb@gmail.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
The first iteration of this patch contained completely wrong
descriptions for diff.<tool>.* options. Thanks to Jakub for pointing
them out, and for pointing out that I left out a a few options
undocumented (found in userdiff.c).

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

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8ea55d4..b2ec4e1 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -875,6 +875,42 @@ diff.tool::
 	the same valid values as `merge.tool` minus "tortoisemerge"
 	and plus "kompare".
 
+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>.funcname::
+	Specifies a regular expression that matches a line to use as
+	the hunk header for files with `diff=<tool>` gitattribute. A
+	built-in pattern may also be used.  See
+	linkgit:gitattributes[5] for details.
+
+diff.<tool>.xfuncname::
+	Same as 'diff.<tool>.funcname', except that an extended
+	regular expression can be specified in this case.
+
+diff.<tool>.binary::
+	Set to true to treat files files with `diff=<tool>`
+	gitattribute as binary for the purposes of 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>.wordregex::
+	Specifies the regular expression to use to customize the rules
+	that `git diff --word-diff` uses to split words in a line.
+	See linkgit:gitattributes[5] for details.
+
+diff.<tool>.cachetextconv::
+	Set to true to enable caching of text conversion outputs for
+	files with `diff=<tool>` gitattribute.  See
+	linkgit:gitattributes[5] for details.
+
 difftool.<tool>.path::
 	Override the path for the given tool.  This is useful in case
 	your tool is not in the PATH.
@@ -973,6 +1009,16 @@ format.signoff::
     the rights to submit this work under the same open source license.
     Please see the 'SubmittingPatches' document for further discussion.
 
+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.
+
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
 	algorithm used by 'git gc --aggressive'.  This defaults
-- 
1.7.4.rc1.7.g2cf08.dirty

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

[Jakub Narebski]

Ramkumar Ramachandra wrote:

> +diff.<tool>.funcname::
> +	Specifies a regular expression that matches a line to use as
> +	the hunk header for files with `diff=<tool>` gitattribute. A
> +	built-in pattern may also be used.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.xfuncname::
> +	Same as 'diff.<tool>.funcname', except that an extended
> +	regular expression can be specified in this case.

Don't we deprecate funcname in favor of xfuncname, perhaps to the point 
of not documenting the former?

-- 
Jakub Narebski
Poland

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

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 01.04.2011 12:43:
> Although the gitattributes page contains comprehensive information
> about these configuration options, they should be included in the
> config documentation for completeness.
> 
> Helped-by: Jakub Narebski <jnareb@gmail.com>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
> The first iteration of this patch contained completely wrong
> descriptions for diff.<tool>.* options. Thanks to Jakub for pointing
> them out, and for pointing out that I left out a a few options
> undocumented (found in userdiff.c).
> 
>  Documentation/config.txt |   46 ++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 46 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 8ea55d4..b2ec4e1 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -875,6 +875,42 @@ diff.tool::
>  	the same valid values as `merge.tool` minus "tortoisemerge"
>  	and plus "kompare".
>  
> +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>.funcname::
> +	Specifies a regular expression that matches a line to use as
> +	the hunk header for files with `diff=<tool>` gitattribute. A
> +	built-in pattern may also be used.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.xfuncname::
> +	Same as 'diff.<tool>.funcname', except that an extended
> +	regular expression can be specified in this case.
> +
> +diff.<tool>.binary::
> +	Set to true to treat files files with `diff=<tool>`
> +	gitattribute as binary for the purposes of 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>.wordregex::
> +	Specifies the regular expression to use to customize the rules
> +	that `git diff --word-diff` uses to split words in a line.
> +	See linkgit:gitattributes[5] for details.
> +
> +diff.<tool>.cachetextconv::
> +	Set to true to enable caching of text conversion outputs for
> +	files with `diff=<tool>` gitattribute.  See
> +	linkgit:gitattributes[5] for details.
> +

I am sorry, but I dislike this for several reasons. First, the wording:
"to use to customize" and the like are no fun to read, and there are
several articles missing.

More importantly: Those config options are not about difftools! Having
diff.<tool>.* before difftool.* is grossly misleading. The options above
are all about external diff drivers. So, diff.<driver>.* would be
appropriate here, esp. when looking at merge.*

>  difftool.<tool>.path::
>  	Override the path for the given tool.  This is useful in case
>  	your tool is not in the PATH.
> @@ -973,6 +1009,16 @@ format.signoff::
>      the rights to submit this work under the same open source license.
>      Please see the 'SubmittingPatches' document for further discussion.
>  
> +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.
> +
>  gc.aggressiveWindow::
>  	The window size parameter used in the delta compression
>  	algorithm used by 'git gc --aggressive'.  This defaults

[PATCH v3 0/3] Document diff and filter drivers in config

[Ramkumar Ramachandra]

What changed since v2:
- I decided to move the diff.* configuration options into a dedicated
  diff-config.txt, corresponding to merge-config.txt.
- The placeholder <driver> is much less confusing than <tool> (see
  difftool.* family) -- thanks to Michael for that.
- Language is much nicer now- thanks to Michael again.
- The deprecated `funcname` is excluded now. Thanks to Jakub.
- There's one extra patch; a small inconsistency that I happened to
  come across while comparing diff-config.txt with merge-config.txt.

Thanks for reading.

-- Ram

Ramkumar Ramachandra (3):
  Documentation: Add filter.<driver>.* to config
  Documentation: Add diff.<driver>.* to config
  Documentation: Allow custom diff tools to be specified in 'diff.tool'

 Documentation/config.txt      |   73 +++++---------------------------
 Documentation/diff-config.txt |   93 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 104 insertions(+), 62 deletions(-)
 create mode 100644 Documentation/diff-config.txt

-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 1/3] Documentation: Add filter.<driver>.* to config

[Ramkumar Ramachandra]

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

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt |   10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8ea55d4..711072c 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -973,6 +973,16 @@ format.signoff::
     the rights to submit this work under the same open source license.
     Please see the 'SubmittingPatches' document for further discussion.
 
+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.
+
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
 	algorithm used by 'git gc --aggressive'.  This defaults
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 2/3] Documentation: Add diff.<driver>.* to config

[Ramkumar Ramachandra]

Although the gitattributes page contains comprehensive information
about these configuration options, they should be included in the
config documentation for completeness.  Also, move out the diff.*
configuration options into a dedicated diff-config.txt.

Helped-by: Jakub Narebski <jnareb@gmail.com>
Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt      |   63 +----------------------------
 Documentation/diff-config.txt |   91 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+), 62 deletions(-)
 create mode 100644 Documentation/diff-config.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 711072c..cfeef63 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -812,68 +812,7 @@ commit.template::
 	"{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
 	specified user's home directory.
 
-diff.autorefreshindex::
-	When using 'git diff' to compare with work tree
-	files, do not consider stat-only change as changed.
-	Instead, silently run `git update-index --refresh` to
-	update the cached stat information for paths whose
-	contents in the work tree match the contents in the
-	index.  This option defaults to true.  Note that this
-	affects only 'git diff' Porcelain, and not lower level
-	'diff' commands such as 'git diff-files'.
-
-diff.external::
-	If this config variable is set, diff generation is not
-	performed using the internal diff machinery, but using the
-	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
-	environment variable.  The command is called with parameters
-	as described under "git Diffs" in linkgit:git[1].  Note: if
-	you want to use an external diff program only on a subset of
-	your files, you	might want to use linkgit:gitattributes[5] instead.
-
-diff.mnemonicprefix::
-	If set, 'git diff' uses a prefix pair that is different from the
-	standard "a/" and "b/" depending on what is being compared.  When
-	this configuration is in effect, reverse diff output also swaps
-	the order of the prefixes:
-`git diff`;;
-	compares the (i)ndex and the (w)ork tree;
-`git diff HEAD`;;
-	 compares a (c)ommit and the (w)ork tree;
-`git diff --cached`;;
-	compares a (c)ommit and the (i)ndex;
-`git diff HEAD:file1 file2`;;
-	compares an (o)bject and a (w)ork tree entity;
-`git diff --no-index a b`;;
-	compares two non-git things (1) and (2).
-
-diff.noprefix::
-	If set, 'git diff' does not show any source or destination prefix.
-
-diff.renameLimit::
-	The number of files to consider when performing the copy/rename
-	detection; equivalent to the 'git diff' option '-l'.
-
-diff.renames::
-	Tells git to detect renames.  If set to any boolean value, it
-	will enable basic rename detection.  If set to "copies" or
-	"copy", it will detect copies, as well.
-
-diff.ignoreSubmodules::
-	Sets the default value of --ignore-submodules. Note that this
-	affects only 'git diff' Porcelain, and not lower level 'diff'
-	commands such as 'git diff-files'. 'git checkout' also honors
-	this setting when reporting uncommitted changes.
-
-diff.suppressBlankEmpty::
-	A boolean to inhibit the standard behavior of printing a space
-	before each empty output line. Defaults to false.
-
-diff.tool::
-	Controls which diff tool is used.  `diff.tool` overrides
-	`merge.tool` when used by linkgit:git-difftool[1] and has
-	the same valid values as `merge.tool` minus "tortoisemerge"
-	and plus "kompare".
+include::diff-config.txt[]
 
 difftool.<tool>.path::
 	Override the path for the given tool.  This is useful in case
diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
new file mode 100644
index 0000000..8c1732f
--- /dev/null
+++ b/Documentation/diff-config.txt
@@ -0,0 +1,91 @@
+diff.autorefreshindex::
+	When using 'git diff' to compare with work tree
+	files, do not consider stat-only change as changed.
+	Instead, silently run `git update-index --refresh` to
+	update the cached stat information for paths whose
+	contents in the work tree match the contents in the
+	index.  This option defaults to true.  Note that this
+	affects only 'git diff' Porcelain, and not lower level
+	'diff' commands such as 'git diff-files'.
+
+diff.external::
+	If this config variable is set, diff generation is not
+	performed using the internal diff machinery, but using the
+	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
+	environment variable.  The command is called with parameters
+	as described under "git Diffs" in linkgit:git[1].  Note: if
+	you want to use an external diff program only on a subset of
+	your files, you	might want to use linkgit:gitattributes[5] instead.
+
+diff.ignoreSubmodules::
+	Sets the default value of --ignore-submodules. Note that this
+	affects only 'git diff' Porcelain, and not lower level 'diff'
+	commands such as 'git diff-files'. 'git checkout' also honors
+	this setting when reporting uncommitted changes.
+
+diff.mnemonicprefix::
+	If set, 'git diff' uses a prefix pair that is different from the
+	standard "a/" and "b/" depending on what is being compared.  When
+	this configuration is in effect, reverse diff output also swaps
+	the order of the prefixes:
+`git diff`;;
+	compares the (i)ndex and the (w)ork tree;
+`git diff HEAD`;;
+	 compares a (c)ommit and the (w)ork tree;
+`git diff --cached`;;
+	compares a (c)ommit and the (i)ndex;
+`git diff HEAD:file1 file2`;;
+	compares an (o)bject and a (w)ork tree entity;
+`git diff --no-index a b`;;
+	compares two non-git things (1) and (2).
+
+diff.noprefix::
+	If set, 'git diff' does not show any source or destination prefix.
+
+diff.renameLimit::
+	The number of files to consider when performing the copy/rename
+	detection; equivalent to the 'git diff' option '-l'.
+
+diff.renames::
+	Tells git to detect renames.  If set to any boolean value, it
+	will enable basic rename detection.  If set to "copies" or
+	"copy", it will detect copies, as well.
+
+diff.suppressBlankEmpty::
+	A boolean to inhibit the standard behavior of printing a space
+	before each empty output line. Defaults to false.
+
+diff.tool::
+	Controls which diff tool is used.  `diff.tool` overrides
+	`merge.tool` when used by linkgit:git-difftool[1] and has
+	the same valid values as `merge.tool` minus "tortoisemerge"
+	and plus "kompare".
+
+diff.<driver>.command::
+	Defines the command that implements the custom diff driver.
+	See linkgit:gitattributes[5] for details.
+
+diff.<driver>.xfuncname::
+	Defines the regular expression that the custom diff driver
+	should use to recognize the hunk header.  A built-in pattern
+	may also be used.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.binary::
+	Set this option to true to make the custom diff driver treat
+	files as binary.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.textconv::
+	Defines the command that the custom diff driver should call to
+	generate the text-converted version of a binary file.  The
+	result of the conversion is used to generate a human-readable
+	diff.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.wordregex::
+	Defines the regular expression that the custom diff driver
+	should use to split words in a line.  See
+	linkgit:gitattributes[5] for details.
+
+diff.<driver>.cachetextconv::
+	Set this option to true to make the custom diff driver cache
+	the text conversion outputs.  See linkgit:gitattributes[5] for
+	details.
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 3/3] Documentation: Allow custom diff tools to be specified in 'diff.tool'

[Ramkumar Ramachandra]

Apart from the list of "valid values", 'diff.tool' can take any value,
provided there is a corresponding 'difftool.<tool>.cmd' option.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/diff-config.txt |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index 8c1732f..7f985a3 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -59,7 +59,9 @@ diff.tool::
 	Controls which diff tool is used.  `diff.tool` overrides
 	`merge.tool` when used by linkgit:git-difftool[1] and has
 	the same valid values as `merge.tool` minus "tortoisemerge"
-	and plus "kompare".
+	and plus "kompare".  Any other value is treated is custom
+	diff tool and there must be a corresponding
+	'difftool.<tool>.cmd' option.
 
 diff.<driver>.command::
 	Defines the command that implements the custom diff driver.
-- 
1.7.4.rc1.7.g2cf08.dirty

Re: [PATCH 1/3] Documentation: Add filter.<driver>.* to config

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 03.04.2011 16:25:
> Although the gitattributes page contains comprehensive information
> about these configuration options, they should be included in the
> config documentation for completeness.
> 
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/config.txt |   10 ++++++++++
>  1 files changed, 10 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 8ea55d4..711072c 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -973,6 +973,16 @@ format.signoff::
>      the rights to submit this work under the same open source license.
>      Please see the 'SubmittingPatches' document for further discussion.
>  
> +filter.<driver>.clean::
> +	Defines the command to be used to convert the contents of
> +	worktree file upon checkin.  See linkgit:gitattributes[5] for
> +	details.
> +

Here we go again :) I rever Desmond Tutu, I dislike "to... to"... And
articles. Also, every option "defines" something, no need to say that:

The command which is used to convert the content of a worktree file to a
blob upon checkin.


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

The command which is used to convert the content of a blob object to a
worktree file upon checkout.

>  gc.aggressiveWindow::
>  	The window size parameter used in the delta compression
>  	algorithm used by 'git gc --aggressive'.  This defaults

Re: [PATCH 2/3] Documentation: Add diff.<driver>.* to config

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 03.04.2011 16:25:
> Although the gitattributes page contains comprehensive information
> about these configuration options, they should be included in the
> config documentation for completeness.  Also, move out the diff.*
> configuration options into a dedicated diff-config.txt.
> 
> Helped-by: Jakub Narebski <jnareb@gmail.com>
> Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/config.txt      |   63 +----------------------------
>  Documentation/diff-config.txt |   91 +++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 92 insertions(+), 62 deletions(-)
>  create mode 100644 Documentation/diff-config.txt
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 711072c..cfeef63 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -812,68 +812,7 @@ commit.template::
>  	"{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
>  	specified user's home directory.
>  
> -diff.autorefreshindex::
> -	When using 'git diff' to compare with work tree
> -	files, do not consider stat-only change as changed.
> -	Instead, silently run `git update-index --refresh` to
> -	update the cached stat information for paths whose
> -	contents in the work tree match the contents in the
> -	index.  This option defaults to true.  Note that this
> -	affects only 'git diff' Porcelain, and not lower level
> -	'diff' commands such as 'git diff-files'.
> -
> -diff.external::
> -	If this config variable is set, diff generation is not
> -	performed using the internal diff machinery, but using the
> -	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
> -	environment variable.  The command is called with parameters
> -	as described under "git Diffs" in linkgit:git[1].  Note: if
> -	you want to use an external diff program only on a subset of
> -	your files, you	might want to use linkgit:gitattributes[5] instead.
> -
> -diff.mnemonicprefix::
> -	If set, 'git diff' uses a prefix pair that is different from the
> -	standard "a/" and "b/" depending on what is being compared.  When
> -	this configuration is in effect, reverse diff output also swaps
> -	the order of the prefixes:
> -`git diff`;;
> -	compares the (i)ndex and the (w)ork tree;
> -`git diff HEAD`;;
> -	 compares a (c)ommit and the (w)ork tree;
> -`git diff --cached`;;
> -	compares a (c)ommit and the (i)ndex;
> -`git diff HEAD:file1 file2`;;
> -	compares an (o)bject and a (w)ork tree entity;
> -`git diff --no-index a b`;;
> -	compares two non-git things (1) and (2).
> -
> -diff.noprefix::
> -	If set, 'git diff' does not show any source or destination prefix.
> -
> -diff.renameLimit::
> -	The number of files to consider when performing the copy/rename
> -	detection; equivalent to the 'git diff' option '-l'.
> -
> -diff.renames::
> -	Tells git to detect renames.  If set to any boolean value, it
> -	will enable basic rename detection.  If set to "copies" or
> -	"copy", it will detect copies, as well.
> -
> -diff.ignoreSubmodules::
> -	Sets the default value of --ignore-submodules. Note that this
> -	affects only 'git diff' Porcelain, and not lower level 'diff'
> -	commands such as 'git diff-files'. 'git checkout' also honors
> -	this setting when reporting uncommitted changes.
> -
> -diff.suppressBlankEmpty::
> -	A boolean to inhibit the standard behavior of printing a space
> -	before each empty output line. Defaults to false.
> -
> -diff.tool::
> -	Controls which diff tool is used.  `diff.tool` overrides
> -	`merge.tool` when used by linkgit:git-difftool[1] and has
> -	the same valid values as `merge.tool` minus "tortoisemerge"
> -	and plus "kompare".
> +include::diff-config.txt[]
>  
>  difftool.<tool>.path::
>  	Override the path for the given tool.  This is useful in case
> diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
> new file mode 100644
> index 0000000..8c1732f
> --- /dev/null
> +++ b/Documentation/diff-config.txt
> @@ -0,0 +1,91 @@
> +diff.autorefreshindex::
> +	When using 'git diff' to compare with work tree
> +	files, do not consider stat-only change as changed.
> +	Instead, silently run `git update-index --refresh` to
> +	update the cached stat information for paths whose
> +	contents in the work tree match the contents in the
> +	index.  This option defaults to true.  Note that this
> +	affects only 'git diff' Porcelain, and not lower level
> +	'diff' commands such as 'git diff-files'.
> +
> +diff.external::
> +	If this config variable is set, diff generation is not
> +	performed using the internal diff machinery, but using the
> +	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
> +	environment variable.  The command is called with parameters
> +	as described under "git Diffs" in linkgit:git[1].  Note: if
> +	you want to use an external diff program only on a subset of
> +	your files, you	might want to use linkgit:gitattributes[5] instead.
> +
> +diff.ignoreSubmodules::
> +	Sets the default value of --ignore-submodules. Note that this
> +	affects only 'git diff' Porcelain, and not lower level 'diff'
> +	commands such as 'git diff-files'. 'git checkout' also honors
> +	this setting when reporting uncommitted changes.
> +
> +diff.mnemonicprefix::
> +	If set, 'git diff' uses a prefix pair that is different from the
> +	standard "a/" and "b/" depending on what is being compared.  When
> +	this configuration is in effect, reverse diff output also swaps
> +	the order of the prefixes:
> +`git diff`;;
> +	compares the (i)ndex and the (w)ork tree;
> +`git diff HEAD`;;
> +	 compares a (c)ommit and the (w)ork tree;
> +`git diff --cached`;;
> +	compares a (c)ommit and the (i)ndex;
> +`git diff HEAD:file1 file2`;;
> +	compares an (o)bject and a (w)ork tree entity;
> +`git diff --no-index a b`;;
> +	compares two non-git things (1) and (2).
> +
> +diff.noprefix::
> +	If set, 'git diff' does not show any source or destination prefix.
> +
> +diff.renameLimit::
> +	The number of files to consider when performing the copy/rename
> +	detection; equivalent to the 'git diff' option '-l'.
> +
> +diff.renames::
> +	Tells git to detect renames.  If set to any boolean value, it
> +	will enable basic rename detection.  If set to "copies" or
> +	"copy", it will detect copies, as well.
> +
> +diff.suppressBlankEmpty::
> +	A boolean to inhibit the standard behavior of printing a space
> +	before each empty output line. Defaults to false.
> +
> +diff.tool::
> +	Controls which diff tool is used.  `diff.tool` overrides
> +	`merge.tool` when used by linkgit:git-difftool[1] and has
> +	the same valid values as `merge.tool` minus "tortoisemerge"
> +	and plus "kompare".

That one would make more sense right before the diftool.* options.

> +
> +diff.<driver>.command::
> +	Defines the command that implements the custom diff driver.
> +	See linkgit:gitattributes[5] for details.

Why not:

The custom diff driver command.

> +
> +diff.<driver>.xfuncname::
> +	Defines the regular expression that the custom diff driver
> +	should use to recognize the hunk header.  A built-in pattern
> +	may also be used.  See linkgit:gitattributes[5] for details.

The regular...

> +
> +diff.<driver>.binary::
> +	Set this option to true to make the custom diff driver treat
> +	files as binary.  See linkgit:gitattributes[5] for details.

This has nothing to do with the diff driver's operation. It is about how
git treats the result (the output from the diff driver):

Set to true if git should treat the output of the custom diff driver as
binary.

> +
> +diff.<driver>.textconv::
> +	Defines the command that the custom diff driver should call to
> +	generate the text-converted version of a binary file.  The
> +	result of the conversion is used to generate a human-readable
> +	diff.  See linkgit:gitattributes[5] for details.

No, please! You don't need a custom diff driver for textconv.

The command which git should call to...

> +
> +diff.<driver>.wordregex::
> +	Defines the regular expression that the custom diff driver
> +	should use to split words in a line.  See
> +	linkgit:gitattributes[5] for details.
> +
> +diff.<driver>.cachetextconv::
> +	Set this option to true to make the custom diff driver cache
> +	the text conversion outputs.  See linkgit:gitattributes[5] for
> +	details.

Again, both are independent of a custom diff driver. Maybe even <driver>
is misleading here, I dunno. By "custom diff driver", I mean the thing
you specify with "diff.<whatever>.command", and this is orthogonal
(unrelated, can be combined with) textconc etc.

Michael

Re: [PATCH 3/3] Documentation: Allow custom diff tools to be specified in 'diff.tool'

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 03.04.2011 16:25:
> Apart from the list of "valid values", 'diff.tool' can take any value,
> provided there is a corresponding 'difftool.<tool>.cmd' option.
> 
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/diff-config.txt |    4 +++-
>  1 files changed, 3 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
> index 8c1732f..7f985a3 100644
> --- a/Documentation/diff-config.txt
> +++ b/Documentation/diff-config.txt
> @@ -59,7 +59,9 @@ diff.tool::
>  	Controls which diff tool is used.  `diff.tool` overrides
>  	`merge.tool` when used by linkgit:git-difftool[1] and has
>  	the same valid values as `merge.tool` minus "tortoisemerge"
> -	and plus "kompare".
> +	and plus "kompare".  Any other value is treated is custom

"treated as a custom"

> +	diff tool and there must be a corresponding
> +	'difftool.<tool>.cmd' option.
>  
>  diff.<driver>.command::
>  	Defines the command that implements the custom diff driver.

Re: [PATCH 2/3] Documentation: Add diff.<driver>.* to config

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

>> ...
>> +diff.<driver>.xfuncname::
>> +	Defines the regular expression that the custom diff driver
>> +	should use to recognize the hunk header.  A built-in pattern
>> +	may also be used.  See linkgit:gitattributes[5] for details.
>
> The regular...

I agree with your "Defines..." comment.

>> +diff.<driver>.binary::
>> +	Set this option to true to make the custom diff driver treat
>> +	files as binary.  See linkgit:gitattributes[5] for details.
>
> This has nothing to do with the diff driver's operation. It is about how
> git treats the result (the output from the diff driver):

In general, the use of "diff.<driver>.foo" is consistent with the current
terminology, which is coming from the description of <driver> in the
gitattributes documentation:

   `diff`
   ^^^^^^

   The attribute `diff` affects how 'git' generates diffs for particular
   files. It can tell git whether to generate a textual patch for the path
   or to treat the path as a binary file.  It can also affect...

   Set::
   ...
   String::

           Diff is shown using the specified diff driver.  Each driver may
           specify one or more options, as described in the following
           section. The options for the diff driver "foo" are defined
           by the configuration variables in the "diff.foo" section of the
           git config file.

When the 'diff' attribute was invented, its string value was meant to say
more than "do generate diff for this path" (set) vs "don't generate diff
for this path" (unset) by saying what _kind_ of file it is and switch the
backend driver to generate diff based on that _kind_.  We could call this
"kind" a file-type, but that is a bit too broad a word; we are not talking
about regular file vs symbolic link or executable vs non-executable.  This
is about letting us determine the type of the _content_ more explicitly
than the case where the attribute is Unspecified and we inspect the
content to determine the type.  Perhaps we could have called this
content-type but again that word has other established meaning.

In any case, as you point out, the description itself is not quite right
from the end-user's point of view, even though it is correct at the
implementation level.

This diff.<driver>.binary variable is a somewhat ugly workaround for
content types that want to be treated as if they are binary while "diff"
(usually you would say "-diff" in gitattributes file for such a path)
works, but still want non-diff users (e.g. "cat-file --textconv") of the
textconv filter to still apply the specified text conversion.  In order to
specify what text conversion to apply, you would need a content-type to do
so, but once you specify a content-type, "diff" will not treat them as
binary anymore, so you tell the "diff" machinery by setting this variable.

At the implementation level, you are telling the <driver>, which is
defined as an array of operations indexed by content-types, to respond to
requests to "diff" by producing "binary files differ", so in that sense,
it is telling "the custom diff driver" to "treat files as binary".

>> +diff.<driver>.textconv::
>> +	Defines the command that the custom diff driver should call to
>> +	generate the text-converted version of a binary file.  The
>> +	result of the conversion is used to generate a human-readable
>> +	diff.  See linkgit:gitattributes[5] for details.
>
> No, please! You don't need a custom diff driver for textconv.

Correct.  Probably we should abolish "custom" from the above description.
Also "binary" is unnecessary in "version of a binary file" above, as it is
perfectly sensible to run ps2ascii for a text postscript file.

>> +diff.<driver>.wordregex::
>> +	Defines the regular expression that the custom diff driver
>> +	should use to split words in a line.  See
>> +	linkgit:gitattributes[5] for details.
>> +
>> +diff.<driver>.cachetextconv::
>> +	Set this option to true to make the custom diff driver cache
>> +	the text conversion outputs.  See linkgit:gitattributes[5] for
>> +	details.
>
> Again, both are independent of a custom diff driver.

Just drop "custom".

> ... Maybe even <driver>
> is misleading here, I dunno.

Perhaps.  See the "file-type" and "content-type" discussion above.

[PATCH v4 0/4] Document diff and filter drivers in config

[Ramkumar Ramachandra]

Also, describe What changed since v3:
- More language improvements, thanks to Michael.
- Junio's elaborate note clarifies several options.
- One more patch in the series to make similar corrections to
  merge-config.

Thanks for reading.

-- Ram

Ramkumar Ramachandra (4):
  Documentation: Add filter.<driver>.* to config
  Documentation: Add diff.<driver>.* to config
  Documentation: Allow custom diff tools to be specified in 'diff.tool'
  Documentation: Minor language improvements to merge-config

 Documentation/config.txt       |   72 ++++---------------------------
 Documentation/diff-config.txt  |   91 ++++++++++++++++++++++++++++++++++++++++
 Documentation/merge-config.txt |   38 ++++++++--------
 3 files changed, 120 insertions(+), 81 deletions(-)
 create mode 100644 Documentation/diff-config.txt

-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Ramkumar Ramachandra]

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

Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8ea55d4..654a3b8 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -973,6 +973,15 @@ format.signoff::
     the rights to submit this work under the same open source license.
     Please see the 'SubmittingPatches' document for further discussion.
 
+filter.<driver>.clean::
+	The command which is used to convert the contents of worktree
+	file upon checkin.  See linkgit:gitattributes[5] for details.
+
+filter.<driver>.smudge::
+	The command which is used to convert the blob object to
+	worktree file upon checkout.  See linkgit:gitattributes[5] for
+	details.
+
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
 	algorithm used by 'git gc --aggressive'.  This defaults
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 2/4] Documentation: Add diff.<driver>.* to config

[Ramkumar Ramachandra]

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

Helped-by: Jakub Narebski <jnareb@gmail.com>
Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt      |   63 +----------------------------
 Documentation/diff-config.txt |   90 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 62 deletions(-)
 create mode 100644 Documentation/diff-config.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 654a3b8..4e13735 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -812,68 +812,7 @@ commit.template::
 	"{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
 	specified user's home directory.
 
-diff.autorefreshindex::
-	When using 'git diff' to compare with work tree
-	files, do not consider stat-only change as changed.
-	Instead, silently run `git update-index --refresh` to
-	update the cached stat information for paths whose
-	contents in the work tree match the contents in the
-	index.  This option defaults to true.  Note that this
-	affects only 'git diff' Porcelain, and not lower level
-	'diff' commands such as 'git diff-files'.
-
-diff.external::
-	If this config variable is set, diff generation is not
-	performed using the internal diff machinery, but using the
-	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
-	environment variable.  The command is called with parameters
-	as described under "git Diffs" in linkgit:git[1].  Note: if
-	you want to use an external diff program only on a subset of
-	your files, you	might want to use linkgit:gitattributes[5] instead.
-
-diff.mnemonicprefix::
-	If set, 'git diff' uses a prefix pair that is different from the
-	standard "a/" and "b/" depending on what is being compared.  When
-	this configuration is in effect, reverse diff output also swaps
-	the order of the prefixes:
-`git diff`;;
-	compares the (i)ndex and the (w)ork tree;
-`git diff HEAD`;;
-	 compares a (c)ommit and the (w)ork tree;
-`git diff --cached`;;
-	compares a (c)ommit and the (i)ndex;
-`git diff HEAD:file1 file2`;;
-	compares an (o)bject and a (w)ork tree entity;
-`git diff --no-index a b`;;
-	compares two non-git things (1) and (2).
-
-diff.noprefix::
-	If set, 'git diff' does not show any source or destination prefix.
-
-diff.renameLimit::
-	The number of files to consider when performing the copy/rename
-	detection; equivalent to the 'git diff' option '-l'.
-
-diff.renames::
-	Tells git to detect renames.  If set to any boolean value, it
-	will enable basic rename detection.  If set to "copies" or
-	"copy", it will detect copies, as well.
-
-diff.ignoreSubmodules::
-	Sets the default value of --ignore-submodules. Note that this
-	affects only 'git diff' Porcelain, and not lower level 'diff'
-	commands such as 'git diff-files'. 'git checkout' also honors
-	this setting when reporting uncommitted changes.
-
-diff.suppressBlankEmpty::
-	A boolean to inhibit the standard behavior of printing a space
-	before each empty output line. Defaults to false.
-
-diff.tool::
-	Controls which diff tool is used.  `diff.tool` overrides
-	`merge.tool` when used by linkgit:git-difftool[1] and has
-	the same valid values as `merge.tool` minus "tortoisemerge"
-	and plus "kompare".
+include::diff-config.txt[]
 
 difftool.<tool>.path::
 	Override the path for the given tool.  This is useful in case
diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
new file mode 100644
index 0000000..0796d5e
--- /dev/null
+++ b/Documentation/diff-config.txt
@@ -0,0 +1,90 @@
+diff.autorefreshindex::
+	When using 'git diff' to compare with work tree
+	files, do not consider stat-only change as changed.
+	Instead, silently run `git update-index --refresh` to
+	update the cached stat information for paths whose
+	contents in the work tree match the contents in the
+	index.  This option defaults to true.  Note that this
+	affects only 'git diff' Porcelain, and not lower level
+	'diff' commands such as 'git diff-files'.
+
+diff.external::
+	If this config variable is set, diff generation is not
+	performed using the internal diff machinery, but using the
+	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
+	environment variable.  The command is called with parameters
+	as described under "git Diffs" in linkgit:git[1].  Note: if
+	you want to use an external diff program only on a subset of
+	your files, you	might want to use linkgit:gitattributes[5] instead.
+
+diff.ignoreSubmodules::
+	Sets the default value of --ignore-submodules. Note that this
+	affects only 'git diff' Porcelain, and not lower level 'diff'
+	commands such as 'git diff-files'. 'git checkout' also honors
+	this setting when reporting uncommitted changes.
+
+diff.mnemonicprefix::
+	If set, 'git diff' uses a prefix pair that is different from the
+	standard "a/" and "b/" depending on what is being compared.  When
+	this configuration is in effect, reverse diff output also swaps
+	the order of the prefixes:
+`git diff`;;
+	compares the (i)ndex and the (w)ork tree;
+`git diff HEAD`;;
+	 compares a (c)ommit and the (w)ork tree;
+`git diff --cached`;;
+	compares a (c)ommit and the (i)ndex;
+`git diff HEAD:file1 file2`;;
+	compares an (o)bject and a (w)ork tree entity;
+`git diff --no-index a b`;;
+	compares two non-git things (1) and (2).
+
+diff.noprefix::
+	If set, 'git diff' does not show any source or destination prefix.
+
+diff.renameLimit::
+	The number of files to consider when performing the copy/rename
+	detection; equivalent to the 'git diff' option '-l'.
+
+diff.renames::
+	Tells git to detect renames.  If set to any boolean value, it
+	will enable basic rename detection.  If set to "copies" or
+	"copy", it will detect copies, as well.
+
+diff.suppressBlankEmpty::
+	A boolean to inhibit the standard behavior of printing a space
+	before each empty output line. Defaults to false.
+
+diff.tool::
+	Controls which diff tool is used.  `diff.tool` overrides
+	`merge.tool` when used by linkgit:git-difftool[1] and has
+	the same valid values as `merge.tool` minus "tortoisemerge"
+	and plus "kompare".
+
+diff.<driver>.command::
+	The custom diff driver command.  See linkgit:gitattributes[5]
+	for details.
+
+diff.<driver>.xfuncname::
+	The regular expression that the custom diff driver should use
+	to recognize the hunk header.  A built-in pattern may also be
+	used.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.binary::
+	Set this option to true to make the custom diff driver treat
+	files as binary.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.textconv::
+	The command that the diff driver should call to generate the
+	text-converted version of a file.  The result of the
+	conversion is used to generate a human-readable diff.  See
+	linkgit:gitattributes[5] for details.
+
+diff.<driver>.wordregex::
+	The regular expression that the diff driver should use to
+	split words in a line.  See linkgit:gitattributes[5] for
+	details.
+
+diff.<driver>.cachetextconv::
+	Set this option to true to make the diff driver cache the text
+	conversion outputs.  See linkgit:gitattributes[5] for details.
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 3/4] Documentation: Allow custom diff tools to be specified in 'diff.tool'

[Ramkumar Ramachandra]

Apart from the list of "valid values", 'diff.tool' can take any value,
provided there is a corresponding 'difftool.<tool>.cmd' option.  Also,
describe this option just before the 'difftool.*' options.

Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/diff-config.txt |   13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index 0796d5e..f1468df 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -55,12 +55,6 @@ diff.suppressBlankEmpty::
 	A boolean to inhibit the standard behavior of printing a space
 	before each empty output line. Defaults to false.
 
-diff.tool::
-	Controls which diff tool is used.  `diff.tool` overrides
-	`merge.tool` when used by linkgit:git-difftool[1] and has
-	the same valid values as `merge.tool` minus "tortoisemerge"
-	and plus "kompare".
-
 diff.<driver>.command::
 	The custom diff driver command.  See linkgit:gitattributes[5]
 	for details.
@@ -88,3 +82,10 @@ diff.<driver>.wordregex::
 diff.<driver>.cachetextconv::
 	Set this option to true to make the diff driver cache the text
 	conversion outputs.  See linkgit:gitattributes[5] for details.
+
+diff.tool::
+	The diff tool to used by linkgit:git-difftool[1].  This option
+	overrides `merge.tool`, and has the same valid values as
+	`merge.tool` minus "tortoisemerge" and plus "kompare".  Any
+	other value is treated as a custom diff tool, and there must
+	be a corresponding 'difftool.<tool>.cmd' option.	
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 4/4] Documentation: Minor language improvements to merge-config

[Ramkumar Ramachandra]

Improve readability by dropping superflous verbs like "specifies",
"controls", and "defines".  Describe the `merge.tool` option just
before the `mergetool.*` options.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/merge-config.txt |   38 +++++++++++++++++++-------------------
 1 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt
index 33bf74c..d3dd640 100644
--- a/Documentation/merge-config.txt
+++ b/Documentation/merge-config.txt
@@ -1,5 +1,5 @@
 merge.conflictstyle::
-	Specify the style in which conflicted hunks are written out to
+	The style in which conflicted hunks are written out to
 	working tree files upon merge.  The default is "merge", which
 	shows a `<<<<<<<` conflict marker, changes made by one side,
 	a `=======` marker, changes made by the other side, and then
@@ -28,19 +28,11 @@ merge.renormalize::
 	attributes" in linkgit:gitattributes[5].
 
 merge.stat::
-	Whether to print the diffstat between ORIG_HEAD and the merge result
-	at the end of the merge.  True by default.
-
-merge.tool::
-	Controls which merge resolution program is used by
-	linkgit:git-mergetool[1].  Valid built-in values are: "araxis",
-	"bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld",
-	"opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff"
-	and "xxdiff".  Any other value is treated is custom merge tool
-	and there must be a corresponding mergetool.<tool>.cmd option.
+	Set this option to false to omit printing the diffstat between
+	ORIG_HEAD and the merge result at the end of the merge.
 
 merge.verbosity::
-	Controls the amount of output shown by the recursive merge
+	The amount of output shown by the recursive merge
 	strategy.  Level 0 outputs nothing except a final error
 	message if conflicts were detected. Level 1 outputs only
 	conflicts, 2 outputs conflicts and file changes.  Level 5 and
@@ -48,15 +40,22 @@ merge.verbosity::
 	Can be overridden by the 'GIT_MERGE_VERBOSITY' environment variable.
 
 merge.<driver>.name::
-	Defines a human-readable name for a custom low-level
-	merge driver.  See linkgit:gitattributes[5] for details.
+	The name of the custom merge driver.  See
+	linkgit:gitattributes[5] for details.
 
 merge.<driver>.driver::
-	Defines the command that implements a custom low-level
-	merge driver.  See linkgit:gitattributes[5] for details.
+	The command that implements the custom merge driver.  See
+	linkgit:gitattributes[5] for details.
 
 merge.<driver>.recursive::
-	Names a low-level merge driver to be used when
-	performing an internal merge between common ancestors.
-	See linkgit:gitattributes[5] for details.
+	The merge driver to be used when performing an internal merge
+	between common ancestors.  See linkgit:gitattributes[5] for
+	details.
+
+merge.tool::
+	The merge tool to be used by linkgit:git-mergetool[1].  Valid
+	built-in values are: "araxis", "bc3", "diffuse", "ecmerge",
+	"emerge", "gvimdiff", "kdiff3", "meld", "opendiff", "p4merge",
+	"tkdiff", "tortoisemerge", "vimdiff" and "xxdiff".  Any other
+	value is treated as a custom merge tool, and there must be a
+	corresponding mergetool.<tool>.cmd option.
-- 
1.7.4.rc1.7.g2cf08.dirty

Re: [PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 06.04.2011 11:57:
> Although the gitattributes page contains comprehensive information
> about these configuration options, they should be included in the
> config documentation for completeness.
> 
> Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/config.txt |    9 +++++++++
>  1 files changed, 9 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 8ea55d4..654a3b8 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -973,6 +973,15 @@ format.signoff::
>      the rights to submit this work under the same open source license.
>      Please see the 'SubmittingPatches' document for further discussion.
>  
> +filter.<driver>.clean::
> +	The command which is used to convert the contents of worktree
> +	file upon checkin.  See linkgit:gitattributes[5] for details.

I don't want to be a PITA, but is there any particular reason you are
refusing to use the article "a" even after repeated suggestions to use
it? (Also, I suggested to say what we are converting into here.)

> +
> +filter.<driver>.smudge::
> +	The command which is used to convert the blob object to
> +	worktree file upon checkout.  See linkgit:gitattributes[5] for
> +	details.
> +

You see, before my first response in this thread I thought: "Doing this
myself would be less work than replying and explaining things, but I'll
try to be nice."

Now, this is v4, I've even provided complete sentences ready for copy &
paste, and we're still iterating. It turned out to be *much more* work
than doing it myself. I'm sorry but I can't afford to spend even more
time on this.

>  gc.aggressiveWindow::
>  	The window size parameter used in the delta compression
>  	algorithm used by 'git gc --aggressive'.  This defaults

Re: [PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Ramkumar Ramachandra]

Hi Michael,

Michael J Gruber writes:
> Ramkumar Ramachandra venit, vidit, dixit 06.04.2011 11:57:
> > Although the gitattributes page contains comprehensive information
> > about these configuration options, they should be included in the
> > config documentation for completeness.
> > 
> > Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
> > Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> > ---
> >  Documentation/config.txt |    9 +++++++++
> >  1 files changed, 9 insertions(+), 0 deletions(-)
> > 
> > diff --git a/Documentation/config.txt b/Documentation/config.txt
> > index 8ea55d4..654a3b8 100644
> > --- a/Documentation/config.txt
> > +++ b/Documentation/config.txt
> > @@ -973,6 +973,15 @@ format.signoff::
> >      the rights to submit this work under the same open source license.
> >      Please see the 'SubmittingPatches' document for further discussion.
> >  
> > +filter.<driver>.clean::
> > +	The command which is used to convert the contents of worktree
> > +	file upon checkin.  See linkgit:gitattributes[5] for details.
> 
> I don't want to be a PITA, but is there any particular reason you are
> refusing to use the article "a" even after repeated suggestions to use
> it? (Also, I suggested to say what we are converting into here.)

Ouch, sorry.

> > +
> > +filter.<driver>.smudge::
> > +	The command which is used to convert the blob object to
> > +	worktree file upon checkout.  See linkgit:gitattributes[5] for
> > +	details.
> > +
> 
> You see, before my first response in this thread I thought: "Doing this
> myself would be less work than replying and explaining things, but I'll
> try to be nice."
> 
> Now, this is v4, I've even provided complete sentences ready for copy &
> paste, and we're still iterating. It turned out to be *much more* work
> than doing it myself. I'm sorry but I can't afford to spend even more
> time on this.

I'm very sorry to have caused so much pain.  Yes, I can imagine how
terrible it must be to review several iterations of a simple
documentation patch.  Thank you for being so patient with me so far- I
understand if you don't want to do this anymore.

I do spend time proofreading patches before sending them out, but I'm
clearly not very good at it.  In future, I'll either try rewriting
entire paragraphs or simply refrain from writing documentation
patches.  Please try to understand that sending out many iterations of
a documentation patch isn't something I particularly enjoy doing.
I'll send out another iteration of this series anyway.

-- Ram

Re: [PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> I'm very sorry to have caused so much pain.  Yes, I can imagine how
> terrible it must be to review several iterations of a simple
> documentation patch.  Thank you for being so patient with me so far- I
> understand if you don't want to do this anymore.
>
> I do spend time proofreading patches before sending them out, but I'm
> clearly not very good at it.  In future, I'll either try rewriting
> entire paragraphs or simply refrain from writing documentation patches.

I do not think that is the lesson you should learn from this exchange.  A
major part of Michael's complaint (which I think was justified) was that
he even made a suggestion that is ready to be cut-and-pasted, but your
reroll does not use the suggested phrasing _without_ explaining why it
doesn't.

It is not limited to "documentation patches".  If you get a "how about
doing it this way---isn't it cleaner?" suggestion to your code patch, you
at least owe either "yeah, that looks better---thanks, I've used it in
this reroll" or "no, because...; I've used the original" to the person who
tried to help you, no?

Re: [PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Ramkumar Ramachandra]

Hi Junio,

Junio C Hamano writes:
> Ramkumar Ramachandra <artagnon@gmail.com> writes:
> > I'm very sorry to have caused so much pain.  Yes, I can imagine how
> > terrible it must be to review several iterations of a simple
> > documentation patch.  Thank you for being so patient with me so far- I
> > understand if you don't want to do this anymore.
> >
> > I do spend time proofreading patches before sending them out, but I'm
> > clearly not very good at it.  In future, I'll either try rewriting
> > entire paragraphs or simply refrain from writing documentation patches.
> 
> I do not think that is the lesson you should learn from this exchange.  A
> major part of Michael's complaint (which I think was justified) was that
> he even made a suggestion that is ready to be cut-and-pasted, but your
> reroll does not use the suggested phrasing _without_ explaining why it
> doesn't.
> 
> It is not limited to "documentation patches".  If you get a "how about
> doing it this way---isn't it cleaner?" suggestion to your code patch, you
> at least owe either "yeah, that looks better---thanks, I've used it in
> this reroll" or "no, because...; I've used the original" to the person who
> tried to help you, no?

I completely agree -- all of Michael's suggestions were excellent, and
I'd definitely owe him an explanation for not using something.  In
this particular case, it was an honest mistake though- I meant to
include Michael's version, but I'd rolled out the wrong commit after
rebasing.

-- Ram

[PATCH v5 0/4] Document diff and filter drivers in config

[Ramkumar Ramachandra]

What changed since v4:
- I included the wrong commit in 1/4 last time.
- More nits and proof-reading.

-- Ram

Ramkumar Ramachandra (4):
  Documentation: Add filter.<driver>.* to config
  Documentation: Add diff.<driver>.* to config
  Documentation: Allow custom diff tools to be specified in 'diff.tool'
  Documentation: Minor language improvements to merge-config

 Documentation/config.txt       |   73 +++++---------------------------
 Documentation/diff-config.txt  |   92 ++++++++++++++++++++++++++++++++++++++++
 Documentation/merge-config.txt |   39 +++++++++--------
 3 files changed, 123 insertions(+), 81 deletions(-)
 create mode 100644 Documentation/diff-config.txt

-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Ramkumar Ramachandra]

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

Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt |   10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 750c86d..d3de3d0 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -977,6 +977,16 @@ format.signoff::
     the rights to submit this work under the same open source license.
     Please see the 'SubmittingPatches' document for further discussion.
 
+filter.<driver>.clean::
+	The command which is used to convert the content of a worktree
+	file to a blob upon checkin.  See linkgit:gitattributes[5] for
+	details.
+
+filter.<driver>.smudge::
+	The command which is used to convert the content of a blob
+	object to a worktree file upon checkout.  See
+	linkgit:gitattributes[5] for details.
+
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
 	algorithm used by 'git gc --aggressive'.  This defaults
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 2/4] Documentation: Add diff.<driver>.* to config

[Ramkumar Ramachandra]

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

Helped-by: Jakub Narebski <jnareb@gmail.com>
Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt      |   63 +----------------------------
 Documentation/diff-config.txt |   90 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 62 deletions(-)
 create mode 100644 Documentation/diff-config.txt

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d3de3d0..e618820 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -812,68 +812,7 @@ commit.template::
 	"{tilde}/" is expanded to the value of `$HOME` and "{tilde}user/" to the
 	specified user's home directory.
 
-diff.autorefreshindex::
-	When using 'git diff' to compare with work tree
-	files, do not consider stat-only change as changed.
-	Instead, silently run `git update-index --refresh` to
-	update the cached stat information for paths whose
-	contents in the work tree match the contents in the
-	index.  This option defaults to true.  Note that this
-	affects only 'git diff' Porcelain, and not lower level
-	'diff' commands such as 'git diff-files'.
-
-diff.external::
-	If this config variable is set, diff generation is not
-	performed using the internal diff machinery, but using the
-	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
-	environment variable.  The command is called with parameters
-	as described under "git Diffs" in linkgit:git[1].  Note: if
-	you want to use an external diff program only on a subset of
-	your files, you	might want to use linkgit:gitattributes[5] instead.
-
-diff.mnemonicprefix::
-	If set, 'git diff' uses a prefix pair that is different from the
-	standard "a/" and "b/" depending on what is being compared.  When
-	this configuration is in effect, reverse diff output also swaps
-	the order of the prefixes:
-`git diff`;;
-	compares the (i)ndex and the (w)ork tree;
-`git diff HEAD`;;
-	 compares a (c)ommit and the (w)ork tree;
-`git diff --cached`;;
-	compares a (c)ommit and the (i)ndex;
-`git diff HEAD:file1 file2`;;
-	compares an (o)bject and a (w)ork tree entity;
-`git diff --no-index a b`;;
-	compares two non-git things (1) and (2).
-
-diff.noprefix::
-	If set, 'git diff' does not show any source or destination prefix.
-
-diff.renameLimit::
-	The number of files to consider when performing the copy/rename
-	detection; equivalent to the 'git diff' option '-l'.
-
-diff.renames::
-	Tells git to detect renames.  If set to any boolean value, it
-	will enable basic rename detection.  If set to "copies" or
-	"copy", it will detect copies, as well.
-
-diff.ignoreSubmodules::
-	Sets the default value of --ignore-submodules. Note that this
-	affects only 'git diff' Porcelain, and not lower level 'diff'
-	commands such as 'git diff-files'. 'git checkout' also honors
-	this setting when reporting uncommitted changes.
-
-diff.suppressBlankEmpty::
-	A boolean to inhibit the standard behavior of printing a space
-	before each empty output line. Defaults to false.
-
-diff.tool::
-	Controls which diff tool is used.  `diff.tool` overrides
-	`merge.tool` when used by linkgit:git-difftool[1] and has
-	the same valid values as `merge.tool` minus "tortoisemerge"
-	and plus "kompare".
+include::diff-config.txt[]
 
 difftool.<tool>.path::
 	Override the path for the given tool.  This is useful in case
diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
new file mode 100644
index 0000000..0796d5e
--- /dev/null
+++ b/Documentation/diff-config.txt
@@ -0,0 +1,90 @@
+diff.autorefreshindex::
+	When using 'git diff' to compare with work tree
+	files, do not consider stat-only change as changed.
+	Instead, silently run `git update-index --refresh` to
+	update the cached stat information for paths whose
+	contents in the work tree match the contents in the
+	index.  This option defaults to true.  Note that this
+	affects only 'git diff' Porcelain, and not lower level
+	'diff' commands such as 'git diff-files'.
+
+diff.external::
+	If this config variable is set, diff generation is not
+	performed using the internal diff machinery, but using the
+	given command.  Can be overridden with the `GIT_EXTERNAL_DIFF'
+	environment variable.  The command is called with parameters
+	as described under "git Diffs" in linkgit:git[1].  Note: if
+	you want to use an external diff program only on a subset of
+	your files, you	might want to use linkgit:gitattributes[5] instead.
+
+diff.ignoreSubmodules::
+	Sets the default value of --ignore-submodules. Note that this
+	affects only 'git diff' Porcelain, and not lower level 'diff'
+	commands such as 'git diff-files'. 'git checkout' also honors
+	this setting when reporting uncommitted changes.
+
+diff.mnemonicprefix::
+	If set, 'git diff' uses a prefix pair that is different from the
+	standard "a/" and "b/" depending on what is being compared.  When
+	this configuration is in effect, reverse diff output also swaps
+	the order of the prefixes:
+`git diff`;;
+	compares the (i)ndex and the (w)ork tree;
+`git diff HEAD`;;
+	 compares a (c)ommit and the (w)ork tree;
+`git diff --cached`;;
+	compares a (c)ommit and the (i)ndex;
+`git diff HEAD:file1 file2`;;
+	compares an (o)bject and a (w)ork tree entity;
+`git diff --no-index a b`;;
+	compares two non-git things (1) and (2).
+
+diff.noprefix::
+	If set, 'git diff' does not show any source or destination prefix.
+
+diff.renameLimit::
+	The number of files to consider when performing the copy/rename
+	detection; equivalent to the 'git diff' option '-l'.
+
+diff.renames::
+	Tells git to detect renames.  If set to any boolean value, it
+	will enable basic rename detection.  If set to "copies" or
+	"copy", it will detect copies, as well.
+
+diff.suppressBlankEmpty::
+	A boolean to inhibit the standard behavior of printing a space
+	before each empty output line. Defaults to false.
+
+diff.tool::
+	Controls which diff tool is used.  `diff.tool` overrides
+	`merge.tool` when used by linkgit:git-difftool[1] and has
+	the same valid values as `merge.tool` minus "tortoisemerge"
+	and plus "kompare".
+
+diff.<driver>.command::
+	The custom diff driver command.  See linkgit:gitattributes[5]
+	for details.
+
+diff.<driver>.xfuncname::
+	The regular expression that the custom diff driver should use
+	to recognize the hunk header.  A built-in pattern may also be
+	used.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.binary::
+	Set this option to true to make the custom diff driver treat
+	files as binary.  See linkgit:gitattributes[5] for details.
+
+diff.<driver>.textconv::
+	The command that the diff driver should call to generate the
+	text-converted version of a file.  The result of the
+	conversion is used to generate a human-readable diff.  See
+	linkgit:gitattributes[5] for details.
+
+diff.<driver>.wordregex::
+	The regular expression that the diff driver should use to
+	split words in a line.  See linkgit:gitattributes[5] for
+	details.
+
+diff.<driver>.cachetextconv::
+	Set this option to true to make the diff driver cache the text
+	conversion outputs.  See linkgit:gitattributes[5] for details.
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 3/4] Documentation: Allow custom diff tools to be specified in 'diff.tool'

[Ramkumar Ramachandra]

Apart from the list of "valid values", 'diff.tool' can take any value,
provided there is a corresponding 'difftool.<tool>.cmd' option.  Also,
describe this option just before the 'difftool.*' options.

Helped-by: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/diff-config.txt |   14 ++++++++------
 1 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt
index 0796d5e..d604484 100644
--- a/Documentation/diff-config.txt
+++ b/Documentation/diff-config.txt
@@ -55,12 +55,6 @@ diff.suppressBlankEmpty::
 	A boolean to inhibit the standard behavior of printing a space
 	before each empty output line. Defaults to false.
 
-diff.tool::
-	Controls which diff tool is used.  `diff.tool` overrides
-	`merge.tool` when used by linkgit:git-difftool[1] and has
-	the same valid values as `merge.tool` minus "tortoisemerge"
-	and plus "kompare".
-
 diff.<driver>.command::
 	The custom diff driver command.  See linkgit:gitattributes[5]
 	for details.
@@ -88,3 +82,11 @@ diff.<driver>.wordregex::
 diff.<driver>.cachetextconv::
 	Set this option to true to make the diff driver cache the text
 	conversion outputs.  See linkgit:gitattributes[5] for details.
+
+diff.tool::
+	The diff tool to be used by linkgit:git-difftool[1].  This
+	option overrides `merge.tool`, and has the same valid built-in
+	values as `merge.tool` minus "tortoisemerge" and plus
+	"kompare".  Any other value is treated as a custom diff tool,
+	and there must be a corresponding `difftool.<tool>.cmd`
+	option.
-- 
1.7.4.rc1.7.g2cf08.dirty

[PATCH 4/4] Documentation: Minor language improvements to merge-config

[Ramkumar Ramachandra]

Improve readability by dropping superflous verbs like "specifies",
"controls", and "defines".  Describe the `merge.tool` option just
before the `mergetool.*` options.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/merge-config.txt |   39 ++++++++++++++++++++-------------------
 1 files changed, 20 insertions(+), 19 deletions(-)

diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt
index 8920258..6cd5127 100644
--- a/Documentation/merge-config.txt
+++ b/Documentation/merge-config.txt
@@ -1,5 +1,5 @@
 merge.conflictstyle::
-	Specify the style in which conflicted hunks are written out to
+	The style in which conflicted hunks are written out to
 	working tree files upon merge.  The default is "merge", which
 	shows a `<<<<<<<` conflict marker, changes made by one side,
 	a `=======` marker, changes made by the other side, and then
@@ -38,19 +38,12 @@ merge.renormalize::
 	attributes" in linkgit:gitattributes[5].
 
 merge.stat::
-	Whether to print the diffstat between ORIG_HEAD and the merge result
-	at the end of the merge.  True by default.
-
-merge.tool::
-	Controls which merge resolution program is used by
-	linkgit:git-mergetool[1].  Valid built-in values are: "araxis",
-	"bc3", "diffuse", "ecmerge", "emerge", "gvimdiff", "kdiff3", "meld",
-	"opendiff", "p4merge", "tkdiff", "tortoisemerge", "vimdiff"
-	and "xxdiff".  Any other value is treated is custom merge tool
-	and there must be a corresponding mergetool.<tool>.cmd option.
+	Set this option to false to omit printing the diffstat between
+	ORIG_HEAD and the merge result at the end of the merge.
+	Defaults to true.
 
 merge.verbosity::
-	Controls the amount of output shown by the recursive merge
+	The amount of output shown by the recursive merge
 	strategy.  Level 0 outputs nothing except a final error
 	message if conflicts were detected. Level 1 outputs only
 	conflicts, 2 outputs conflicts and file changes.  Level 5 and
@@ -58,14 +51,22 @@ merge.verbosity::
 	Can be overridden by the 'GIT_MERGE_VERBOSITY' environment variable.
 
 merge.<driver>.name::
-	Defines a human-readable name for a custom low-level
-	merge driver.  See linkgit:gitattributes[5] for details.
+	The name of the custom merge driver.  See
+	linkgit:gitattributes[5] for details.
 
 merge.<driver>.driver::
-	Defines the command that implements a custom low-level
-	merge driver.  See linkgit:gitattributes[5] for details.
+	The command that implements the custom merge driver.  See
+	linkgit:gitattributes[5] for details.
 
 merge.<driver>.recursive::
-	Names a low-level merge driver to be used when
-	performing an internal merge between common ancestors.
-	See linkgit:gitattributes[5] for details.
+	The merge driver to be used when performing an internal merge
+	between common ancestors.  See linkgit:gitattributes[5] for
+	details.
+
+merge.tool::
+	The merge tool to be used by linkgit:git-mergetool[1].  Valid
+	built-in values are: "araxis", "bc3", "diffuse", "ecmerge",
+	"emerge", "gvimdiff", "kdiff3", "meld", "opendiff", "p4merge",
+	"tkdiff", "tortoisemerge", "vimdiff" and "xxdiff".  Any other
+	value is treated as a custom merge tool, and there must be a
+	corresponding `mergetool.<tool>.cmd` option.
-- 
1.7.4.rc1.7.g2cf08.dirty

Re: [PATCH 2/4] Documentation: Add diff.<driver>.* to config

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> +diff.<driver>.command::
> +	The custom diff driver command.  See linkgit:gitattributes[5]
> +	for details.

This is about "custom", but I thought it was pointed out that ...

> +diff.<driver>.xfuncname::
> +	The regular expression that the custom diff driver should use
> +	to recognize the hunk header.  A built-in pattern may also be
> +	used.  See linkgit:gitattributes[5] for details.
> +
> +diff.<driver>.binary::
> +	Set this option to true to make the custom diff driver treat
> +	files as binary.  See linkgit:gitattributes[5] for details.

... these two don't have much to do with "custom".  You seem to have
dropped "custom" from the remaining three, and I think their description
without "custom" makes more sense.

It is not a problem for me to just amend these two and lose "custom" when
I apply this patch (if there is no other glitch in it, of course), but I
am wondering if these are intentional.

> +diff.<driver>.textconv::
> +diff.<driver>.wordregex::
> +diff.<driver>.cachetextconv::

Re: [PATCH 2/4] Documentation: Add diff.<driver>.* to config

[Ramkumar Ramachandra]

Hi Junio,

Junio C Hamano writes:
> Ramkumar Ramachandra <artagnon@gmail.com> writes:
> 
> > +diff.<driver>.command::
> > +	The custom diff driver command.  See linkgit:gitattributes[5]
> > +	for details.
> 
> This is about "custom", but I thought it was pointed out that ...
> 
> > +diff.<driver>.xfuncname::
> > +	The regular expression that the custom diff driver should use
> > +	to recognize the hunk header.  A built-in pattern may also be
> > +	used.  See linkgit:gitattributes[5] for details.
> > +
> > +diff.<driver>.binary::
> > +	Set this option to true to make the custom diff driver treat
> > +	files as binary.  See linkgit:gitattributes[5] for details.
> 
> ... these two don't have much to do with "custom".  You seem to have
> dropped "custom" from the remaining three, and I think their description
> without "custom" makes more sense.
> 
> It is not a problem for me to just amend these two and lose "custom" when
> I apply this patch (if there is no other glitch in it, of course), but I

Right.  I was a little confused about these two, but yeah- I see now
that dependence on `diff.<driver>.command` is equivalent to saying
that an option applies to a "custom" diff driver.  Please amend to
lose the "custom".

Thanks.

-- Ram

Re: [PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 06.04.2011 20:09:
> Hi Junio,
> 
> Junio C Hamano writes:
>> Ramkumar Ramachandra <artagnon@gmail.com> writes:
>>> I'm very sorry to have caused so much pain.  Yes, I can imagine how
>>> terrible it must be to review several iterations of a simple
>>> documentation patch.  Thank you for being so patient with me so far- I
>>> understand if you don't want to do this anymore.
>>>
>>> I do spend time proofreading patches before sending them out, but I'm
>>> clearly not very good at it.  In future, I'll either try rewriting
>>> entire paragraphs or simply refrain from writing documentation patches.
>>
>> I do not think that is the lesson you should learn from this exchange.  A
>> major part of Michael's complaint (which I think was justified) was that
>> he even made a suggestion that is ready to be cut-and-pasted, but your
>> reroll does not use the suggested phrasing _without_ explaining why it
>> doesn't.
>>
>> It is not limited to "documentation patches".  If you get a "how about
>> doing it this way---isn't it cleaner?" suggestion to your code patch, you
>> at least owe either "yeah, that looks better---thanks, I've used it in
>> this reroll" or "no, because...; I've used the original" to the person who
>> tried to help you, no?
> 
> I completely agree -- all of Michael's suggestions were excellent, and
> I'd definitely owe him an explanation for not using something.  In
> this particular case, it was an honest mistake though- I meant to
> include Michael's version, but I'd rolled out the wrong commit after
> rebasing.

Ram, all is well (explained) now, and please don't give up on
documentation patches. You see, it happened to me again and again that I
submitted something, and someone took over the initiative or the idea
and submitted something under his name. And that is completely OK (after
all I had signed off on my patch, it's part of the O in OSS) but
"deprives" the original submitter of the "reward" of having the commit
count incremented. And that is what I wanted to spare you by not
submitting my own version.

Cheers,
Michael

Re: [PATCH v4 0/4] Document diff and filter drivers in config

[Michael J Gruber]

Ramkumar Ramachandra venit, vidit, dixit 06.04.2011 11:57:
> Also, describe What changed since v3:
> - More language improvements, thanks to Michael.
> - Junio's elaborate note clarifies several options.
> - One more patch in the series to make similar corrections to
>   merge-config.
> 
> Thanks for reading.
> 
> -- Ram
> 
> Ramkumar Ramachandra (4):
>   Documentation: Add filter.<driver>.* to config
>   Documentation: Add diff.<driver>.* to config
>   Documentation: Allow custom diff tools to be specified in 'diff.tool'
>   Documentation: Minor language improvements to merge-config
> 
>  Documentation/config.txt       |   72 ++++---------------------------
>  Documentation/diff-config.txt  |   91 ++++++++++++++++++++++++++++++++++++++++
>  Documentation/merge-config.txt |   38 ++++++++--------
>  3 files changed, 120 insertions(+), 81 deletions(-)
>  create mode 100644 Documentation/diff-config.txt
> 

Thanks for hanging in, looks good (minus the customs which Junio mentioned).

Michael

Re: [PATCH v4 0/4] Document diff and filter drivers in config

[Michael J Gruber]

Michael J Gruber venit, vidit, dixit 07.04.2011 14:47:
> Ramkumar Ramachandra venit, vidit, dixit 06.04.2011 11:57:
>> Also, describe What changed since v3:
>> - More language improvements, thanks to Michael.
>> - Junio's elaborate note clarifies several options.
>> - One more patch in the series to make similar corrections to
>>   merge-config.
>>
>> Thanks for reading.
>>
>> -- Ram
>>
>> Ramkumar Ramachandra (4):
>>   Documentation: Add filter.<driver>.* to config
>>   Documentation: Add diff.<driver>.* to config
>>   Documentation: Allow custom diff tools to be specified in 'diff.tool'
>>   Documentation: Minor language improvements to merge-config
>>
>>  Documentation/config.txt       |   72 ++++---------------------------
>>  Documentation/diff-config.txt  |   91 ++++++++++++++++++++++++++++++++++++++++
>>  Documentation/merge-config.txt |   38 ++++++++--------
>>  3 files changed, 120 insertions(+), 81 deletions(-)
>>  create mode 100644 Documentation/diff-config.txt
>>
> 
> Thanks for hanging in, looks good (minus the customs which Junio mentioned).
> 
> Michael

...oh well, that was meant to be a reply to the v5 cover letter... I
guess I got "lost in thread" ;)

M.

Re: [PATCH 1/4] Documentation: Add filter.<driver>.* to config

[Ramkumar Ramachandra]

Hi Michael,

Michael J Gruber writes:
> Ramkumar Ramachandra venit, vidit, dixit 06.04.2011 20:09:
> > Junio C Hamano writes:
> >> Ramkumar Ramachandra <artagnon@gmail.com> writes:
> >>> I'm very sorry to have caused so much pain.  Yes, I can imagine how
> >>> terrible it must be to review several iterations of a simple
> >>> documentation patch.  Thank you for being so patient with me so far- I
> >>> understand if you don't want to do this anymore.
> >>>
> >>> I do spend time proofreading patches before sending them out, but I'm
> >>> clearly not very good at it.  In future, I'll either try rewriting
> >>> entire paragraphs or simply refrain from writing documentation patches.
> >>
> >> I do not think that is the lesson you should learn from this exchange.  A
> >> major part of Michael's complaint (which I think was justified) was that
> >> he even made a suggestion that is ready to be cut-and-pasted, but your
> >> reroll does not use the suggested phrasing _without_ explaining why it
> >> doesn't.
> >>
> >> It is not limited to "documentation patches".  If you get a "how about
> >> doing it this way---isn't it cleaner?" suggestion to your code patch, you
> >> at least owe either "yeah, that looks better---thanks, I've used it in
> >> this reroll" or "no, because...; I've used the original" to the person who
> >> tried to help you, no?
> > 
> > I completely agree -- all of Michael's suggestions were excellent, and
> > I'd definitely owe him an explanation for not using something.  In
> > this particular case, it was an honest mistake though- I meant to
> > include Michael's version, but I'd rolled out the wrong commit after
> > rebasing.
> 
> Ram, all is well (explained) now, and please don't give up on
> documentation patches. You see, it happened to me again and again that I
> submitted something, and someone took over the initiative or the idea
> and submitted something under his name. And that is completely OK (after
> all I had signed off on my patch, it's part of the O in OSS) but
> "deprives" the original submitter of the "reward" of having the commit
> count incremented. And that is what I wanted to spare you by not
> submitting my own version.

Cool, thanks for understanding and bearing with my slopiness :p

Yes, I strongly believe that we should spend time writing reviews,
even if it's quicker to redo the series entirely* -- that's how we can
get more contributors :)

* This is often the case with inexperienced contributors

-- Ram