git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / Atom feed
* [PATCH] git-config: update doc for --get with multiple values
@ 2013-07-03 18:27 John Keeping
  2013-07-03 18:32 ` Jeff King
  2013-07-03 18:47 ` Junio C Hamano
  0 siblings, 2 replies; 7+ messages in thread
From: John Keeping @ 2013-07-03 18:27 UTC (permalink / raw)
  To: git; +Cc: Jeff King, Junio C Hamano, John Keeping

Since commit 00b347d (git-config: do not complain about duplicate
entries, 2012-10-23), "git config --get" does not exit with an error if
there are multiple values for the specified key but instead returns the
last value.  Update the documentation to reflect this.

Signed-off-by: John Keeping <john@keeping.me.uk>
---
 Documentation/git-config.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 19a7be0..fbad05e 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -82,7 +82,7 @@ OPTIONS
 --get::
 	Get the value for a given key (optionally filtered by a regex
 	matching the value). Returns error code 1 if the key was not
-	found and error code 2 if multiple key values were found.
+	found and the last value if multiple key values were found.
 
 --get-all::
 	Like get, but does not fail if the number of values for the key
-- 
1.8.3.1.747.g77f7d3a

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] git-config: update doc for --get with multiple values
  2013-07-03 18:27 [PATCH] git-config: update doc for --get with multiple values John Keeping
@ 2013-07-03 18:32 ` Jeff King
  2013-07-03 18:47 ` Junio C Hamano
  1 sibling, 0 replies; 7+ messages in thread
From: Jeff King @ 2013-07-03 18:32 UTC (permalink / raw)
  To: John Keeping; +Cc: git, Junio C Hamano

On Wed, Jul 03, 2013 at 07:27:39PM +0100, John Keeping wrote:

> Since commit 00b347d (git-config: do not complain about duplicate
> entries, 2012-10-23), "git config --get" does not exit with an error if
> there are multiple values for the specified key but instead returns the
> last value.  Update the documentation to reflect this.

Thanks for catching this. Patch looks good.

There is another section later in the documentation which details the
various exit codes and what they mean. But it seems to have never
actually documented this case, so we don't need to update it. :)

-Peff

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] git-config: update doc for --get with multiple values
  2013-07-03 18:27 [PATCH] git-config: update doc for --get with multiple values John Keeping
  2013-07-03 18:32 ` Jeff King
@ 2013-07-03 18:47 ` Junio C Hamano
  2013-07-07  9:50   ` John Keeping
  1 sibling, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2013-07-03 18:47 UTC (permalink / raw)
  To: John Keeping; +Cc: git, Jeff King

John Keeping <john@keeping.me.uk> writes:

> Since commit 00b347d (git-config: do not complain about duplicate
> entries, 2012-10-23), "git config --get" does not exit with an error if
> there are multiple values for the specified key but instead returns the
> last value.  Update the documentation to reflect this.
>
> Signed-off-by: John Keeping <john@keeping.me.uk>
> ---
>  Documentation/git-config.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 19a7be0..fbad05e 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -82,7 +82,7 @@ OPTIONS
>  --get::
>  	Get the value for a given key (optionally filtered by a regex
>  	matching the value). Returns error code 1 if the key was not
> -	found and error code 2 if multiple key values were found.
> +	found and the last value if multiple key values were found.
>  
>  --get-all::
>  	Like get, but does not fail if the number of values for the key

Thanks.

I wondered if we should explain the significance of "last" a bit
more (like "this results in the value from the most specific
configuration file to be used, the ones in $GIT_DIR/config
overriding what is in $HOME/.gitconfig"), but I do not have a strong
opinion either way.  Let's queue this for 'maint' for now.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] git-config: update doc for --get with multiple values
  2013-07-03 18:47 ` Junio C Hamano
@ 2013-07-07  9:50   ` John Keeping
  2013-07-07 17:31     ` Junio C Hamano
  0 siblings, 1 reply; 7+ messages in thread
From: John Keeping @ 2013-07-07  9:50 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git, Jeff King

