Re: [PATCH] grep: document negated line-number, column long options
From: Junio C Hamano <hidden>
Date: 2025-01-17 00:29:49
Junio C Hamano [off-list ref] 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 <redacted> --- 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