environ: explain Boolean environment variables
Many environment variables use the git_env_bool() API to parse their values, and allow the usual "true/yes/on are true, false/no/off are false. In addition non-zero numbers are true and zero is false. An empty string is also false." set of values. Mark them as such, and consistently say "true" or "false", instead of random mixes of '1', '0', 'yes', 'true', etc. in their description. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Sep 15, 2022 at 09:06 UTC
80f0b3f397d6467cb6f6fc9456b867aaffdc9b8c
1 file changed
+18
-13
Documentation/git.txt
+18
-13
@@ -441,7 +441,12 @@ Please see linkgit:gitglossary[7].
441
442
Environment Variables
443
---------------------
444
-Various Git commands use the following environment variables:
444
+Various Git commands pay attention to environment variables and change
445
+their behavior. The environment variables marked as "Boolean" take
446
+their values the same way as Boolean valued configuration variables, e.g.
447
+"true", "yes", "on" and positive numbers are taken as "yes".
448
+
449
+Here are the variables:
450
451
The Git Repository
452
~~~~~~~~~~~~~~~~~~
@@ -513,7 +518,7 @@ double-quotes and respecting backslash escapes. E.g., the value
518
When run in a directory that does not have ".git" repository
519
directory, Git tries to find such a directory in the parent
520
directories to find the top of the working tree, but by default it
516
- does not cross filesystem boundaries. This environment variable
521
+ does not cross filesystem boundaries. This Boolean environment variable
522
can be set to true to tell Git not to stop at filesystem
523
boundaries. Like `GIT_CEILING_DIRECTORIES`, this will not affect
524
an explicit repository directory set via `GIT_DIR` or on the
@@ -678,7 +683,7 @@ for further details.
683
option in linkgit:git-config[1].
684
685
`GIT_TERMINAL_PROMPT`::
681
- If this environment variable is set to `0`, git will not prompt
686
+ If this Boolean environment variable is set to false, git will not prompt
687
on the terminal (e.g., when asking for HTTP authentication).
688
689
`GIT_CONFIG_GLOBAL`::
@@ -693,10 +698,10 @@ for further details.
698
699
`GIT_CONFIG_NOSYSTEM`::
700
Whether to skip reading settings from the system-wide
696
- `$(prefix)/etc/gitconfig` file. This environment variable can
701
+ `$(prefix)/etc/gitconfig` file. This Boolean environment variable can
702
be used along with `$HOME` and `$XDG_CONFIG_HOME` to create a
703
predictable environment for a picky script, or you can set it
699
- temporarily to avoid using a buggy `/etc/gitconfig` file while
704
+ to true to temporarily avoid using a buggy `/etc/gitconfig` file while
705
waiting for someone with sufficient permissions to fix it.
706
707
`GIT_FLUSH`::
@@ -840,11 +845,11 @@ for full details.
845
`GIT_TRACE_REDACT`::
846
By default, when tracing is activated, Git redacts the values of
847
cookies, the "Authorization:" header, the "Proxy-Authorization:"
843
- header and packfile URIs. Set this variable to `0` to prevent this
848
+ header and packfile URIs. Set this Boolean environment variable to false to prevent this
849
redaction.
850
851
`GIT_LITERAL_PATHSPECS`::
847
- Setting this variable to `1` will cause Git to treat all
852
+ Setting this Boolean environment variable to true will cause Git to treat all
853
pathspecs literally, rather than as glob patterns. For example,
854
running `GIT_LITERAL_PATHSPECS=1 git log -- '*.c'` will search
855
for commits that touch the path `*.c`, not any paths that the
@@ -853,15 +858,15 @@ for full details.
858
`git ls-tree`, `--raw` diff output, etc).
859
860
`GIT_GLOB_PATHSPECS`::
856
- Setting this variable to `1` will cause Git to treat all
861
+ Setting this Boolean environment variable to true will cause Git to treat all
862
pathspecs as glob patterns (aka "glob" magic).
863
864
`GIT_NOGLOB_PATHSPECS`::
860
- Setting this variable to `1` will cause Git to treat all
865
+ Setting this Boolean environment variable to true will cause Git to treat all
866
pathspecs as literal (aka "literal" magic).
867
868
`GIT_ICASE_PATHSPECS`::
864
- Setting this variable to `1` will cause Git to treat all
869
+ Setting this Boolean environment variable to true will cause Git to treat all
870
pathspecs as case-insensitive.
871
872
`GIT_REFLOG_ACTION`::
@@ -875,7 +880,7 @@ for full details.
880
end user, to be recorded in the body of the reflog.
881
882
`GIT_REF_PARANOIA`::
878
- If set to `0`, ignore broken or badly named refs when iterating
883
+ If this Boolean environment variable is set to false, ignore broken or badly named refs when iterating
884
over lists of refs. Normally Git will try to include any such
885
refs, which may cause some operations to fail. This is usually
886
preferable, as potentially destructive operations (e.g.,
@@ -894,7 +899,7 @@ for full details.
899
`protocol.allow` in linkgit:git-config[1] for more details.
900
901
`GIT_PROTOCOL_FROM_USER`::
897
- Set to 0 to prevent protocols used by fetch/push/clone which are
902
+ Set this Boolean environment variable to false to prevent protocols used by fetch/push/clone which are
903
configured to the `user` state. This is useful to restrict recursive
904
submodule initialization from an untrusted repository or for programs
905
which feed potentially-untrusted URLS to git commands. See
@@ -922,7 +927,7 @@ only affects clones and fetches; it is not yet used for pushes (but may
927
be in the future).
928
929
`GIT_OPTIONAL_LOCKS`::
925
- If set to `0`, Git will complete any requested operation without
930
+ If this Boolean environment variable is set to false, Git will complete any requested operation without
931
performing any optional sub-operations that require taking a lock.
932
For example, this will prevent `git status` from refreshing the
933
index as a side effect. This is useful for processes running in