| Message ID | 5c58db3bb2189f3b4193a682aa3b43f3bfa95796.1657234914.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | config: introduce discovery.bare and protected config | expand |
"Glen Choo via GitGitGadget" <gitgitgadget@gmail.com> writes: > From: Glen Choo <chooglen@google.com> > > In a subsequent commit, we will introduce "protected configuration", > which is easiest to describe in terms of configuration scopes (i.e. it's > the union of the 'system', 'global', and 'command' scopes). This > description is fine for ML discussions, but it's inadequate for end > users because we don't provide a good description of "configuration > scopes" in the public docs. > > 145d59f482 (config: add '--show-scope' to print the scope of a config > value, 2020-02-10) introduced the word "scope" to our public docs, but > that only enumerates the scopes and assumes the user can figure out > those values mean. Probably: "figure out those values mean" -> "figure out what those values mean" > Add a SCOPES section to Documentation/git-config.txt that describes the > configuration scopes, their corresponding CLI options, and mentions that > some configuration options are only respected in certain scopes. Then, > use the word "scope" to simplify the FILES section and change some > confusing wording. > > Signed-off-by: Glen Choo <chooglen@google.com> > --- > Documentation/git-config.txt | 65 ++++++++++++++++++++++++++++-------- > 1 file changed, 51 insertions(+), 14 deletions(-) > > diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt > index 9376e39aef2..c4ce61a0493 100644 > --- a/Documentation/git-config.txt > +++ b/Documentation/git-config.txt > @@ -297,8 +297,8 @@ The default is to use a pager. > FILES > ----- > > -If not set explicitly with `--file`, there are four files where > -'git config' will search for configuration options: > +By default, 'git config' will read configuration options from multiple > +files: > > $(prefix)/etc/gitconfig:: > System-wide configuration file. > @@ -322,27 +322,64 @@ $GIT_DIR/config.worktree:: > This is optional and is only searched when > `extensions.worktreeConfig` is present in $GIT_DIR/config. > > -If no further options are given, all reading options will read all of these > -files that are available. If the global or the system-wide configuration > -file are not available they will be ignored. If the repository configuration > -file is not available or readable, 'git config' will exit with a non-zero > -error code. However, in neither case will an error message be issued. > +You may also provide additional configuration parameters when running any > +git command by using the `-c` option. See linkgit:git[1] for details. Listing "-c" as another one in addition to these files is probably a good simplification, instead of "-c override others" in the original, as we would need to say "more specific ones override less specific ones" anyway. > +Options will be read from all of these files that are available. If the > +global or the system-wide configuration file are not available they will be > +ignored. If the repository configuration file is not available or readable, > +'git config' will exit with a non-zero error code. Note that neither case > +produces an error message. Problem inherited from the original, but I suspect that rephrasing "not available" to "missing" (or "does not exist") may make it easier to follow. Also, "global" in the preceding description is explained as one of the user-specific configuration files, so it may be better to avoid it, e.g. If the user-specific or the system-wide configuration files are missing, they will be ignored. If the repository configuration file is missing or unreadable, ... Alternatively, we may want to tighten the description of $XDG_CONFIG_HOME/git/config and ~/.gitconfig a bit better, e.g. something along the lines of ... $XDG_CONFIG_HOME/git/config:: $HOME/.gitconfig:: User-specific configuration file. When the XDG_CONFIG_HOME environment variable is not set or empty, $HOME/.config/ is used as $XDG_CONFIG_HOME. + These are often called the "global" configuration file. When either or both of them exist(s), both files are read. Note that I deliberately omitted the mehtion that our $XDG support may be too recent and $HOME/.gitconfig may be preferred for portability. It came from 21cf3227 (config: read (but not write) from $XDG_CONFIG_HOME/git/config file, 2012-06-22) but sufficient number of years have passed. Also note that I originally wrote the following immediately after the above + When writing to the "--global" scope (see below), $XDG_CONFIG_HOME/git/config is used if it exists; otherwise $HOME/.gitconfig is used. but decided to discard it, since the OPTIONS -> "--global" covers it well enough. With a tightening of the definition of what "global" is,, we can rephrase "If the global or the system configuration files are missing...". > +You can limit which configuration sources are read from or written to by > +specifying the path of a file with the `--file` option, or by specifying a > +configuration scope with `--system`, `--global`, `--local`, or `--worktree`. > +For more, see <<OPTIONS>> above. > + > +SCOPES > +------ > + > +Each configuration source falls within a configuration scope. The scopes > +are: > + > +system:: > + $(prefix)/etc/gitconfig > + > +global:: > + $XDG_CONFIG_HOME/git/config > ++ > +~/.gitconfig > + > +local:: > + $GIT_DIR/config > + > +worktree:: > + $GIT_DIR/config.worktree > + > +command:: > + environment variables We'd need to tighten this a bit, like: GIT_CONFIG_{COUNT,KEY,VALUE} environment varialbes (see below) GIT_CONFIG_GLOBAL or GIT_CONFIG_SYSTEM environment varialbes and others are listed in the ENVIRONMENT section that comes after this section, but you do not want the readers to be confused into thinking that we'd give them more precedence over others. > ++ > +the `-c` option > +With the exception of 'command', each scope corresponds to a command line > +option: `--system`, `--global`, `--local`, `--worktree`. > + > +When reading options, specifying a scope will only read options from the > +files within that scope. When writing options, specifying a scope will write > +to the files within that scope (instead of the repository specific > +configuration file). See <<OPTIONS>> above for a complete description. > > +Most configuration options are respected regardless of the scope it is > +defined in, but some options are only respected in certain scopes. See the > +respective option's documentation for the full details. > > ENVIRONMENT > ----------- Overall it was a pleasant read. Thanks, will queue.
Junio C Hamano <gitster@pobox.com> writes: > "Glen Choo via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> From: Glen Choo <chooglen@google.com> >> >> In a subsequent commit, we will introduce "protected configuration", >> which is easiest to describe in terms of configuration scopes (i.e. it's >> the union of the 'system', 'global', and 'command' scopes). This >> description is fine for ML discussions, but it's inadequate for end >> users because we don't provide a good description of "configuration >> scopes" in the public docs. >> >> 145d59f482 (config: add '--show-scope' to print the scope of a config >> value, 2020-02-10) introduced the word "scope" to our public docs, but >> that only enumerates the scopes and assumes the user can figure out >> those values mean. > > Probably: "figure out those values mean" -> "figure out what those > values mean" > >> Add a SCOPES section to Documentation/git-config.txt that describes the >> configuration scopes, their corresponding CLI options, and mentions that >> some configuration options are only respected in certain scopes. Then, >> use the word "scope" to simplify the FILES section and change some >> confusing wording. >> >> Signed-off-by: Glen Choo <chooglen@google.com> >> --- >> Documentation/git-config.txt | 65 ++++++++++++++++++++++++++++-------- >> 1 file changed, 51 insertions(+), 14 deletions(-) >> >> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt >> index 9376e39aef2..c4ce61a0493 100644 >> --- a/Documentation/git-config.txt >> +++ b/Documentation/git-config.txt >> @@ -297,8 +297,8 @@ The default is to use a pager. >> FILES >> ----- >> >> -If not set explicitly with `--file`, there are four files where >> -'git config' will search for configuration options: >> +By default, 'git config' will read configuration options from multiple >> +files: >> >> $(prefix)/etc/gitconfig:: >> System-wide configuration file. >> @@ -322,27 +322,64 @@ $GIT_DIR/config.worktree:: >> This is optional and is only searched when >> `extensions.worktreeConfig` is present in $GIT_DIR/config. >> >> -If no further options are given, all reading options will read all of these >> -files that are available. If the global or the system-wide configuration >> -file are not available they will be ignored. If the repository configuration >> -file is not available or readable, 'git config' will exit with a non-zero >> -error code. However, in neither case will an error message be issued. >> +You may also provide additional configuration parameters when running any >> +git command by using the `-c` option. See linkgit:git[1] for details. > > Listing "-c" as another one in addition to these files is probably a > good simplification, instead of "-c override others" in the original, > as we would need to say "more specific ones override less specific > ones" anyway. > >> +Options will be read from all of these files that are available. If the >> +global or the system-wide configuration file are not available they will be >> +ignored. If the repository configuration file is not available or readable, >> +'git config' will exit with a non-zero error code. Note that neither case >> +produces an error message. > > Problem inherited from the original, but I suspect that rephrasing > "not available" to "missing" (or "does not exist") may make it > easier to follow. Also, "global" in the preceding description is > explained as one of the user-specific configuration files, so it may > be better to avoid it, e.g. > > If the user-specific or the system-wide configuration files > are missing, they will be ignored. If the repository > configuration file is missing or unreadable, ... > > Alternatively, we may want to tighten the description of > $XDG_CONFIG_HOME/git/config and ~/.gitconfig a bit better, > e.g. something along the lines of ... > > $XDG_CONFIG_HOME/git/config:: > $HOME/.gitconfig:: > User-specific configuration file. When the > XDG_CONFIG_HOME environment variable is not set or > empty, $HOME/.config/ is used as $XDG_CONFIG_HOME. > + > These are often called the "global" configuration file. > When either or both of them exist(s), both files are read. > > Note that I deliberately omitted the mehtion that our $XDG support > may be too recent and $HOME/.gitconfig may be preferred for > portability. It came from 21cf3227 (config: read (but not write) > from $XDG_CONFIG_HOME/git/config file, 2012-06-22) but sufficient > number of years have passed. > > Also note that I originally wrote the following immediately after > the above > > + > When writing to the "--global" scope (see below), > $XDG_CONFIG_HOME/git/config is used if it exists; otherwise > $HOME/.gitconfig is used. > > but decided to discard it, since the OPTIONS -> "--global" covers > it well enough. > > With a tightening of the definition of what "global" is,, we can > rephrase "If the global or the system configuration files are > missing...". Makes sense. I think this is simpler and more coherent with your suggested changes. The only change I'd suggest is to expand "missing" -> "missing or unreadable". The original wording is "not available", which could be interpreted to cover both cases. We'd obviously also have to amend "not available or readable" accordingly. >> +You can limit which configuration sources are read from or written to by >> +specifying the path of a file with the `--file` option, or by specifying a >> +configuration scope with `--system`, `--global`, `--local`, or `--worktree`. >> +For more, see <<OPTIONS>> above. >> + >> +SCOPES >> +------ >> + >> +Each configuration source falls within a configuration scope. The scopes >> +are: >> + >> +system:: >> + $(prefix)/etc/gitconfig >> + >> +global:: >> + $XDG_CONFIG_HOME/git/config >> ++ >> +~/.gitconfig >> + >> +local:: >> + $GIT_DIR/config >> + >> +worktree:: >> + $GIT_DIR/config.worktree >> + >> +command:: >> + environment variables > > We'd need to tighten this a bit, like: > > GIT_CONFIG_{COUNT,KEY,VALUE} environment varialbes (see below) > > GIT_CONFIG_GLOBAL or GIT_CONFIG_SYSTEM environment varialbes and > others are listed in the ENVIRONMENT section that comes after this > section, but you do not want the readers to be confused into > thinking that we'd give them more precedence over others. Ah, good point. >> ++ >> +the `-c` option > >> +With the exception of 'command', each scope corresponds to a command line >> +option: `--system`, `--global`, `--local`, `--worktree`. >> + >> +When reading options, specifying a scope will only read options from the >> +files within that scope. When writing options, specifying a scope will write >> +to the files within that scope (instead of the repository specific >> +configuration file). See <<OPTIONS>> above for a complete description. >> >> +Most configuration options are respected regardless of the scope it is >> +defined in, but some options are only respected in certain scopes. See the >> +respective option's documentation for the full details. >> >> ENVIRONMENT >> ----------- > > Overall it was a pleasant read. Thanks, will queue. Thanks! Shall I apply your suggestions, or were you planning to apply them yourself?
Glen Choo <chooglen@google.com> writes: >> Problem inherited from the original, but I suspect that rephrasing >> "not available" to "missing" (or "does not exist") may make it >> easier to follow. >> ... > > The only change I'd suggest is to expand "missing" -> "missing or > unreadable". The original wording is "not available", which could be > interpreted to cover both cases. We'd obviously also have to amend > "not available or readable" accordingly. Probably. I wonder if we should document that we at least warn when a file we are expected to read exists but is not readable (instead of simply saying "is ignored"), but other than that I agree with you. > Thanks! Shall I apply your suggestions, or were you planning to apply > them yourself? Definitely not the latter ;-)
Junio C Hamano <gitster@pobox.com> writes: > Glen Choo <chooglen@google.com> writes: > >> Thanks! Shall I apply your suggestions, or were you planning to apply >> them yourself? > > Definitely not the latter ;-) ;) Ok, I'll give others some time to weigh in before rerolling.
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 9376e39aef2..c4ce61a0493 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -297,8 +297,8 @@ The default is to use a pager. FILES ----- -If not set explicitly with `--file`, there are four files where -'git config' will search for configuration options: +By default, 'git config' will read configuration options from multiple +files: $(prefix)/etc/gitconfig:: System-wide configuration file. @@ -322,27 +322,64 @@ $GIT_DIR/config.worktree:: This is optional and is only searched when `extensions.worktreeConfig` is present in $GIT_DIR/config. -If no further options are given, all reading options will read all of these -files that are available. If the global or the system-wide configuration -file are not available they will be ignored. If the repository configuration -file is not available or readable, 'git config' will exit with a non-zero -error code. However, in neither case will an error message be issued. +You may also provide additional configuration parameters when running any +git command by using the `-c` option. See linkgit:git[1] for details. + +Options will be read from all of these files that are available. If the +global or the system-wide configuration file are not available they will be +ignored. If the repository configuration file is not available or readable, +'git config' will exit with a non-zero error code. Note that neither case +produces an error message. The files are read in the order given above, with last value found taking precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used. -You may override individual configuration parameters when running any git -command by using the `-c` option. See linkgit:git[1] for details. - -All writing options will per default write to the repository specific +By default, options are only written to the repository specific configuration file. Note that this also affects options like `--replace-all` and `--unset`. *'git config' will only ever change one file at a time*. -You can override these rules using the `--global`, `--system`, -`--local`, `--worktree`, and `--file` command-line options; see -<<OPTIONS>> above. +You can limit which configuration sources are read from or written to by +specifying the path of a file with the `--file` option, or by specifying a +configuration scope with `--system`, `--global`, `--local`, or `--worktree`. +For more, see <<OPTIONS>> above. + +SCOPES +------ + +Each configuration source falls within a configuration scope. The scopes +are: + +system:: + $(prefix)/etc/gitconfig + +global:: + $XDG_CONFIG_HOME/git/config ++ +~/.gitconfig + +local:: + $GIT_DIR/config + +worktree:: + $GIT_DIR/config.worktree + +command:: + environment variables ++ +the `-c` option + +With the exception of 'command', each scope corresponds to a command line +option: `--system`, `--global`, `--local`, `--worktree`. + +When reading options, specifying a scope will only read options from the +files within that scope. When writing options, specifying a scope will write +to the files within that scope (instead of the repository specific +configuration file). See <<OPTIONS>> above for a complete description. +Most configuration options are respected regardless of the scope it is +defined in, but some options are only respected in certain scopes. See the +respective option's documentation for the full details. ENVIRONMENT -----------