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

From: zen96285 <redacted>

The git log documentation says "The default option is 'short'." This is wrong. After testing, the default value of '--decorate' is 'auto', not 'short'.

There is no difference between 'auto' and 'short' in terminal, but there is a significant difference in how they behave in the shell.The information generated by the 'short' can be saved in shell variables, while the 'auto' can't.

Signed-off-by: AndyAo Zen96285@gmail.com
---
    describe-doc:fix a obscure error description in the git log documenta…
    
    The git log documentation says "The default option is 'short'." This is
    wrong. After testing, the default value of '--decorate' is 'auto', not
    'short'.
    
    There is no difference between 'auto' and 'short' in terminal, but there
    is a significant difference in how they behave in the shell.The
    information generated by the 'short' can be saved in shell variables,
    while the 'auto' can't.
    
    Signed-off-by: AndyAo Zen96285@gmail.com

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1030%2FAndy-AO%2Ffix_a_obscure_error_description_in_the_git_log_documentation-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1030/Andy-AO/fix_a_obscure_error_description_in_the_git_log_documentation-v1
Pull-Request: https://github.com/git/git/pull/1030

 Documentation/git-log.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 1bbf865a1b2d..37a4694b060a 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt

@@ -39,7 +39,7 @@ 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 default option is 'auto'.
 
 --decorate-refs=<pattern>::
 --decorate-refs-exclude=<pattern>::

base-commit: 4e42405f00ecbbee412846f48cb0253efeebe726
-- 
gitgitgadget

Hi Andy, welcome to Git mailing list!

On 31/05/21 13.00, Andy AO via GitGitGadget wrote:

From: zen96285 <redacted>

The git log documentation says "The default option is 'short'." This is wrong. After testing, the default value of '--decorate' is 'auto', not 'short'.

There is no difference between 'auto' and 'short' in terminal, but there is a significant difference in how they behave in the shell.The information generated by the 'short' can be saved in shell variables, while the 'auto' can't.

Why are info generated with 'short' option (and not 'auto') can be 
assigned to a variable?

Looks OK to me, thanks.

-- 
An old man doll... just what I always wanted! - Clara

On 2021-05-31 06:00:56+0000, Andy AO via GitGitGadget [off-list ref] wrote:

From: zen96285 <redacted>

The git log documentation says "The default option is 'short'." This is wrong. After testing, the default value of '--decorate' is 'auto', not 'short'.

There is no difference between 'auto' and 'short' in terminal, but there is a significant difference in how they behave in the shell.The information generated by the 'short' can be saved in shell variables, while the 'auto' can't.

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

Let's the commit message aside.

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.

I think you meant:

	git log -1 >/tmp/no-decorate

In that case, please check your "log.decorate" config.

-- 
Danh

Hi Đoàn,

On 31/05/21 13.47, Đoàn Trần Công Danh wrote:

On 2021-05-31 06:00:56+0000, Andy AO via GitGitGadget [off-list ref] wrote:

quoted

From: zen96285 <redacted>

The git log documentation says "The default option is 'short'." This is wrong. After testing, the default value of '--decorate' is 'auto', not 'short'.

There is no difference between 'auto' and 'short' in terminal, but there is a significant difference in how they behave in the shell.The information generated by the 'short' can be saved in shell variables, while the 'auto' can't.

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

I think the case here was Andy forwarded this patch from someone, which 
happened to be also himself. Maybe that From: line above can be removed, 
unless that he forwarded from other people (in which From: line must be 
preserved).

-- 
An old man doll... just what I always wanted! - Clara

On 2021-05-31 14:49:32+0700, Bagas Sanjaya [off-list ref] wrote:

Hi Đoàn,

On 31/05/21 13.47, Đoàn Trần Công Danh wrote:

quoted

On 2021-05-31 06:00:56+0000, Andy AO via GitGitGadget [off-list ref] wrote:

quoted

From: zen96285 <redacted>

The git log documentation says "The default option is 'short'." This is wrong. After testing, the default value of '--decorate' is 'auto', not 'short'.

There is no difference between 'auto' and 'short' in terminal, but there is a significant difference in how they behave in the shell.The information generated by the 'short' can be saved in shell variables, while the 'auto' can't.

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

I think the case here was Andy forwarded this patch from someone, which
happened to be also himself. Maybe that From: line above can be removed,
unless that he forwarded from other people (in which From: line must be
preserved).

Andy is using GitGitGadget bridge.
That bridge uses its own email address (gitgitgadget@gmail.com).

Thus, the identity in the RFC 822's header: "From" should be ignored,
and we should use the "From: " line in body instead.

In principle, GitGitGadget will use the Author identity in the commit
that was pushed into GitHub to generate such "From: " line.
So, it's Andy's resposibility to configure correct core.name and
core.email in Andy's machine, and create a commit with correct
authorship. Otherwise, GitGitGadget will create above message.

Hope that help.

-- 
Danh

There're two different default options for log --decorate:
* Should `--decorate` be given without any arguments, it's default to
  `short`
* Should neither `--decorate` nor `--no-decorate` be given, it's default
  to the `log.decorate` or `auto`.

We documented the former, but not the latter.

Let's document them, too.

Reported-by: Andy AO <redacted>
Signed-off-by: Đoàn Trần Công Danh <redacted>
---

 I'm reluctant to send this out since I would like to see Andy get familiar
 with the list.  However, it's a while since the original patch.

 Documentation/git-log.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

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

-- 
2.32.0.5.gc7fdd17fde