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

["brian m. carlson" <sandals@crustytoothpaste.net>]

[-- Attachment #1: Type: text/plain, Size: 1705 bytes --]

On 2025-01-17 at 02:05:13, Junio C Hamano wrote:
> 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.

I appreciate you taking the time to document this.  I remember it coming
up recently on the list and it's good that we're writing this down and
documenting it.

This is useful not only for end users, but also new contributors who
might want to implement a feature or authors of other tools which
interact with Git, who will be able to write tooling that behaves in a
similar way on the first go-around.
-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]