threads / patch / 54135

patchpretty-options.txt: fix --no-abbrev-commit description

Subject: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

## tl;dr

6 messages between Aug 26, 2020 and Aug 27, 2020. Diffs are folded; open one to read it.

replies: 5people: 3as markdown or json

Sergey Organov· Aug 26, 2020, 14:49 UTC · lore

Description suggested --no-abbrev-commit negates --oneline as well as any other option that implies --abbrev-commit. Fix it to say that it's --abbrev-commit that is negated, not the option that implies it.

Signed-off-by: Sergey Organov <sorganov@gmail.com>
---
 Documentation/pretty-options.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Show changes to Documentation/pretty-options.txt +2 −2
diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt
index 7a6da6db780e..17c5aac4b71d 100644
--- a/Documentation/pretty-options.txt
+++ b/Documentation/pretty-options.txt
@@ -25,8 +25,8 @@ people using 80-column terminals.
 
 --no-abbrev-commit::
 	Show the full 40-byte hexadecimal commit object name. This negates
-	`--abbrev-commit` and those options which imply it such as
-	"--oneline". It also overrides the `log.abbrevCommit` variable.
+	`--abbrev-commit`, either explicit or implied by other options such
+	as "--oneline". It also overrides the `log.abbrevCommit` variable.
 
 --oneline::
 	This is a shorthand for "--pretty=oneline --abbrev-commit"

-- 
2.25.1
Junio C Hamano· Aug 26, 2020, 17:56 UTC · re: Sergey Organov · lore

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

Sergey Organov <sorganov@gmail.com> writes:
Show 6 quoted lines
>  --no-abbrev-commit::
>  	Show the full 40-byte hexadecimal commit object name. This negates
> -	`--abbrev-commit` and those options which imply it such as
> -	"--oneline". It also overrides the `log.abbrevCommit` variable.
> +	`--abbrev-commit`, either explicit or implied by other options such
> +	as "--oneline". It also overrides the `log.abbrevCommit` variable.

I personally do not think it would be crazy to misread that one-line format itself would be defeated when no abbreviation of object names is requested, so from that point of view, the original text would be OK enough, but as long as the updated text is easier to understand, that is fine ;-)

Keeping the original sentence structure, e.g.
    ... and those options which imply abbreviating commit object
    names such as ...

would have been what I wrote, instead of "either explicit or implied by", though.

Thanks.
Sergey Organov· Aug 26, 2020, 21:55 UTC · re: Junio C Hamano · lore

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

Junio C Hamano <gitster@pobox.com> writes:
Show 13 quoted lines
> Sergey Organov <sorganov@gmail.com> writes:
>
>>  --no-abbrev-commit::
>>  	Show the full 40-byte hexadecimal commit object name. This negates
>> -	`--abbrev-commit` and those options which imply it such as
>> -	"--oneline". It also overrides the `log.abbrevCommit` variable.
>> +	`--abbrev-commit`, either explicit or implied by other options such
>> +	as "--oneline". It also overrides the `log.abbrevCommit` variable.
>
> I personally do not think it would be crazy to misread that one-line
> format itself would be defeated when no abbreviation of object names
> is requested, so from that point of view, the original text would be
> OK enough,
Well, I don't think it's OK to essentially say:
  "--no-abbrev-commit" negates "--oneline"
when it doesn't. Yes, I even actually checked it doesn't, just in case.
> but as long as the updated text is easier to understand,
> that is fine ;-)

Admittedly, not being a native speaker, I'm not sure the form I used is a good English, but at least it's factually correct.

Actually, I'd drop it altogether, to read like this:
--no-abbrev-commit::
	Show the full 40-byte hexadecimal commit object name. This negates
	`--abbrev-commit` as well as overrides the `log.abbrevCommit` variable.

as I don't see why such clarification is at all needed in the first place.

I'll re-roll if you agree this variant is better.
Show 8 quoted lines
>
> Keeping the original sentence structure, e.g.
>
>     ... and those options which imply abbreviating commit object names
>     such as ...
>
> would have been what I wrote, instead of "either explicit or implied
> by", though.
Sorry, but it'd then read:
  This negates `--abbrev-commit` and those options which imply
  abbreviating commit object names such as "--oneline".
that again essentially reduces to:
  This negates "--oneline"

that is simply false statement, being exactly the problem of the original that the patch tries to fix.

Thanks, -- Sergey

Junio C Hamano· Aug 26, 2020, 22:07 UTC · re: Sergey Organov · lore

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

