Document disabling core.whitespace values trailing-space and space-before-tab

From http://article.gmane.org/gmane.comp.version-control.git/68146 I got the syntax that works:

git config core.whitespace "-trailing-space"

Is it me, or is this not readable from git help config which says:

The '-trailing-space' syntax to disable the trailing-space setting is not obvious and not documented as far as I can see. I would have assumed a value of '' would disable it.

Is there a documentation bug here? If so, I suggest this patch. I didn't find anywhere else where the '-setting' syntax was used to disable something.

My first-ever git patch is attached, because Thunderbird messes up due to wrapping. I realize that SubmittingPatches has a mini-guide for reconfiguring Thunderbird (ver 1!), but I really prefer not to have to add extensions and reconfigure Thunderbird to send patches. (Comments to this and how the patch was made are welcome and encouraged)

Peter

Peter Valdemar Mørch
http://www.morch.com

From: =?utf-8?q?Peter=20Valdemar=20M=C3=B8rch?= <[email protected]>
Date: Thu, 24 Jul 2008 07:18:48 +0200
Subject: [PATCH] Document disabling core.whitespace values trailing-space and space-before-tab
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

---
 Documentation/config.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

index e784805..a198b3c 100644
@@ -361,10 +361,12 @@ core.whitespace::
 	consider them as errors:
 +
 * `trailing-space` treats trailing whitespaces at the end of the line
