From 1bc1e940918cd44cc78bff1dfd518e16fc5bad57 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Mon, 25 Nov 2024 12:14:01 +0900 Subject: doc: option value may be separate for valid reasons Even though `git help cli` recommends users to prefer using "--option=value" over "--option value", there can be reasons why giving them separately is a good idea. One reason is that shells do not perform tilde expansion for `--option=~/path/name` but they expand `--options ~/path/name` just fine. This is not a problem for many options whose option parsing is properly written using OPT_FILENAME(), because the value given to OPT_FILENAME() is tilde-expanded internally by us, but some commands take a pathname as a mere string, which needs this trick to have the shell help us. I think the reason we originally decided to recommend the stuck form was because an option that takes an optional value requires you to use it in the stuck form, and it is one less thing for users to worry about if they get into the habit to always use the stuck form. But we should be discouraging ourselves from adding an option with an optional value in the first place, and we might want to weaken the current recommendation. In any case, let's describe this one case where it is necessary to use the separate form, with an example. Reviewed-by: Eric Sunshine Signed-off-by: Junio C Hamano --- Documentation/gitcli.txt | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'Documentation/gitcli.txt') diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 7c709324ba..bd62cbd043 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -90,6 +90,15 @@ scripting Git: for long options. An option that takes optional option-argument must be written in the 'stuck' form. + * Despite the above suggestion, when Arg is a path relative to the + home directory of a user, e.g. ~/directory/file or ~u/d/f, you + may want to use the separate form, e.g. `git foo --file ~/mine`, + not `git foo --file=~/mine`. The shell will expand `~/` in the + former to your home directory, but most shells keep the tilde in + the latter. Some of our commands know how to tilde-expand the + option value even when given in the stuck form, but not all of + them do. + * When you give a revision parameter to a command, make sure the parameter is not ambiguous with a name of a file in the work tree. E.g. do not write `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work -- cgit v1.3 From b67a603f6360051f174a00f8d10dc088dc7093be Mon Sep 17 00:00:00 2001 From: Martin Ågren Date: Fri, 3 Jan 2025 12:33:31 +0100 Subject: gitcli.txt: typeset pathnames as monospace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Commit 1bc1e94091 (doc: option value may be separate for valid reasons, 2024-11-25) added a paragraph discussing tilde-expansion of, e.g., ~/directory/file. The tilde character has a special meaning to asciidoc tools. In this particular case, AsciiDoc matches up the two tildes in "e.g. ~/directory/file or ~u/d/f" and sets the text between them using subscript. In the manpage, where subscripting is not possible, this renders as "e.g. /directory/file oru/d/f". These paths are literal values, which our coding guidelines want typeset as verbatim using backticks. Do that. One effect of this is indeed that the asciidoc tools stop interpreting tilde and other special characters. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano --- Documentation/gitcli.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/gitcli.txt') diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index bd62cbd043..fcd86d2eee 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -91,7 +91,7 @@ scripting Git: written in the 'stuck' form. * Despite the above suggestion, when Arg is a path relative to the - home directory of a user, e.g. ~/directory/file or ~u/d/f, you + home directory of a user, e.g. `~/directory/file` or `~u/d/f`, you may want to use the separate form, e.g. `git foo --file ~/mine`, not `git foo --file=~/mine`. The shell will expand `~/` in the former to your home directory, but most shells keep the tilde in -- cgit v1.3 From 4ad47d2de3cf71686a0dffcdda069cbd202938bd Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Thu, 16 Jan 2025 18:05:13 -0800 Subject: gitcli: document that command line trumps config and env 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 Acked-by: brian m. carlson Signed-off-by: Junio C Hamano --- Documentation/gitcli.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'Documentation/gitcli.txt') 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=` +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 -- cgit v1.3