| Message ID | xmqqzfjqmbza.fsf@gitster.g (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 4ad47d2de3cf71686a0dffcdda069cbd202938bd |
| Headers | show |
| Series | [v2] gitcli: document that command line trumps config and env | expand |
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" <sandals@crustytoothpaste.net> writes: > 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. OK, thanks. Let's merge it down to 'next', then.
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
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 <gitster@pobox.com> --- * 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(+)