[PATCH] grep: document negated line-number, column long options

[PATCH] grep: document negated line-number, column long options

[D. Ben Knoble via GitGitGadget]

From: "D. Ben Knoble" <ben.knoble+github@gmail.com>

I set grep.lineNumber and grep.column on in my user .gitconfig;
sometimes, when I script over the results from `git grep`, I want no
prefixes, only a filename prefix, or only the matched text. I usually
comment out the relevant config sections or use `git -c` to tweak them for
a single run---why? Because `git help grep` doesn't mention they can be
disabled any other way!

Intending to add the ability to negate these options, I reviewed
builtin/grep.c and learned that OPT_BOOL already provides this feature.
Document it for future readers. Borrow "configuration file" language
from `--no-color`, since that's my motivating use case.

Signed-off-by: D. Ben Knoble <ben.knoble+github@gmail.com>
---
    grep: document negated line-number, column long options

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1878%2Fbenknoble%2Fdocument-grep-negated-options-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1878/benknoble/document-grep-negated-options-v1
Pull-Request: https://github.com/git/git/pull/1878

 Documentation/git-grep.txt | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 1e6d7b65c84..7ec5ad381db 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -13,7 +13,7 @@ SYNOPSIS
 	   [-v | --invert-match] [-h|-H] [--full-name]
 	   [-E | --extended-regexp] [-G | --basic-regexp]
 	   [-P | --perl-regexp]
-	   [-F | --fixed-strings] [-n | --line-number] [--column]
+	   [-F | --fixed-strings] [-n | --[no-]line-number] [--[no-]column]
 	   [-l | --files-with-matches] [-L | --files-without-match]
 	   [(-O | --open-files-in-pager) [<pager>]]
 	   [-z | --null]
@@ -157,10 +157,18 @@ providing this option will cause it to die.
 --line-number::
 	Prefix the line number to matching lines.
 
+--no-line-number::
+	Turn off line number prefixes, even when the configuration file or a
+	previous option requests them.
+
 --column::
 	Prefix the 1-indexed byte-offset of the first match from the start of the
 	matching line.
 
+--no-column::
+	Turn off column prefixes, even when the configuration file or a
+	previous option requests them.
+
 -l::
 --files-with-matches::
 --name-only::

base-commit: 757161efcca150a9a96b312d9e780a071e601a03
-- 
gitgitgadget

Re: [PATCH] grep: document negated line-number, column long options

[Junio C Hamano]

"D. Ben Knoble via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: "D. Ben Knoble" <ben.knoble+github@gmail.com>
>
> I set grep.lineNumber and grep.column on in my user .gitconfig;
> sometimes, when I script over the results from `git grep`, I want no
> prefixes, only a filename prefix, or only the matched text. I usually
> comment out the relevant config sections or use `git -c` to tweak them for
> a single run---why? Because `git help grep` doesn't mention they can be
> disabled any other way!

While I am somewhat sympathetic, I'd prefer to see it done in a more
centralized way, so that people understand that *any* Boolean option
and associated configuratrion can be negated by prefixing "--no-" to
the base option, instead of having to learn "Ah, today I learned
that --line-number can be negated with --no-line-number thanks to
this patch."

>  --line-number::
>  	Prefix the line number to matching lines.
>  
> +--no-line-number::
> +	Turn off line number prefixes, even when the configuration file or a
> +	previous option requests them.

So, this is not quite welcome for two reasons.

 - We do not want to see us keep repeating "configuration file" for
   any negatable option, as it is common to all command line options
   and associated configuration knob that the command line option
   trumps the configuration.

 - We do not want to see us keep repeating the substantial part of
   the body of the base option by adding a separate entry for a
   corresponding variant with "--no-".

Even though an approach to centrally teach people that they can
negate a Boolean option "--opt" by saying "--no-opt", and thatn they
can negate a configured setting with a command line option is
desirable, for such an approach to work, the documentation must
somehow signal which option is Boolean.

