threads / patch / 62818

patchgrep: document negated line-number, column long options

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

## tl;dr

9 messages between Jan 16, 2025 and Jan 21, 2025. Diffs are folded; open one to read it.

replies: 8people: 4as markdown or json

D. Ben Knoble via GitGitGadget· Jan 16, 2025, 22:20 UTC · lore
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(-)
Show changes to Documentation/git-grep.txt +9 −1
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
Junio C Hamano· Jan 16, 2025, 22:54 UTC · re: D. Ben Knoble via GitGitGadget · lore

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

"D. Ben Knoble via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 8 quoted lines
> 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."

Show 6 quoted lines
>  --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.
Junio C Hamano· Jan 17, 2025, 00:29 UTC · re: Junio C Hamano · lore

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

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(+)
Show changes to diff +14 −0
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
Junio C Hamano· Jan 17, 2025, 02:05 UTC · re: Junio C Hamano · lore

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

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(+)
Show changes to Documentation/gitcli.txt +17 −0
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
brian m. carlson· Jan 17, 2025, 02:41 UTC · re: Junio C Hamano · lore

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

On 2025-01-17 at 02:05:13, Junio C Hamano wrote:
Show 23 quoted lines
> 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
Junio C Hamano· Jan 17, 2025, 18:09 UTC · re: brian m. carlson · lore

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

"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.
Eric Sunshine· Jan 17, 2025, 03:14 UTC · re: Junio C Hamano · lore

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

On Thu, Jan 16, 2025 at 7:30 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 20 quoted lines
> 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`.
D. Ben Knoble· Jan 19, 2025, 23:17 UTC · re: Junio C Hamano · lore

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

On Thu, Jan 16, 2025 at 5:54 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 18 quoted lines
>
> "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`?

Show 14 quoted lines
>
> >  --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!

Show 23 quoted lines
>
>  - 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.

Show 15 quoted lines
>
> 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?

Junio C Hamano· Jan 21, 2025, 20:51 UTC · re: D. Ben Knoble · lore

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

"D. Ben Knoble" <ben.knoble+github@gmail.com> writes:
Show 15 quoted lines
>> $ 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.

← back to recent threads