grep: document negated line-number, column long options
PATCH 1/1 grep: document negated line-number, column long options
From: "D. Ben Knoble" <[email protected]>
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.
---
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(-)
Documentation/git-grep.txt +9 -1
@@ -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
Signature · 1 line
gitgitgadget
Quoted 8 lines · D. Ben Knoble via GitGitGadget
From: "D. Ben Knoble" <[email protected]>
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 usegit -cto tweak them for a single run---why? Becausegit help grepdoesn'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."
Documentation/git-grep.txt providing this option will cause it to die. · line 162
Quoted 6 lines
--line-number::
Documentation/git-grep.txt +3
-0Prefix 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.
Quoted 4 lines · Junio C Hamano
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.
--- Documentation/gitcli.txt | 14 ++++++++++++++ 1 file changed, 14 insertions(+)
Documentation/gitcli.txt +14 -0
@@ -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 1/1 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.
---
* 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(+)
Documentation/gitcli.txt +17 -0
@@ -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
Signature · 1 line
2.48.1-210-gaa1682cadd
Re: [PATCH v2] gitcli: document that command line trumps config and env
Quoted 13 lines · Junio C Hamano
Documentation/gitcli.txt +5
-0@@ -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
Documentation/gitcli.txt can use `--no-track` to override that behaviour. The same goes for `--color` · line 169
Quoted 10 lines
Documentation/gitcli.txt +10
-0+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.
Signature · 2 lines
brian m. carlson (they/them or he/him) Toronto, Ontario, CA
Re: [PATCH v2] gitcli: document that command line trumps config and env
Quoted 4 lines · brian m. carlson
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.
Quoted 10 lines · Junio C Hamano
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 <[email protected]>---
w/Documentation/gitcli.txt can use `--no-track` to override that behaviour. The same goes for `--color` · line 170
Quoted 10 lines
w/Documentation/gitcli.txt renamed from c/Documentation/gitcli.txt +10
-0@@ -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/
Quoted 2 lines
w/Documentation/gitcli.txt renamed from c/Documentation/gitcli.txt +2
-0+option on the command line is used, instead of the configured +`user.signingKey`.
Quoted 12 lines · Junio C Hamano
Quoted 8 lines · D. Ben Knoble via GitGitGadget
From: "D. Ben Knoble" <[email protected]>
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 usegit -cto tweak them for a single run---why? Becausegit help grepdoesn't mention they can be disabled any other way!
Quoted 6 lines
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?
Quoted 8 lines
Review
Quoted 7 lines
--line-number::
Prefix the line number to matching lines.+--no-line-number::
(quoted diff) +2
-0+ Turn off line number prefixes, even when the configuration file or a + previous option requests them.
Quoted 6 lines
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!
Quoted 15 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/
Quoted 8 lines
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--progresstogether with--porcelainor--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.
Quoted 8 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
Quoted 7 lines
---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?
Quoted 11 lines · D. Ben Knoble
Quoted 10 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--progresstogether with--porcelainor--incremental.
Quoted 4 lines
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.
Quoted 3 lines
Sounds like you would prefer a re-roll that does something similar for
--[no-]line-numberand--[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.