{"thread":{"id":"62818","subject":"[PATCH] grep: document negated line-number, column long options","startedAt":"2025-01-16T22:20:44Z","lastAt":"2025-01-21T20:51:58Z","messageCount":9,"participants":["D. Ben Knoble via GitGitGadget","Junio C Hamano","brian m. carlson","Eric Sunshine","D. Ben Knoble"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"510743","messageId":"pull.1878.git.git.1737066042014.gitgitgadget@gmail.com","threadId":"62818","inReplyTo":null,"subject":"[PATCH] grep: document negated line-number, column long options","fromName":"D. Ben Knoble via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-01-16T22:20:41Z","receivedAt":"2025-01-16T22:20:44Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"From: \"D. Ben Knoble\" \n\nI set grep.lineNumber and grep.column on in my user .gitconfig;\nsometimes, when I script over the results from `git grep`, I want no\nprefixes, only a filename prefix, or only the matched text. I usually\ncomment out the relevant config sections or use `git -c` to tweak them for\na single run---why? Because `git help grep` doesn't mention they can be\ndisabled any other way!\n\nIntending to add the ability to negate these options, I reviewed\nbuiltin/grep.c and learned that OPT_BOOL already provides this feature.\nDocument it for future readers. Borrow \"configuration file\" language\nfrom `--no-color`, since that's my motivating use case.\n\nSigned-off-by: D. Ben Knoble \n---\n grep: document negated line-number, column long options\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1878%2Fbenknoble%2Fdocument-grep-negated-options-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1878/benknoble/document-grep-negated-options-v1\nPull-Request: https://github.com/git/git/pull/1878\n\n Documentation/git-grep.txt | 10 +++++++++-\n 1 file changed, 9 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 1e6d7b65c84..7ec5ad381db 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n \t [-v | --invert-match] [-h|-H] [--full-name]\n \t [-E | --extended-regexp] [-G | --basic-regexp]\n \t [-P | --perl-regexp]\n-\t [-F | --fixed-strings] [-n | --line-number] [--column]\n+\t [-F | --fixed-strings] [-n | --[no-]line-number] [--[no-]column]\n \t [-l | --files-with-matches] [-L | --files-without-match]\n \t [(-O | --open-files-in-pager) []]\n \t [-z | --null]\n@@ -157,10 +157,18 @@ providing this option will cause it to die.\n --line-number::\n \tPrefix the line number to matching lines.\n \n+--no-line-number::\n+\tTurn off line number prefixes, even when the configuration file or a\n+\tprevious option requests them.\n+\n --column::\n \tPrefix the 1-indexed byte-offset of the first match from the start of the\n \tmatching line.\n \n+--no-column::\n+\tTurn off column prefixes, even when the configuration file or a\n+\tprevious option requests them.\n+\n -l::\n --files-with-matches::\n --name-only::\n\nbase-commit: 757161efcca150a9a96b312d9e780a071e601a03\n-- \ngitgitgadget\n"},{"id":"510745","messageId":"xmqqy0zanzdw.fsf@gitster.g","threadId":"62818","inReplyTo":"pull.1878.git.git.1737066042014.gitgitgadget@gmail.com","subject":"Re: [PATCH] grep: document negated line-number, column long options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-16T22:54:19Z","receivedAt":"2025-01-16T22:54:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble via GitGitGadget\" writes:\n\n> From: \"D. Ben Knoble\" \n>\n> I set grep.lineNumber and grep.column on in my user .gitconfig;\n> sometimes, when I script over the results from `git grep`, I want no\n> prefixes, only a filename prefix, or only the matched text. I usually\n> comment out the relevant config sections or use `git -c` to tweak them for\n> a single run---why? Because `git help grep` doesn't mention they can be\n> disabled any other way!\n\nWhile I am somewhat sympathetic, I'd prefer to see it done in a more\ncentralized way, so that people understand that *any* Boolean option\nand associated configuratrion can be negated by prefixing \"--no-\" to\nthe base option, instead of having to learn \"Ah, today I learned\nthat --line-number can be negated with --no-line-number thanks to\nthis patch.\"\n\n> --line-number::\n> \tPrefix the line number to matching lines.\n> \n> +--no-line-number::\n> +\tTurn off line number prefixes, even when the configuration file or a\n> +\tprevious option requests them.\n\nSo, this is not quite welcome for two reasons.\n\n - We do not want to see us keep repeating \"configuration file\" for\n any negatable option, as it is common to all command line options\n and associated configuration knob that the command line option\n trumps the configuration.\n\n - We do not want to see us keep repeating the substantial part of\n the body of the base option by adding a separate entry for a\n corresponding variant with \"--no-\".\n\nEven though an approach to centrally teach people that they can\nnegate a Boolean option \"--opt\" by saying \"--no-opt\", and thatn they\ncan negate a configured setting with a command line option is\ndesirable, for such an approach to work, the documentation must\nsomehow signal which option is Boolean.\n\nThe way we do so is by doing something like this.\n\n$ git grep -e '^--\\[no-\\]' Documentation/\n\nAn example entry (this is from blame-options.txt) looks like this.\n\n --[no-]progress::\n Progress status is reported on the standard error stream\n by default when it is attached to a terminal. This flag\n enables progress reporting even if not attached to a\n terminal. Can't use `--progress` together with `--porcelain`\n or `--incremental`.\n\nAs nobody complains that \"I cannot understand what --no-progress,\nwhich is described in the above, means\", there must be a central\nplace where we describe this convention (\"git help cli\" talks about\nnegating options).\n\nSo I suspect you'd only need to do something like this\n\n ---line-number::\n +--[no-]line-number::\n\t Prefix the line number ...\n\nin your patch, without doing anything else.\n\nThanks.\n"},{"id":"510749","messageId":"xmqqfrlinuys.fsf@gitster.g","threadId":"62818","inReplyTo":"xmqqy0zanzdw.fsf@gitster.g","subject":"Re: [PATCH] grep: document negated line-number, column long options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-17T00:29:47Z","receivedAt":"2025-01-17T00:29:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> As nobody complains that \"I cannot understand what --no-progress,\n> which is described in the above, means\", there must be a central\n> place where we describe this convention (\"git help cli\" talks about\n> negating options).\n\nI looked for it for a while and noticed that we do not seem to\nofficially state that command line options trump configuration\nvariables. Which is a bit hard to believe for an old timer like me\nwho taught our developers for 20-years that it is one of the\nconventions they must make sure their new commands, options and\nconfiguration variables follow.\n\nIn any case, perhaps something along the lines of the following would\nhelp? This is in the vicinity of where we describe that `--no-track`\nis a way to override `--track`.\n\nIt is entirely possible that this patch is not needed and I didn't\nlook hard enough to find an existing documentation that says it\nalready, though.\n\n---- >8 ----\nSubject: [PATCH] gitcli: document that command line trumps configuration\n\nWe centrally explain that \"--no-whatever\" is the way to countermand\nthe \"--whatever\" option. Explain that a configured default can be\noverridden by the corresponding command line option, too.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 14 ++++++++++++++\n 1 file changed, 14 insertions(+)\n\ndiff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\nindex fcd86d2eee..5b6f0e4a4b 100644\n--- c/Documentation/gitcli.txt\n+++ w/Documentation/gitcli.txt\n@@ -161,6 +161,20 @@ can use `--no-track` to override that behaviour. The same goes for `--color`\n and `--no-color`.\n \n \n+Options trump configuration\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+When there is a configuration variable and a command line option\n+that tweaks the behaviour of the same aspect of a Git command,\n+the command line option overrides the configuration variable.\n+\n+For example, the `user.signingKey` configuration variable is used to\n+specify the default key used by the `git tag -s` command to create a\n+signed tag. By giving the `-u ` option to `git tag`, which\n+specif es the key used to sign a tag, the key specified by the `-u`\n+option on the command line is used, instead of the configured\n+`user.signingKey`.\n+\n+\n Aggregating short options\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n Commands that support the enhanced option parser allow you to aggregate short\n"},{"id":"510750","messageId":"xmqqzfjqmbza.fsf@gitster.g","threadId":"62818","inReplyTo":"xmqqfrlinuys.fsf@gitster.g","subject":"[PATCH v2] gitcli: document that command line trumps config and env","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-17T02:05:13Z","receivedAt":"2025-01-17T02:05:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"We centrally explain that \"--no-whatever\" is the way to countermand\nthe \"--whatever\" option. Explain that a configured default and the\nvalue specified by an environment variable can be overridden by the\ncorresponding command line option, too.\n\nSigned-off-by: Junio C Hamano \n---\n * If we are adding a section to the document, let's make it a bit\n more complete by mentioning another source of tweak, i.e., the\n environment variable.\n\n Documentation/gitcli.txt | 17 +++++++++++++++++\n 1 file changed, 17 insertions(+)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 7c709324ba..00b71bc462 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -152,6 +152,23 @@ can use `--no-track` to override that behaviour. The same goes for `--color`\n and `--no-color`.\n \n \n+Options trump configuration and environment\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+When there is a configuration variable or an environment variable\n+that tweak the behaviour of an aspect of a Git command, and also a\n+command line option that tweaks the same, the command line option\n+overrides what the configuration and/or environment variable say.\n+\n+For example, the `user.name` configuration variable is used to\n+specify the human-readable name used by the `git commit` command to\n+record the author and the committer name in a newly created commit.\n+The `GIT_AUTHOR_NAME` environment variable, if set, takes precedence\n+when deciding what author name to record. The `--author=`\n+command line option of the `git commit` command, when given, takes\n+precedence over these two sources of information.\n+\n+\n Aggregating short options\n ~~~~~~~~~~~~~~~~~~~~~~~~~\n Commands that support the enhanced option parser allow you to aggregate short\n-- \n2.48.1-210-gaa1682cadd\n\n"},{"id":"510751","messageId":"Z4nDW2FQ-MdWbW5P@tapette.crustytoothpaste.net","threadId":"62818","inReplyTo":"xmqqzfjqmbza.fsf@gitster.g","subject":"Re: [PATCH v2] gitcli: document that command line trumps config and env","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-01-17T02:41:31Z","receivedAt":"2025-01-17T02:41:39Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2025-01-17 at 02:05:13, Junio C Hamano wrote:\n> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\n> index 7c709324ba..00b71bc462 100644\n> --- a/Documentation/gitcli.txt\n> +++ b/Documentation/gitcli.txt\n> @@ -152,6 +152,23 @@ can use `--no-track` to override that behaviour. The same goes for `--color`\n> and `--no-color`.\n> \n> \n> +Options trump configuration and environment\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +When there is a configuration variable or an environment variable\n> +that tweak the behaviour of an aspect of a Git command, and also a\n> +command line option that tweaks the same, the command line option\n> +overrides what the configuration and/or environment variable say.\n> +\n> +For example, the `user.name` configuration variable is used to\n> +specify the human-readable name used by the `git commit` command to\n> +record the author and the committer name in a newly created commit.\n> +The `GIT_AUTHOR_NAME` environment variable, if set, takes precedence\n> +when deciding what author name to record. The `--author=`\n> +command line option of the `git commit` command, when given, takes\n> +precedence over these two sources of information.\n\nI appreciate you taking the time to document this. I remember it coming\nup recently on the list and it's good that we're writing this down and\ndocumenting it.\n\nThis is useful not only for end users, but also new contributors who\nmight want to implement a feature or authors of other tools which\ninteract with Git, who will be able to write tooling that behaves in a\nsimilar way on the first go-around.\n-- \nbrian m. carlson (they/them or he/him)\nToronto, Ontario, CA\n"},{"id":"510752","messageId":"CAPig+cSKHWm+Xwk8AAeyOdHh8voPc4OBT-bZdsWHBGDG0GcgJA@mail.gmail.com","threadId":"62818","inReplyTo":"xmqqfrlinuys.fsf@gitster.g","subject":"Re: [PATCH] grep: document negated line-number, column long options","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-01-17T03:14:06Z","receivedAt":"2025-01-17T03:14:18Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, Jan 16, 2025 at 7:30 PM Junio C Hamano wrote:\n> Subject: [PATCH] gitcli: document that command line trumps configuration\n>\n> We centrally explain that \"--no-whatever\" is the way to countermand\n> the \"--whatever\" option. Explain that a configured default can be\n> overridden by the corresponding command line option, too.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> @@ -161,6 +161,20 @@ can use `--no-track` to override that behaviour. The same goes for `--color`\n> +Options trump configuration\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +When there is a configuration variable and a command line option\n> +that tweaks the behaviour of the same aspect of a Git command,\n> +the command line option overrides the configuration variable.\n> +\n> +For example, the `user.signingKey` configuration variable is used to\n> +specify the default key used by the `git tag -s` command to create a\n> +signed tag. By giving the `-u ` option to `git tag`, which\n> +specif es the key used to sign a tag, the key specified by the `-u`\n\ns/specif es/specifies/\n\n> +option on the command line is used, instead of the configured\n> +`user.signingKey`.\n"},{"id":"510819","messageId":"xmqqtt9xl3by.fsf@gitster.g","threadId":"62818","inReplyTo":"Z4nDW2FQ-MdWbW5P@tapette.crustytoothpaste.net","subject":"Re: [PATCH v2] gitcli: document that command line trumps config and env","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-17T18:09:37Z","receivedAt":"2025-01-17T18:09:39Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> This is useful not only for end users, but also new contributors who\n> might want to implement a feature or authors of other tools which\n> interact with Git, who will be able to write tooling that behaves in a\n> similar way on the first go-around.\n\nOK, thanks. Let's merge it down to 'next', then.\n"},{"id":"510915","messageId":"CALnO6CBUbmZaL1NuG2RxrvuxbUexKdtKfgYi2jTDY3QEa9NQkA@mail.gmail.com","threadId":"62818","inReplyTo":"xmqqy0zanzdw.fsf@gitster.g","subject":"Re: [PATCH] grep: document negated line-number, column long options","fromName":"D. Ben Knoble","fromEmail":"ben.knoble+github@gmail.com","sentAt":"2025-01-19T23:17:03Z","receivedAt":"2025-01-19T23:17:15Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Thu, Jan 16, 2025 at 5:54 PM Junio C Hamano wrote:\n>\n> \"D. Ben Knoble via GitGitGadget\" writes:\n>\n> > From: \"D. Ben Knoble\" \n> >\n> > I set grep.lineNumber and grep.column on in my user .gitconfig;\n> > sometimes, when I script over the results from `git grep`, I want no\n> > prefixes, only a filename prefix, or only the matched text. I usually\n> > comment out the relevant config sections or use `git -c` to tweak them for\n> > a single run---why? Because `git help grep` doesn't mention they can be\n> > disabled any other way!\n>\n> While I am somewhat sympathetic, I'd prefer to see it done in a more\n> centralized way, so that people understand that *any* Boolean option\n> and associated configuratrion can be negated by prefixing \"--no-\" to\n> the base option, instead of having to learn \"Ah, today I learned\n> that --line-number can be negated with --no-line-number thanks to\n> this patch.\"\n\nThis makes sense, though I want to also make it discoverable. Relying\non `git help cli` is not quite as discoverable as I would like, since\nI wouldn't have thought to look there myself—further, it isn't always\nclear _which_ options can be negated in the way `git help cli`\ndescribes. [Returning to this midway through writing] Upon\nexperimentation it appears the answer is \"all long options\"—TIL!\n\nI wonder if there is some way to point more folks to the conventions\nof `git help cli`?\n\n>\n> > --line-number::\n> > Prefix the line number to matching lines.\n> >\n> > +--no-line-number::\n> > + Turn off line number prefixes, even when the configuration file or a\n> > + previous option requests them.\n>\n> So, this is not quite welcome for two reasons.\n>\n> - We do not want to see us keep repeating \"configuration file\" for\n> any negatable option, as it is common to all command line options\n> and associated configuration knob that the command line option\n> trumps the configuration.\n\nFair—as you noticed, this isn't really spelled out anywhere, but you\nhave patches to fix that below. Thanks!\n\n>\n> - We do not want to see us keep repeating the substantial part of\n> the body of the base option by adding a separate entry for a\n> corresponding variant with \"--no-\".\n>\n> Even though an approach to centrally teach people that they can\n> negate a Boolean option \"--opt\" by saying \"--no-opt\", and thatn they\n> can negate a configured setting with a command line option is\n> desirable, for such an approach to work, the documentation must\n> somehow signal which option is Boolean.\n>\n> The way we do so is by doing something like this.\n>\n> $ git grep -e '^--\\[no-\\]' Documentation/\n>\n> An example entry (this is from blame-options.txt) looks like this.\n>\n> --[no-]progress::\n> Progress status is reported on the standard error stream\n> by default when it is attached to a terminal. This flag\n> enables progress reporting even if not attached to a\n> terminal. Can't use `--progress` together with `--porcelain`\n> or `--incremental`.\n\nFair enough; I dislike the `[no-]` formatting because it is harder to\nbuild into a search pattern (I have Vim keybindings to search manuals\nfor long and short options that it breaks), but I will probably live\nwith it and adjust my search patterns rather than complain further.\n\n\n>\n> As nobody complains that \"I cannot understand what --no-progress,\n> which is described in the above, means\", there must be a central\n> place where we describe this convention (\"git help cli\" talks about\n> negating options).\n>\n> So I suspect you'd only need to do something like this\n>\n> ---line-number::\n> +--[no-]line-number::\n> Prefix the line number ...\n>\n> in your patch, without doing anything else.\n>\n> Thanks.\n\nSounds like you would prefer a re-roll that does something similar for\n`--[no-]line-number` and `--[no-]column`? I suppose I have to\nwonder—for which Boolean options is it worth doing so?\n"},{"id":"511020","messageId":"xmqqjzanzy8k.fsf@gitster.g","threadId":"62818","inReplyTo":"CALnO6CBUbmZaL1NuG2RxrvuxbUexKdtKfgYi2jTDY3QEa9NQkA@mail.gmail.com","subject":"Re: [PATCH] grep: document negated line-number, column long options","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-21T20:51:55Z","receivedAt":"2025-01-21T20:51:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"D. Ben Knoble\" writes:\n\n>> $ git grep -e '^--\\[no-\\]' Documentation/\n>>\n>> An example entry (this is from blame-options.txt) looks like this.\n>>\n>> --[no-]progress::\n>> Progress status is reported on the standard error stream\n>> by default when it is attached to a terminal. This flag\n>> enables progress reporting even if not attached to a\n>> terminal. Can't use `--progress` together with `--porcelain`\n>> or `--incremental`.\n>\n> Fair enough; I dislike the `[no-]` formatting because it is harder to\n> build into a search pattern (I have Vim keybindings to search manuals\n> for long and short options that it breaks), but I will probably live\n> with it and adjust my search patterns rather than complain further.\n\n$ git grep -e '^[`]*--\\[no-\\]' -e '^[`]*--no-' Documentation/\n\ntells us that we also can write the above more like so:\n\n\t--progress::\n\t--no-progress::\n\t\tProgress status is reported ...\n\nwhich may make it more palatable? I didn't count and sift the hits\ninto two bin to see which style is more prevalent, but it may not be\na bad idea to consider unifying into one style.\n\n> Sounds like you would prefer a re-roll that does something similar for\n> `--[no-]line-number` and `--[no-]column`? I suppose I have to\n> wonder—for which Boolean options is it worth doing so?\n\nOnes that are not marked with OPT_NONEG all take --no- variant, and\nwhile going through the list of options we may realize some of them\nshould *not* take negated forms. They all commonly share that\n\"giving --no-opt countermands an earlier --opt or the corresponding\nconfiguration variable setting\", and any \"--opt\" that has its own\ncorresponding configuration variable should already have the variable\ndocumented in the paragraph, the body text may not have to be updated\nat all in the best case (in other words, the only change required may\nbe to add lines of \"--no-foo::\" form next to existing \"--foo::\".\n\nThanks.\n\n"}]}