Subject: [PATCH v2] gitcli: document that command line trumps config and env

From: Junio C Hamano <[email-masked]>
Date: Thu, 16 Jan 2025 18:05:13 -0800

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.

Signed-off-by: Junio C Hamano <[email-masked]>
---
 * 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(+)

diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 7c709324ba..00b71bc462 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -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
-- 
2.48.1-210-gaa1682cadd