Junio C Hamano <gitster@xxxxxxxxx> 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@xxxxxxxxx>
---
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