-  as an error (enabled by default).
+  as an error (enabled by default - disable with 'git config core.whitespace
+  "-trailing-space"').
 * `space-before-tab` treats a space character that appears immediately
   before a tab character in the initial indent part of the line as an
-  error (enabled by default).
+  error (enabled by default - disable with 'git config core.whitespace
+  "-space-before-tab"').
 * `indent-with-non-tab` treats a line that is indented with 8 or more
   space characters as an error (not enabled by default).
 * `cr-at-eol` treats a carriage-return at the end of line as

1.5.6

Quoting "Peter Valdemar Mrch (Lists)" <[email protected]>:

Doesn't gitattributes(5) describe the overall syntax in detail?

Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Actually, it gets stranger and stranger!

First, git-config.1 does not mention gitattributes except for specific settings. core.whitespace is not one of these.

gitattributes.5 has:

note that this is ! before the *name* of the attribute, and for "Checking whitespace errors / whitespace":

...

So now, git attributes says to unspecify a setting with '!' in front of the attribute *name*, which for core.whitespace means use the value from git-config, which if not specified means to error on e.g. trailing-space.

Now, I notice that git's own .gitattributes has this:

Which I assume actually works, but is invalid according to git-config.1 and gitattributes.5 because:

For the first line, neither of the values 'indent', 'trail' nor 'space' are valid for core.whitespace, and the '!' notation is not defined in neither gitattributes.5 nor in git-config.1 for *values*.

For the second line, gitattributes states generally about attributes that:

A value of true (unspecified would have required:"*.[ch] !whitespace") is not valid for core.whitespace either.

So now (as I read it), neither git-config.1 nor gitattributes.5 specify how to turn off core.whitespace "elements", but .gitattributes (from git itself) uses one notation (!) with settings that are invalid for other reaons, while "grep core.whitespace t/*" uses another notation (-) to turn off elements.

Also in t/* the elements have various different names, such as: "trail", "trailing", "trailing-space". t/t4019-diff-wserror.sh also uses this:

just to make things interesting!

It seems that there is some inconsistency about this. Perhaps documentation (and changing t/* and .gitattributes accordingly) isn't such a bad idea! :D

Peter

Peter Valdemar Mørch
http://www.morch.com

Yes, but as Peter says in his reply to you, it only talks about [-!]name syntax to force the variable to unset (with '-' prefix) and to revert the variable to the unspecified state (with '!' prefix).

Various "values" given to the whitespace attribute actually act as if they are sub-variables and obey the similar "[-]name" rule, but (1) that is left unsaid, and (2) in that context '!' does not make sense so only '-' has any meaning. We would certainly need to clarify that.

So I think Peter's patch is going in the right direction.

Thus encouraged, I've created a file with two more patches like I described in my previous mail: one that fixes up .gitattributes and one that fixes up t/* to conform to documented syntax of core.whitespace.

(For the future: Is it better to have one file with tree patches like I have created with git format-patch -M -s --stdout, 3 individual numbered files, or one single patch created with git-merge --squash?)

Peter

Peter Valdemar Mørch
http://www.morch.com

Thus encouraged, I've created a file with two more patches like I described in my previous mail: one that fixes up .gitattributes and one that fixes up t/* to conform to documented syntax of core.whitespace.

(For the future: Is it better to have one file with tree patches like I
have created with "git format-patch -M -s --stdout", 3 individual numbered files, or one single patch created with git-merge --squash?)

Peter

Peter Valdemar Mørch
http://www.morch.com

From: =?utf-8?q?Peter=20Valdemar=20M=C3=B8rch?= <[email protected]>
Date: Thu, 24 Jul 2008 07:18:48 +0200
Subject: [PATCH] Document disabling core.whitespace values trailing-space and space-before-tab
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

---
 Documentation/config.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

index e784805..a198b3c 100644
@@ -361,10 +361,12 @@ core.whitespace::
 	consider them as errors:
 +
 * `trailing-space` treats trailing whitespaces at the end of the line
-  as an error (enabled by default).
+  as an error (enabled by default - disable with 'git config core.whitespace
+  "-trailing-space"').
 * `space-before-tab` treats a space character that appears immediately
   before a tab character in the initial indent part of the line as an
-  error (enabled by default).
+  error (enabled by default - disable with 'git config core.whitespace
+  "-space-before-tab"').
 * `indent-with-non-tab` treats a line that is indented with 8 or more
   space characters as an error (not enabled by default).
 * `cr-at-eol` treats a carriage-return at the end of line as

1.5.6

From: =?utf-8?q?Peter=20Valdemar=20M=C3=B8rch?= <[email protected]>
Date: Fri, 25 Jul 2008 07:33:07 +0200
Subject: [PATCH] Fixed up .gitattributes to allign with git-config.1
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

---
 .gitattributes |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

index 6b9c715..1a903b6 100644
@@ -1,2 +1,2 @@
-* whitespace=!indent,trail,space
-*.[ch] whitespace
+* whitespace=-indent-with-non-tab,trailing-space,space-before-tab
+*.[ch] !whitespace

1.5.6

From: =?utf-8?q?Peter=20Valdemar=20M=C3=B8rch?= <[email protected]>
Date: Fri, 25 Jul 2008 07:59:24 +0200
Subject: [PATCH] tests now use git-config's core.whitespace only with documented values
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit

---
 t/t4019-diff-wserror.sh  |   14 +++++++-------
 t/t4124-apply-ws-rule.sh |    4 ++--
 2 files changed, 9 insertions(+), 9 deletions(-)

index 0d9cbb6..ecff30d 100755
@@ -33,9 +33,9 @@ test_expect_success default '
 
 '
 
-test_expect_success 'without -trail' '
+test_expect_success 'without -trailing-space' '
 
-	git config core.whitespace -trail
+	git config core.whitespace -trailing-space
 	git diff --color >output
 	grep "$blue_grep" output >error
 	grep -v "$blue_grep" output >normal

@@ -48,10 +48,10 @@ test_expect_success 'without -trail' '
 
 '
 
-test_expect_success 'without -trail (attribute)' '
+test_expect_success 'without -trailing-space (attribute)' '
 
 	git config --unset core.whitespace
-	echo "F whitespace=-trail" >.gitattributes
+	echo "F whitespace=-trailing-space" >.gitattributes
 	git diff --color >output
 	grep "$blue_grep" output >error
 	grep -v "$blue_grep" output >normal

@@ -99,7 +99,7 @@ test_expect_success 'without -space (attribute)' '
 test_expect_success 'with indent-non-tab only' '
 
 	rm -f .gitattributes
-	git config core.whitespace indent,-trailing,-space
+	git config core.whitespace indent-with-non-tab,-trailing-space,-space-before-tab
 	git diff --color >output
 	grep "$blue_grep" output >error
 	grep -v "$blue_grep" output >normal

@@ -115,7 +115,7 @@ test_expect_success 'with indent-non-tab only' '
 test_expect_success 'with indent-non-tab only (attribute)' '
 
 	git config --unset core.whitespace
-	echo "F whitespace=indent,-trailing,-space" >.gitattributes
+	echo "F whitespace=indent-with-non-tab,-trailing-space,-space-before-tab" >.gitattributes
 	git diff --color >output
 	grep "$blue_grep" output >error
 	grep -v "$blue_grep" output >normal

@@ -147,7 +147,7 @@ test_expect_success 'with cr-at-eol' '
 test_expect_success 'with cr-at-eol (attribute)' '
 
 	git config --unset core.whitespace
-	echo "F whitespace=trailing,cr-at-eol" >.gitattributes
+	echo "F whitespace=trailing-space,cr-at-eol" >.gitattributes
 	git diff --color >output
 	grep "$blue_grep" output >error
 	grep -v "$blue_grep" output >normal

index 85f3da2..644aadc 100755
@@ -106,7 +106,7 @@ test_expect_success 'whitespace=error-all, default rule' '
 
 test_expect_success 'whitespace=error-all, no rule' '
 
-	git config core.whitespace -trailing,-space-before,-indent &&
+	git config core.whitespace -trailing-space,-space-before-tab,-indent-with-non-tab &&
 	apply_patch --whitespace=error-all &&
 	diff file target
 

@@ -130,7 +130,7 @@ do
 		for i in - ''
 		do
 			case "$i" in '') ti='#' ;; *) ti= ;; esac
-			rule=${t}trailing,${s}space,${i}indent
+			rule=${t}trailing-space,${s}space-before-tab,${i}indent-with-non-tab
 
 			rm -f .gitattributes
 			test_expect_success "rule=$rule" '

1.5.6

Actually I take it back. "!name to revert to unspecified and -name to unset" really is about name; values to whitespace do not work like "sub-variables" at all.

I've committed a much more simplified version.

-- >8 --
[PATCH] Documentation: clarify how to diable elements in core.whitespace

Noticed by Peter Valdemar Mørch.

index e784805..798b551 100644
@@ -358,7 +358,8 @@ core.whitespace::
 	A comma separated list of common whitespace problems to
 	notice.  'git-diff' will use `color.diff.whitespace` to
 	highlight them, and 'git-apply --whitespace=error' will
-	consider them as errors:
+	consider them as errors.  You can prefix `-` to disable
+	any of them (e.g. `-trailing-space`):
 +
 * `trailing-space` treats trailing whitespaces at the end of the line
   as an error (enabled by default).

Please do not send patch as attachment. It is very cumbersome to handle.