The way we do so is by doing something like this.

$ git grep -e '^--\[no-\]' Documentation/

An example entry (this is from blame-options.txt) looks like this.

    --[no-]progress::
            Progress status is reported on the standard error stream
            by default when it is attached to a terminal. This flag
            enables progress reporting even if not attached to a
            terminal. Can't use `--progress` together with `--porcelain`
            or `--incremental`.

As nobody complains that "I cannot understand what --no-progress,
which is described in the above, means", there must be a central
place where we describe this convention ("git help cli" talks about
negating options).

So I suspect you'd only need to do something like this

    ---line-number::
    +--[no-]line-number::
	    Prefix the line number ...

in your patch, without doing anything else.

Thanks.

Re: [PATCH] grep: document negated line-number, column long options

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> As nobody complains that "I cannot understand what --no-progress,
> which is described in the above, means", there must be a central
> place where we describe this convention ("git help cli" talks about
> negating options).

I looked for it for a while and noticed that we do not seem to
officially state that command line options trump configuration
variables.  Which is a bit hard to believe for an old timer like me
who taught our developers for 20-years that it is one of the
conventions they must make sure their new commands, options and
configuration variables follow.

In any case, perhaps something along the lines of the following would
help?  This is in the vicinity of where we describe that `--no-track`
is a way to override `--track`.

It is entirely possible that this patch is not needed and I didn't
look hard enough to find an existing documentation that says it
already, though.

---- >8 ----
Subject: [PATCH] gitcli: document that command line trumps configuration

We centrally explain that "--no-whatever" is the way to countermand
the "--whatever" option.  Explain that a configured default can be
overridden by the corresponding command line option, too.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/gitcli.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
index fcd86d2eee..5b6f0e4a4b 100644
--- c/Documentation/gitcli.txt
+++ w/Documentation/gitcli.txt
@@ -161,6 +161,20 @@ can use `--no-track` to override that behaviour. The same goes for `--color`
 and `--no-color`.
 
 
+Options trump configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When there is a configuration variable and a command line option
+that tweaks the behaviour of the same aspect of a Git command,
+the command line option overrides the configuration variable.
+
+For example, the `user.signingKey` configuration variable is used to
+specify the default key used by the `git tag -s` command to create a
+signed tag.  By giving the `-u <key-id>` option to `git tag`, which
+specif es the key used to sign a tag, the key specified by the `-u`
+option on the command line is used, instead of the configured
+`user.signingKey`.
+
+
 Aggregating short options
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 Commands that support the enhanced option parser allow you to aggregate short

[PATCH v2] gitcli: document that command line trumps config and env

[Junio C Hamano]

We centrally explain that "--no-whatever" is the way to countermand
the "--whatever" option.  Explain that a configured default and the
value specified by an environment variable can be overridden by the
corresponding command line option, too.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 * If we are adding a section to the document, let's make it a bit
   more complete by mentioning another source of tweak, i.e., the
   environment variable.

 Documentation/gitcli.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 7c709324ba..00b71bc462 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -152,6 +152,23 @@ can use `--no-track` to override that behaviour. The same goes for `--color`
 and `--no-color`.
 
 
+Options trump configuration and environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When there is a configuration variable or an environment variable
+that tweak the behaviour of an aspect of a Git command, and also a
+command line option that tweaks the same, the command line option
+overrides what the configuration and/or environment variable say.
+
+For example, the `user.name` configuration variable is used to
+specify the human-readable name used by the `git commit` command to
+record the author and the committer name in a newly created commit.
+The `GIT_AUTHOR_NAME` environment variable, if set, takes precedence
+when deciding what author name to record.  The `--author=<author>`
+command line option of the `git commit` command, when given, takes
+precedence over these two sources of information.
+
+
 Aggregating short options
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 Commands that support the enhanced option parser allow you to aggregate short
-- 
2.48.1-210-gaa1682cadd

Re: [PATCH v2] gitcli: document that command line trumps config and env

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1705 bytes --]