Sergey Organov <sorganov@gmail.com> writes:
Show 16 quoted lines
>> Keeping the original sentence structure, e.g.
>>
>>     ... and those options which imply abbreviating commit object names
>>     such as ...
>>
>> would have been what I wrote, instead of "either explicit or implied
>> by", though.
>
> Sorry, but it'd then read:
>
>   This negates `--abbrev-commit` and those options which imply
>   abbreviating commit object names such as "--oneline".
>
> that again essentially reduces to:
>
>   This negates "--oneline"

"--oneline" means a lot more than "do not use full object name", and I think we are on the same page with our shared goal of not negating everything "--oneline" means. We just want to say the option negates only the "do not use full object name" aspect.

"and the effect of abbreviating commit objects implied by other options, such as '--oneline'" may be a more verbose way to say the same thing, I would think, but that would be overkill. I would have expected that with common sense readers would think it would be crazy for --no-abbrev to override everything --oneline means, but if you found that the original risks such an interpretation, perhaps we would need to be more verbose and explicit. I dunno.

Jeff King· Aug 27, 2020, 04:25 UTC · re: Junio C Hamano · lore

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

On Wed, Aug 26, 2020 at 03:07:52PM -0700, Junio C Hamano wrote:
Show 31 quoted lines
> Sergey Organov <sorganov@gmail.com> writes:
> 
> >> Keeping the original sentence structure, e.g.
> >>
> >>     ... and those options which imply abbreviating commit object names
> >>     such as ...
> >>
> >> would have been what I wrote, instead of "either explicit or implied
> >> by", though.
> >
> > Sorry, but it'd then read:
> >
> >   This negates `--abbrev-commit` and those options which imply
> >   abbreviating commit object names such as "--oneline".
> >
> > that again essentially reduces to:
> >
> >   This negates "--oneline"
> 
> "--oneline" means a lot more than "do not use full object name", and
> I think we are on the same page with our shared goal of not negating
> everything "--oneline" means.  We just want to say the option
> negates only the "do not use full object name" aspect.
> 
> "and the effect of abbreviating commit objects implied by other
> options, such as '--oneline'" may be a more verbose way to say the
> same thing, I would think, but that would be overkill.  I would have
> expected that with common sense readers would think it would be
> crazy for --no-abbrev to override everything --oneline means, but if
> you found that the original risks such an interpretation, perhaps we
> would need to be more verbose and explicit.  I dunno.

FWIW, as a third-party observer (because you wanted more opinions, right?), I found the result of Sergey's original patch easy to read and understand.

I also think it's unlikely for people to misinterpret the current text, but it does not hurt to be more precise just in case.

-Peff
Junio C Hamano· Aug 27, 2020, 04:32 UTC · re: Jeff King · lore

Re: [PATCH] pretty-options.txt: fix --no-abbrev-commit description

Jeff King <peff@peff.net> writes:
Show 40 quoted lines
> On Wed, Aug 26, 2020 at 03:07:52PM -0700, Junio C Hamano wrote:
>
>> Sergey Organov <sorganov@gmail.com> writes:
>> 
>> >> Keeping the original sentence structure, e.g.
>> >>
>> >>     ... and those options which imply abbreviating commit object names
>> >>     such as ...
>> >>
>> >> would have been what I wrote, instead of "either explicit or implied
>> >> by", though.
>> >
>> > Sorry, but it'd then read:
>> >
>> >   This negates `--abbrev-commit` and those options which imply
>> >   abbreviating commit object names such as "--oneline".
>> >
>> > that again essentially reduces to:
>> >
>> >   This negates "--oneline"
>> 
>> "--oneline" means a lot more than "do not use full object name", and
>> I think we are on the same page with our shared goal of not negating
>> everything "--oneline" means.  We just want to say the option
>> negates only the "do not use full object name" aspect.
>> 
>> "and the effect of abbreviating commit objects implied by other
>> options, such as '--oneline'" may be a more verbose way to say the
>> same thing, I would think, but that would be overkill.  I would have
>> expected that with common sense readers would think it would be
>> crazy for --no-abbrev to override everything --oneline means, but if
>> you found that the original risks such an interpretation, perhaps we
>> would need to be more verbose and explicit.  I dunno.
>
> FWIW, as a third-party observer (because you wanted more opinions,
> right?), I found the result of Sergey's original patch easy to read and
> understand.
>
> I also think it's unlikely for people to misinterpret the current text,
> but it does not hurt to be more precise just in case.
Yup, I think I said the same already ;-)

← back to recent threads