Re: [PATCH] describe-doc:fix a obscure error description in the git log documentation

Đoàn Trần Công Danh  [off-list ref] writes:

Please use your real name and wrap your commit message at 50
characters for subject line and 72 characters for body.

Very good suggestions.  Thanks for raising these issues.

The default option is documented correctly as short.
Please check out builtin/log.c:decorate_callback and
builtin/log.c:parse_decoration_style.

Below command print nothing in my machine:

	git log --decorate -1 >/tmp/default
	git log --decorate=short -1 >/tmp/short
	cmp /tmp/default /tmp/short

I'm curious about your config and/or command invocation.
From the code, I can't guess which scenario that's different.

You two are thinking about two "defaults", I think.  If a --decorate
option you give does not say which kind of decoration you want, by
default, you see the short output.  The above shows that.

If you do not give any --decorate option, the command behaves as if
you gave --decorate=auto, which is what the patch author wanted to
say, I think.

I think you meant:

	git log -1 >/tmp/no-decorate

Yes, and this (with redirection to file), I think you do not get any
decoration---that is what you get from --decorate=auto, i.e.

	git log --decorate=auto -1 >/tmp/auto-decorate

I think the default discussed in the paragraph the patch touches is
"what happens if you do not say what kind, i.e. "--decorate" not
"--decorate=<what kind>", so "the default is 'short'" is correct,
but at the same time, "even if you do not say --decorate, you'll see
short decoration when on a terminal" is worth mentioning somewhere.

On 2021-05-31 15:57:17+0900, Junio C Hamano [off-list ref] wrote:

quoted

I think you meant:

	git log -1 >/tmp/no-decorate

Yes, and this (with redirection to file), I think you do not get any
decoration---that is what you get from --decorate=auto, i.e.

	git log --decorate=auto -1 >/tmp/auto-decorate

I think the default discussed in the paragraph the patch touches is
"what happens if you do not say what kind, i.e. "--decorate" not
"--decorate=<what kind>", so "the default is 'short'" is correct,
but at the same time, "even if you do not say --decorate, you'll see
short decoration when on a terminal" is worth mentioning somewhere.

I forgot that I have log.decorate configured to 'short'. *facepalm*

I think something like this should be nice.

----8<----

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 1bbf865a1b..0498e7bacb 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt

@@ -39,7 +39,9 @@ OPTIONS
 	full ref name (including prefix) will be printed. If 'auto' is
 	specified, then if the output is going to a terminal, the ref names
 	are shown as if 'short' were given, otherwise no ref names are
-	shown. The default option is 'short'.
+	shown. The option `--decorate` is short-hand for `--decorate=short`.
+	Default to configuration value of `log.decorate` if configured,
+	otherwise, `auto`.
 
 --decorate-refs=<pattern>::
 --decorate-refs-exclude=<pattern>::
---->8---------

Andy, feel free to pick this up and re-wording however you like.

-- 
Danh