On Wed, Jul 03, 2013 at 11:47:50AM -0700, Junio C Hamano wrote:
> John Keeping <john@keeping.me.uk> writes:
> 
> > Since commit 00b347d (git-config: do not complain about duplicate
> > entries, 2012-10-23), "git config --get" does not exit with an error if
> > there are multiple values for the specified key but instead returns the
> > last value.  Update the documentation to reflect this.
> >
> > Signed-off-by: John Keeping <john@keeping.me.uk>
> > ---
> >  Documentation/git-config.txt | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> > index 19a7be0..fbad05e 100644
> > --- a/Documentation/git-config.txt
> > +++ b/Documentation/git-config.txt
> > @@ -82,7 +82,7 @@ OPTIONS
> >  --get::
> >  	Get the value for a given key (optionally filtered by a regex
> >  	matching the value). Returns error code 1 if the key was not
> > -	found and error code 2 if multiple key values were found.
> > +	found and the last value if multiple key values were found.
> >  
> >  --get-all::
> >  	Like get, but does not fail if the number of values for the key
> 
> Thanks.
> 
> I wondered if we should explain the significance of "last" a bit
> more (like "this results in the value from the most specific
> configuration file to be used, the ones in $GIT_DIR/config
> overriding what is in $HOME/.gitconfig"), but I do not have a strong
> opinion either way.  Let's queue this for 'maint' for now.

I don't think that change belongs here.  How about doing something like
this in the FILES section (the first two hunks are just reordering the
existing list, only the last hunk changes the content):

-- >8 --
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index fbad05e..99dc497 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -206,12 +206,8 @@ FILES
 If not set explicitly with '--file', there are four files where
 'git config' will search for configuration options:
 
-$GIT_DIR/config::
-	Repository specific configuration file.
-
-~/.gitconfig::
-	User-specific configuration file. Also called "global"
-	configuration file.
+$(prefix)/etc/gitconfig::
+	System-wide configuration file.
 
 $XDG_CONFIG_HOME/git/config::
 	Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
@@ -221,8 +217,12 @@ $XDG_CONFIG_HOME/git/config::
 	you sometimes use older versions of Git, as support for this
 	file was added fairly recently.
 
-$(prefix)/etc/gitconfig::
-	System-wide configuration file.
+~/.gitconfig::
+	User-specific configuration file. Also called "global"
+	configuration file.
+
+$GIT_DIR/config::
+	Repository specific configuration file.
 
 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
@@ -230,6 +230,10 @@ 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.
 
+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.
+
 All writing options will per default write 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*.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] git-config: update doc for --get with multiple values
  2013-07-07  9:50   ` John Keeping
@ 2013-07-07 17:31     ` Junio C Hamano
  2013-07-07 19:49       ` [PATCH] git-config(1): clarify precedence of " John Keeping
  0 siblings, 1 reply; 7+ messages in thread
From: Junio C Hamano @ 2013-07-07 17:31 UTC (permalink / raw)
  To: John Keeping; +Cc: git, Jeff King

John Keeping <john@keeping.me.uk> writes:

>> I wondered if we should explain the significance of "last" a bit
>> more (like "this results in the value from the most specific
>> configuration file to be used, the ones in $GIT_DIR/config
>> overriding what is in $HOME/.gitconfig"), but I do not have a strong
>> opinion either way.  Let's queue this for 'maint' for now.
>
> I don't think that change belongs here.  How about doing something like
> this in the FILES section (the first two hunks are just reordering the
> existing list, only the last hunk changes the content):

Sounds like a good change to me ;-).

> -- >8 --
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index fbad05e..99dc497 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -206,12 +206,8 @@ FILES
>  If not set explicitly with '--file', there are four files where
>  'git config' will search for configuration options:
>  
> -$GIT_DIR/config::
> -	Repository specific configuration file.
> -
> -~/.gitconfig::
> -	User-specific configuration file. Also called "global"
> -	configuration file.
> +$(prefix)/etc/gitconfig::
> +	System-wide configuration file.
>  
>  $XDG_CONFIG_HOME/git/config::
>  	Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
> @@ -221,8 +217,12 @@ $XDG_CONFIG_HOME/git/config::
>  	you sometimes use older versions of Git, as support for this
>  	file was added fairly recently.
>  
> -$(prefix)/etc/gitconfig::
> -	System-wide configuration file.
> +~/.gitconfig::
> +	User-specific configuration file. Also called "global"
> +	configuration file.
> +
> +$GIT_DIR/config::
> +	Repository specific configuration file.
>  
>  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
> @@ -230,6 +230,10 @@ 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.
>  
> +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.
> +
>  All writing options will per default write 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*.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH] git-config(1): clarify precedence of multiple values
  2013-07-07 17:31     ` Junio C Hamano