On 2025-01-17 at 02:05:13, Junio C Hamano wrote:
> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
> index 7c709324ba..00b71bc462 100644
> --- a/Documentation/gitcli.txt
> +++ b/Documentation/gitcli.txt
> @@ -152,6 +152,23 @@ can use `--no-track` to override that behaviour. The same goes for `--color`
>  and `--no-color`.
>  
>  
> +Options trump configuration and environment
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +When there is a configuration variable or an environment variable
> +that tweak the behaviour of an aspect of a Git command, and also a
> +command line option that tweaks the same, the command line option
> +overrides what the configuration and/or environment variable say.
> +
> +For example, the `user.name` configuration variable is used to
> +specify the human-readable name used by the `git commit` command to
> +record the author and the committer name in a newly created commit.
> +The `GIT_AUTHOR_NAME` environment variable, if set, takes precedence
> +when deciding what author name to record.  The `--author=<author>`
> +command line option of the `git commit` command, when given, takes
> +precedence over these two sources of information.

I appreciate you taking the time to document this.  I remember it coming
up recently on the list and it's good that we're writing this down and
documenting it.

This is useful not only for end users, but also new contributors who
might want to implement a feature or authors of other tools which
interact with Git, who will be able to write tooling that behaves in a
similar way on the first go-around.
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

Re: [PATCH] grep: document negated line-number, column long options

[Eric Sunshine]

On Thu, Jan 16, 2025 at 7:30 PM Junio C Hamano <gitster@pobox.com> wrote:
> Subject: [PATCH] gitcli: document that command line trumps configuration
>
> We centrally explain that "--no-whatever" is the way to countermand
> the "--whatever" option.  Explain that a configured default can be
> overridden by the corresponding command line option, too.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt
> @@ -161,6 +161,20 @@ can use `--no-track` to override that behaviour. The same goes for `--color`
> +Options trump configuration
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +When there is a configuration variable and a command line option
> +that tweaks the behaviour of the same aspect of a Git command,
> +the command line option overrides the configuration variable.
> +
> +For example, the `user.signingKey` configuration variable is used to
> +specify the default key used by the `git tag -s` command to create a
> +signed tag.  By giving the `-u <key-id>` option to `git tag`, which
> +specif es the key used to sign a tag, the key specified by the `-u`

s/specif es/specifies/

> +option on the command line is used, instead of the configured
> +`user.signingKey`.

Re: [PATCH v2] gitcli: document that command line trumps config and env

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> This is useful not only for end users, but also new contributors who
> might want to implement a feature or authors of other tools which
> interact with Git, who will be able to write tooling that behaves in a
> similar way on the first go-around.

OK, thanks.  Let's merge it down to 'next', then.

Re: [PATCH] grep: document negated line-number, column long options

[D. Ben Knoble]

On Thu, Jan 16, 2025 at 5:54 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "D. Ben Knoble via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: "D. Ben Knoble" <ben.knoble+github@gmail.com>
> >
> > I set grep.lineNumber and grep.column on in my user .gitconfig;
> > sometimes, when I script over the results from `git grep`, I want no
> > prefixes, only a filename prefix, or only the matched text. I usually
> > comment out the relevant config sections or use `git -c` to tweak them for
> > a single run---why? Because `git help grep` doesn't mention they can be
> > disabled any other way!
>
> While I am somewhat sympathetic, I'd prefer to see it done in a more
> centralized way, so that people understand that *any* Boolean option
> and associated configuratrion can be negated by prefixing "--no-" to
> the base option, instead of having to learn "Ah, today I learned
> that --line-number can be negated with --no-line-number thanks to
> this patch."

This makes sense, though I want to also make it discoverable. Relying
on `git help cli` is not quite as discoverable as I would like, since
I wouldn't have thought to look there myself—further, it isn't always
clear _which_ options can be negated in the way `git help cli`
describes. [Returning to this midway through writing] Upon
experimentation it appears the answer is "all long options"—TIL!

