| Message ID | pull.1878.git.git.1737066042014.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | grep: document negated line-number, column long options | expand |
"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.
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
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`.
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?
"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.
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::