@ 2013-07-07 19:49       ` John Keeping
  2013-07-07 19:55         ` Jeff King
  0 siblings, 1 reply; 7+ messages in thread
From: John Keeping @ 2013-07-07 19:49 UTC (permalink / raw)
  To: Junio C Hamano; +Cc: git, Jeff King

In order to clarify which value is used when there are multiple values
defined for a key, re-order the list of file locations so that it runs
from least specific to most specific.  Then add a paragraph which simply
says that the last value will be used.

Signed-off-by: John Keeping <john@keeping.me.uk>
---
On Sun, Jul 07, 2013 at 10:31:38AM -0700, Junio C Hamano wrote:
> John Keeping <john@keeping.me.uk> writes:
> 
> >> I wondered if we should explain the significance of "last" a bit
> >> more (like "this results in the value from the most specific
> >> configuration file to be used, the ones in $GIT_DIR/config
> >> overriding what is in $HOME/.gitconfig"), but I do not have a strong
> >> opinion either way.  Let's queue this for 'maint' for now.
> >
> > I don't think that change belongs here.  How about doing something like
> > this in the FILES section (the first two hunks are just reordering the
> > existing list, only the last hunk changes the content):
> 
> Sounds like a good change to me ;-).

So here it is as a proper patch :-)

 Documentation/git-config.txt | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index fbad05e..99dc497 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -206,12 +206,8 @@ FILES
 If not set explicitly with '--file', there are four files where
 'git config' will search for configuration options:
 
-$GIT_DIR/config::
-	Repository specific configuration file.
-
-~/.gitconfig::
-	User-specific configuration file. Also called "global"
-	configuration file.
+$(prefix)/etc/gitconfig::
+	System-wide configuration file.
 
 $XDG_CONFIG_HOME/git/config::
 	Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
@@ -221,8 +217,12 @@ $XDG_CONFIG_HOME/git/config::
 	you sometimes use older versions of Git, as support for this
 	file was added fairly recently.
 
-$(prefix)/etc/gitconfig::
-	System-wide configuration file.
+~/.gitconfig::
+	User-specific configuration file. Also called "global"
+	configuration file.
+
+$GIT_DIR/config::
+	Repository specific configuration file.
 
 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
@@ -230,6 +230,10 @@ 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.
 
+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.
+
 All writing options will per default write 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*.
-- 
1.8.3.2.855.gbc9faed

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH] git-config(1): clarify precedence of multiple values
  2013-07-07 19:49       ` [PATCH] git-config(1): clarify precedence of " John Keeping
@ 2013-07-07 19:55         ` Jeff King
  0 siblings, 0 replies; 7+ messages in thread
From: Jeff King @ 2013-07-07 19:55 UTC (permalink / raw)
  To: John Keeping; +Cc: Junio C Hamano, git

On Sun, Jul 07, 2013 at 08:49:56PM +0100, John Keeping wrote:

> In order to clarify which value is used when there are multiple values
> defined for a key, re-order the list of file locations so that it runs
> from least specific to most specific.  Then add a paragraph which simply
> says that the last value will be used.

Makes sense.

>  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.
>  
> +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.

What order do the values come in --get-all?

If you read carefully, I think it is implied by the "files are read in
order given above", but it took me a minute to think about it. Maybe add
at the end:

  ...values of a key from all files will be shown, in the order the
  files are processed (least specific to most specific).

Or something (I do not like "least specific" because we have not
introduced that term earlier, but I can't think of another succinct way
to say it).

But even without that, the patch is certainly an improvement.

-Peff

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2013-07-07 19:55 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-07-03 18:27 [PATCH] git-config: update doc for --get with multiple values John Keeping
2013-07-03 18:32 ` Jeff King
2013-07-03 18:47 ` Junio C Hamano
2013-07-07  9:50   ` John Keeping
2013-07-07 17:31     ` Junio C Hamano
2013-07-07 19:49       ` [PATCH] git-config(1): clarify precedence of " John Keeping
2013-07-07 19:55         ` Jeff King

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for the project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git