I wonder if there is some way to point more folks to the conventions
of `git help cli`?

>
> >  --line-number::
> >       Prefix the line number to matching lines.
> >
> > +--no-line-number::
> > +     Turn off line number prefixes, even when the configuration file or a
> > +     previous option requests them.
>
> So, this is not quite welcome for two reasons.
>
>  - We do not want to see us keep repeating "configuration file" for
>    any negatable option, as it is common to all command line options
>    and associated configuration knob that the command line option
>    trumps the configuration.

Fair—as you noticed, this isn't really spelled out anywhere, but you
have patches to fix that below. Thanks!

>
>  - We do not want to see us keep repeating the substantial part of
>    the body of the base option by adding a separate entry for a
>    corresponding variant with "--no-".
>
> Even though an approach to centrally teach people that they can
> negate a Boolean option "--opt" by saying "--no-opt", and thatn they
> can negate a configured setting with a command line option is
> desirable, for such an approach to work, the documentation must
> somehow signal which option is Boolean.
>
> The way we do so is by doing something like this.
>
> $ git grep -e '^--\[no-\]' Documentation/
>
> An example entry (this is from blame-options.txt) looks like this.
>
>     --[no-]progress::
>             Progress status is reported on the standard error stream
>             by default when it is attached to a terminal. This flag
>             enables progress reporting even if not attached to a
>             terminal. Can't use `--progress` together with `--porcelain`
>             or `--incremental`.

Fair enough; I dislike the `[no-]` formatting because it is harder to
build into a search pattern (I have Vim keybindings to search manuals
for long and short options that it breaks), but I will probably live
with it and adjust my search patterns rather than complain further.


>
> As nobody complains that "I cannot understand what --no-progress,
> which is described in the above, means", there must be a central
> place where we describe this convention ("git help cli" talks about
> negating options).
>
> So I suspect you'd only need to do something like this
>
>     ---line-number::
>     +--[no-]line-number::
>             Prefix the line number ...
>
> in your patch, without doing anything else.
>
> Thanks.

Sounds like you would prefer a re-roll that does something similar for
`--[no-]line-number` and `--[no-]column`? I suppose I have to
wonder—for which Boolean options is it worth doing so?

Re: [PATCH] grep: document negated line-number, column long options

[Junio C Hamano]

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:

>> $ git grep -e '^--\[no-\]' Documentation/
>>
>> An example entry (this is from blame-options.txt) looks like this.
>>
>>     --[no-]progress::
>>             Progress status is reported on the standard error stream
>>             by default when it is attached to a terminal. This flag
>>             enables progress reporting even if not attached to a
>>             terminal. Can't use `--progress` together with `--porcelain`
>>             or `--incremental`.
>
> Fair enough; I dislike the `[no-]` formatting because it is harder to
> build into a search pattern (I have Vim keybindings to search manuals
> for long and short options that it breaks), but I will probably live
> with it and adjust my search patterns rather than complain further.

$ git grep -e '^[`]*--\[no-\]' -e '^[`]*--no-' Documentation/

tells us that we also can write the above more like so:

	--progress::
	--no-progress::
		Progress status is reported ...

which may make it more palatable?  I didn't count and sift the hits
into two bin to see which style is more prevalent, but it may not be
a bad idea to consider unifying into one style.

> Sounds like you would prefer a re-roll that does something similar for
> `--[no-]line-number` and `--[no-]column`? I suppose I have to
> wonder—for which Boolean options is it worth doing so?

Ones that are not marked with OPT_NONEG all take --no- variant, and
while going through the list of options we may realize some of them
should *not* take negated forms.  They all commonly share that
"giving --no-opt countermands an earlier --opt or the corresponding
configuration variable setting", and any "--opt" that has its own
corresponding configuration variable should already have the variable
documented in the paragraph, the body text may not have to be updated
at all in the best case (in other words, the only change required may
be to add lines of "--no-foo::" form next to existing "--foo::".

Thanks.