Re: push.default documented in "man git-push"?
David Glasser wrote: > Is the newish push.default documented in the "git push" manpage > anywhere? I don't see it mentioned (and there are several references > to the "default" behavior), but maybe I'm missing something. Is it > left out on purpose (ie, config values aren't supposed to be mentioned > in command manpages)? You're right. It's documented in `man git-config`, but we should probably mention it in the `git-push` manpage. --8<-- From: Ramkumar Ramachandra Date: Tue, 2 Oct 2012 20:37:13 +0530 Subject: [PATCH] Documentation: mention `push.default` in git-push.txt Signed-off-by: Ramkumar Ramachandra --- Documentation/git-push.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index cb97cc1..8751b38 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -37,7 +37,8 @@ OPTIONS[[OPTIONS]] `+`, followed by the source ref , followed by a colon `:`, followed by the destination ref . It is used to specify with what object the ref - in the remote repository is to be updated. + in the remote repository is to be updated. If not specified, + the configuration variable `push.default` is used. + The is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or -- 1.7.12.1.428.g652398a.dirty -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Thanks Rankumar! There's also the reference in the "git push origin" example and the "This is the default operation mode if no explicit refspec is found". (I would have sent my own patch but I can't figure out where the syntax for the manpages is documented.) --dave On Tue, Oct 2, 2012 at 8:09 AM, Ramkumar Ramachandra wrote: > David Glasser wrote: >> Is the newish push.default documented in the "git push" manpage >> anywhere? I don't see it mentioned (and there are several references >> to the "default" behavior), but maybe I'm missing something. Is it >> left out on purpose (ie, config values aren't supposed to be mentioned >> in command manpages)? > > You're right. It's documented in `man git-config`, but we should > probably mention it in the `git-push` manpage. > > --8<-- > From: Ramkumar Ramachandra > Date: Tue, 2 Oct 2012 20:37:13 +0530 > Subject: [PATCH] Documentation: mention `push.default` in git-push.txt > > Signed-off-by: Ramkumar Ramachandra > --- > Documentation/git-push.txt | 3 ++- > 1 file changed, 2 insertions(+), 1 deletion(-) > > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt > index cb97cc1..8751b38 100644 > --- a/Documentation/git-push.txt > +++ b/Documentation/git-push.txt > @@ -37,7 +37,8 @@ OPTIONS[[OPTIONS]] > `+`, followed by the source ref , followed > by a colon `:`, followed by the destination ref . > It is used to specify with what object the ref > - in the remote repository is to be updated. > + in the remote repository is to be updated. If not specified, > + the configuration variable `push.default` is used. > + > The is often the name of the branch you would want to push, but > it can be any arbitrary "SHA-1 expression", such as `master~4` or > -- > 1.7.12.1.428.g652398a.dirty -- glas...@davidglasser.net | langtonlabs.org | flickr.com/photos/glasser/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Ramkumar Ramachandra writes: > David Glasser wrote: >> Thanks Rankumar! There's also the reference in the "git push origin" >> example and the "This is the default operation mode if no explicit >> refspec is found". > > Sorry; here's a revised patch. Sounds good, thanks (resend and Cc Junio if needed). -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Matthieu Moy wrote: > Ramkumar Ramachandra writes: > >> David Glasser wrote: >>> Thanks Rankumar! There's also the reference in the "git push origin" >>> example and the "This is the default operation mode if no explicit >>> refspec is found". >> >> Sorry; here's a revised patch. > > Sounds good, thanks (resend and Cc Junio if needed). +CC: Junio Please add a Reported-by: David Glasser Ram -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Matthieu Moy writes: > Ramkumar Ramachandra writes: > >> David Glasser wrote: >>> Thanks Rankumar! There's also the reference in the "git push origin" >>> example and the "This is the default operation mode if no explicit >>> refspec is found". >> >> Sorry; here's a revised patch. > > Sounds good, thanks (resend and Cc Junio if needed). That's an Ack? -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Junio C Hamano writes: > Matthieu Moy writes: > >> Ramkumar Ramachandra writes: >> >>> David Glasser wrote: Thanks Rankumar! There's also the reference in the "git push origin" example and the "This is the default operation mode if no explicit refspec is found". >>> >>> Sorry; here's a revised patch. >> >> Sounds good, thanks (resend and Cc Junio if needed). > > That's an Ack? Yes. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Ramkumar Ramachandra writes: > David Glasser wrote: >> Thanks Rankumar! There's also the reference in the "git push origin" >> example and the "This is the default operation mode if no explicit >> refspec is found". > > Sorry; here's a revised patch. > > --8<-- FYI: the above is not a scissors line. > From: Ramkumar Ramachandra > Date: Tue, 2 Oct 2012 21:06:05 +0530 > Subject: [PATCH] Documentation: mention `push.default` in git-push.txt > > Signed-off-by: Ramkumar Ramachandra > --- > Documentation/git-push.txt | 8 +--- > 1 file changed, 5 insertions(+), 3 deletions(-) > > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt > index cb97cc1..e1e9aca 100644 > --- a/Documentation/git-push.txt > +++ b/Documentation/git-push.txt > @@ -37,7 +37,8 @@ OPTIONS[[OPTIONS]] > `+`, followed by the source ref , followed > by a colon `:`, followed by the destination ref . > It is used to specify with what object the ref > - in the remote repository is to be updated. > + in the remote repository is to be updated. If not specified, > + the configuration variable `push.default` is used. I think this is way suboptimal; it is begging users to do this [push] default = frotz:xyzzy by making it sound as if push.default gives a default for . > @@ -65,7 +66,8 @@ directs git to push "matching" branches: for every > branch that > the local side, the remote side is updated if a branch of the same name > already exists on the remote side. This is the default operation mode > if no explicit refspec is found (that is neither on the command line > -nor in any Push line of the corresponding remotes file---see below). > +nor in any Push line of the corresponding remotes file, or `push.default` > +---see below). Likewise. The added part should not be inside the parentheses, which is about what the value used for refspec. `push.default` is about what happens when there is _no_ refspec. I'll queue this instead. Thanks. -- >8 -- From: Ramkumar Ramachandra Date: Tue, 2 Oct 2012 21:08:00 +0530 Subject: [PATCH] Documentation: mention `push.default` in git-push.txt It already is listed in the "git config" documentation, but people interested in pushing would first look at "git push" documentation. Noticed-by: David Glasser Signed-off-by: Ramkumar Ramachandra Acked-by: Matthieu Moy Fixed-by: Junio C Hamano Signed-off-by: Junio C Hamano --- Documentation/git-push.txt | 10 +++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index cb97cc1..70b18bc 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -37,7 +37,9 @@ OPTIONS[[OPTIONS]] `+`, followed by the source ref , followed by a colon `:`, followed by the destination ref . It is used to specify with what object the ref - in the remote repository is to be updated. + in the remote repository is to be updated. If not specified, + the behavior of the command is controled by the `push.default` + configuration variable. + The is often the name of the branch you would want to push, but it can be any arbitrary "SHA-1 expression", such as `master~4` or @@ -65,7 +67,8 @@ directs git to push "matching" branches: for every branch that exists on the local side, the remote side is updated if a branch of the same name already exists on the remote side. This is the default operation mode if no explicit refspec is found (that is neither on the command line -nor in any Push line of the corresponding remotes file---see below). +nor in any Push line of the corresponding remotes file---see below) and +no `push.default` configuration variable is set. --all:: Instead of naming each ref to push, specifies that all @@ -357,7 +360,8 @@ Examples `git push origin :`. + The default behavior of this command when no is given can be -configured by setting the `push` option of the remote. +configured by setting the `push` option of the remote, or the `push.default` +configuration variable. + For example, to default to pushing only the current branch to `origin` use `git config remote.origin.push HEAD`. Any valid (like -- 1.8.0.rc0.45.g7ce8dc5 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Thanks Junio! Note that I think the word is usually spelled "controlled" not "controled". On Tue, Oct 2, 2012 at 11:34 AM, Junio C Hamano wrote: > Ramkumar Ramachandra writes: > >> David Glasser wrote: >>> Thanks Rankumar! There's also the reference in the "git push origin" >>> example and the "This is the default operation mode if no explicit >>> refspec is found". >> >> Sorry; here's a revised patch. >> >> --8<-- > > FYI: the above is not a scissors line. > >> From: Ramkumar Ramachandra >> Date: Tue, 2 Oct 2012 21:06:05 +0530 >> Subject: [PATCH] Documentation: mention `push.default` in git-push.txt >> >> Signed-off-by: Ramkumar Ramachandra >> --- >> Documentation/git-push.txt | 8 +--- >> 1 file changed, 5 insertions(+), 3 deletions(-) >> >> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt >> index cb97cc1..e1e9aca 100644 >> --- a/Documentation/git-push.txt >> +++ b/Documentation/git-push.txt >> @@ -37,7 +37,8 @@ OPTIONS[[OPTIONS]] >> `+`, followed by the source ref , followed >> by a colon `:`, followed by the destination ref . >> It is used to specify with what object the ref >> - in the remote repository is to be updated. >> + in the remote repository is to be updated. If not specified, >> + the configuration variable `push.default` is used. > > I think this is way suboptimal; it is begging users to do this > > [push] > default = frotz:xyzzy > > by making it sound as if push.default gives a default for . > >> @@ -65,7 +66,8 @@ directs git to push "matching" branches: for every >> branch that >> the local side, the remote side is updated if a branch of the same name >> already exists on the remote side. This is the default operation mode >> if no explicit refspec is found (that is neither on the command line >> -nor in any Push line of the corresponding remotes file---see below). >> +nor in any Push line of the corresponding remotes file, or `push.default` >> +---see below). > > Likewise. The added part should not be inside the parentheses, > which is about what the value used for refspec. `push.default` is > about what happens when there is _no_ refspec. > > I'll queue this instead. Thanks. > > -- >8 -- > From: Ramkumar Ramachandra > Date: Tue, 2 Oct 2012 21:08:00 +0530 > Subject: [PATCH] Documentation: mention `push.default` in git-push.txt > > It already is listed in the "git config" documentation, but people > interested in pushing would first look at "git push" documentation. > > Noticed-by: David Glasser > Signed-off-by: Ramkumar Ramachandra > Acked-by: Matthieu Moy > Fixed-by: Junio C Hamano > Signed-off-by: Junio C Hamano > --- > Documentation/git-push.txt | 10 +++--- > 1 file changed, 7 insertions(+), 3 deletions(-) > > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt > index cb97cc1..70b18bc 100644 > --- a/Documentation/git-push.txt > +++ b/Documentation/git-push.txt > @@ -37,7 +37,9 @@ OPTIONS[[OPTIONS]] > `+`, followed by the source ref , followed > by a colon `:`, followed by the destination ref . > It is used to specify with what object the ref > - in the remote repository is to be updated. > + in the remote repository is to be updated. If not specified, > + the behavior of the command is controled by the `push.default` > + configuration variable. > + > The is often the name of the branch you would want to push, but > it can be any arbitrary "SHA-1 expression", such as `master~4` or > @@ -65,7 +67,8 @@ directs git to push "matching" branches: for every branch > that exists on > the local side, the remote side is updated if a branch of the same name > already exists on the remote side. This is the default operation mode > if no explicit refspec is found (that is neither on the command line > -nor in any Push line of the corresponding remotes file---see below). > +nor in any Push line of the corresponding remotes file---see below) and > +no `push.default` configuration variable is set. > > --all:: > Instead of naming each ref to push, specifies that all > @@ -357,7 +360,8 @@ Examples > `git push origin :`. > + > The default behavior of this command when no is given can be > -configured by setting the `push` option of the remote. > +configured by setting the `push` option of the remote, or the `push.default` > +configuration variable. > + > For example, to default to pushing only the current branch to `origin` > use `git config remote.origin.push HEAD`. Any valid (like > -- > 1.8.0.rc0.45.g7ce8dc5 > -- glas...@davidglasser.net | langtonlabs.org | flickr.com/photos/glasser/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
David Glasser writes: > Thanks Junio! Note that I think the word is usually spelled > "controlled" not "controled". Thanks; I cannot spelll... -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Junio C Hamano writes: > I'll queue this instead. Thanks. Even better, perfect! -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Tue, Oct 2, 2012 at 10:09 PM, Ramkumar Ramachandra wrote: > David Glasser wrote: >> Is the newish push.default documented in the "git push" manpage >> anywhere? I don't see it mentioned (and there are several references >> to the "default" behavior), but maybe I'm missing something. Is it >> left out on purpose (ie, config values aren't supposed to be mentioned >> in command manpages)? > > You're right. It's documented in `man git-config`, but we should > probably mention it in the `git-push` manpage. Your patch is fine. I'm just thinking whether it's a good idea to add a section in the end of each command's man page to list all relevant config keys to that command, somewhat similar to "see also" section. It may help finding useful config keys that otherwise hard to find. -- Duy -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Wed, Oct 3, 2012 at 3:17 PM, Ramkumar Ramachandra wrote: > Hi Duy, > > Nguyen Thai Ngoc Duy wrote: >> Your patch is fine. I'm just thinking whether it's a good idea to add >> a section in the end of each command's man page to list all relevant >> config keys to that command, somewhat similar to "see also" section. >> It may help finding useful config keys that otherwise hard to find. > > That sounds like a good idea. Would you like to write the first patch > (for git-push)? I won't be able to do it in the next 4 hours. If you want a stab at it, go ahead. -- Duy -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
[+CC: Junio, for comments] Nguyen Thai Ngoc Duy wrote: > On Wed, Oct 3, 2012 at 3:17 PM, Ramkumar Ramachandra > wrote: >> Hi Duy, >> >> Nguyen Thai Ngoc Duy wrote: >>> Your patch is fine. I'm just thinking whether it's a good idea to add >>> a section in the end of each command's man page to list all relevant >>> config keys to that command, somewhat similar to "see also" section. >>> It may help finding useful config keys that otherwise hard to find. >> >> That sounds like a good idea. Would you like to write the first patch >> (for git-push)? > > I won't be able to do it in the next 4 hours. If you want a stab at > it, go ahead. On second thought, it might not be such a good idea. There are *lots* of variables that control the operation of each command, and it's hard to decide which ones to list and which ones to omit. I've listed all the relevant variables for git-push, except the advice.* variables- I don't know how useful such a long list might be. Signed-off-by: Ramkumar Ramachandra -- 8< -- diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index cb97cc1..0a1c8d2 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -426,6 +426,30 @@ Commits A and B would no longer belong to a branch with a symbolic name, and so would be unreachable. As such, these commits would be removed by a `git gc` command on the origin repository. +Configuration variables +--- + +These configuration variables affect the operation of git-push in +various ways. For more information see linkgit:git-config[1]. + +branch..remote +core.gitProxy +http.proxy +push.default +receive.autogc +receive.denyCurrentBranch +receive.denyDeleteCurrent +receive.denyDeletes +receive.denyNonFastForwards +receive.unpackLimit +receive.updateserverinfo +remote..mirror +remote..proxy +remote..push +remote..pushurl +remote..receivepack +remote..url + GIT --- Part of the linkgit:git[1] suite -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Junio C Hamano wrote: > Ramkumar Ramachandra writes: >> [...] >> --8<-- > > FYI: the above is not a scissors line. Excerpt from git-mailinfo[1]: --scissors:: Remove everything in body before a scissors line. A line that mainly consists of scissors (either ">8" or "8<") and perforation (dash "-") marks is called a scissors line, and is used to request the reader to cut the message at that line. If such a line appears in the body of the message before the patch, everything before it (including the scissors line itself) is ignored when this option is used. Does it need to be updated to say that a space is required between the perforation and the scissors? Ram -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Wed, Oct 3, 2012 at 3:46 PM, Ramkumar Ramachandra wrote: > On second thought, it might not be such a good idea. There are *lots* > of variables that control the operation of each command, and it's hard > to decide which ones to list and which ones to omit. I've listed all > the relevant variables for git-push, except the advice.* variables- I > don't know how useful such a long list might be. I think listing receive.* and advice.* (and maybe even remove..*) is still ok. The goal is to give users a clue. They'll need to look up in config.txt anyway for explanation. If we name the config keys (and groups) well then users should be able to guess what those keys may be for before deciding whether to look into details. -- Duy -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Nguyen Thai Ngoc Duy: I'm just thinking whether it's a good idea to add a section in the end of each command's man page to list all relevant config keys to that command, somewhat similar to "see also" section. Yes, please. Discoverability of configuration settings is not very good at the moment. -- \\// Peter - http://www.softwolves.pp.se/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Nguyen Thai Ngoc Duy writes: > On Wed, Oct 3, 2012 at 3:46 PM, Ramkumar Ramachandra > wrote: >> On second thought, it might not be such a good idea. There are *lots* >> of variables that control the operation of each command, and it's hard >> to decide which ones to list and which ones to omit. I've listed all >> the relevant variables for git-push, except the advice.* variables- I >> don't know how useful such a long list might be. > > I think listing receive.* and advice.* (and maybe even > remove..*) is still ok. The goal is to give users a clue. > They'll need to look up in config.txt anyway for explanation. If we > name the config keys (and groups) well then users should be able to > guess what those keys may be for before deciding whether to look into > details. Please do not label the list as "These variables affect this command" to give a false impression that it is the complete list if it isn't. Unless somebody promises to keep an up-to-date complete list there (or even better, come up with a mechanism to help us keep that promise automatically, perhaps by annotating pieces with structured comments in config.txt and automatically appending such a section to manual pages of relevant commands), that is. With a weaker phrase, e.g. "These configuration variables may be of interest", such a list may not hurt readers, but personally I do not think it adds much value to have a list of variables without even a single line description of what each is used for. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Nguyen Thai Ngoc Duy writes: > On Wed, Oct 3, 2012 at 3:46 PM, Ramkumar Ramachandra > wrote: >> On second thought, it might not be such a good idea. There are *lots* >> of variables that control the operation of each command, and it's hard >> to decide which ones to list and which ones to omit. I've listed all >> the relevant variables for git-push, except the advice.* variables- I >> don't know how useful such a long list might be. > > I think listing receive.* and advice.* (and maybe even > remove..*) is still ok. The goal is to give users a clue. > They'll need to look up in config.txt anyway for explanation. If we > name the config keys (and groups) well then users should be able to > guess what those keys may be for before deciding whether to look into > details. I would recommend against listing any advice.* in the command manual pages. They are meant to give an advice in cases that are often confusing to new people and are supposed to advise how to turn it off in the message. We want users to see them and understand the situation, and more importantly, we want to strongly discourage users to decline them until seeing them and understand what they advise for or against. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Wed, Oct 03, 2012 at 11:26:55AM -0700, Junio C Hamano wrote: > Please do not label the list as "These variables affect this > command" to give a false impression that it is the complete list if > it isn't. > > Unless somebody promises to keep an up-to-date complete list there > (or even better, come up with a mechanism to help us keep that > promise automatically, perhaps by annotating pieces with structured > comments in config.txt and automatically appending such a section to > manual pages of relevant commands), that is. > > With a weaker phrase, e.g. "These configuration variables may be of > interest", such a list may not hurt readers, but personally I do not > think it adds much value to have a list of variables without even a > single line description of what each is used for. We talked a while ago about actually moving the config options into the individual manpages, and generating config.txt to simply contain an index of keys and where their definitions may be found. That also has the "list without description" characteristic. But presumably you would be looking for keys in the manual of the command you want to affect, and the master list would mostly be for redirecting you to the right manpage. It does break down a little when you have keys that could go in multiple pages. In many cases, this can be solved by a canonical location that describes the shared concepts. For example, `diff.*` should probably go into a `gitdiff(7)` that talks about the various diff options and formats. Of course, that only works if you think pulling out the shared diff bits from git-diff*, git-log, etc into a separate manpage is a good idea. I do, because I think it makes it more clear to the reader how the concepts connect (as opposed to simply including shared bits inline in the manpages, as we do now, with no indication that the same content is going to apply in many places). But it does have a downside that individual manpages are not as easily searchable via the pager, as you may have to follow a cross-reference to find what you want. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Nguyen Thai Ngoc Duy writes: > On Thu, Oct 4, 2012 at 1:49 AM, Junio C Hamano wrote: >> I would recommend against listing any advice.* in the command manual >> pages. They are meant to give an advice in cases that are often >> confusing to new people and are supposed to advise how to turn it >> off in the message. > > OK. I think I was surprised that some messages were controlled by > advice.* but gave no hints about that and I found that out by other > means. I'll check all the advice messages. As far as I can tell, $ git grep -e 'advice\.' Documentation shows the list in config.txt and nothing else, and they do talk about when they are issued, but the reasoning behind them may not be described to a sufficient degree (that is, unless a reader carefully thinks things through, s/he may not be able to figure out why). But I think what we have there is more or less OK. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Thu, Oct 4, 2012 at 12:45 PM, Junio C Hamano wrote: > Nguyen Thai Ngoc Duy writes: > >> On Thu, Oct 4, 2012 at 1:49 AM, Junio C Hamano wrote: >>> I would recommend against listing any advice.* in the command manual >>> pages. They are meant to give an advice in cases that are often >>> confusing to new people and are supposed to advise how to turn it >>> off in the message. >> >> OK. I think I was surprised that some messages were controlled by >> advice.* but gave no hints about that and I found that out by other >> means. I'll check all the advice messages. > > As far as I can tell, > > $ git grep -e 'advice\.' Documentation > > shows the list in config.txt and nothing else, and they do talk > about when they are issued, but the reasoning behind them may not be > described to a sufficient degree (that is, unless a reader carefully > thinks things through, s/he may not be able to figure out why). But > I think what we have there is more or less OK. It's about the commands, not the documents. For example I had no idea I could set advice.statusHints to turn off some advice. "git status" does not say that those messages can be turned off. -- Duy -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Nguyen Thai Ngoc Duy writes: > On Thu, Oct 4, 2012 at 12:45 PM, Junio C Hamano wrote: >> Nguyen Thai Ngoc Duy writes: >> >>> On Thu, Oct 4, 2012 at 1:49 AM, Junio C Hamano wrote: I would recommend against listing any advice.* in the command manual pages. They are meant to give an advice in cases that are often confusing to new people and are supposed to advise how to turn it off in the message. >>> >>> OK. I think I was surprised that some messages were controlled by >>> advice.* but gave no hints about that and I found that out by other >>> means. I'll check all the advice messages. >> >> As far as I can tell, >> >> $ git grep -e 'advice\.' Documentation >> >> shows the list in config.txt and nothing else, and they do talk >> about when they are issued, but the reasoning behind them may not be >> described to a sufficient degree (that is, unless a reader carefully >> thinks things through, s/he may not be able to figure out why). But >> I think what we have there is more or less OK. > > It's about the commands, not the documents. For example I had no idea > I could set advice.statusHints to turn off some advice. "git status" > does not say that those messages can be turned off. OK, the messages are supposed to advise how to turn them off, so we would want some code updates in that case. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Junio C Hamano wrote: > Nguyen Thai Ngoc Duy writes: > >> On Wed, Oct 3, 2012 at 3:46 PM, Ramkumar Ramachandra >> wrote: >>> On second thought, it might not be such a good idea. There are *lots* >>> of variables that control the operation of each command, and it's hard >>> to decide which ones to list and which ones to omit. I've listed all >>> the relevant variables for git-push, except the advice.* variables- I >>> don't know how useful such a long list might be. >> >> I think listing receive.* and advice.* (and maybe even >> remove..*) is still ok. The goal is to give users a clue. >> They'll need to look up in config.txt anyway for explanation. If we >> name the config keys (and groups) well then users should be able to >> guess what those keys may be for before deciding whether to look into >> details. > > Please do not label the list as "These variables affect this > command" to give a false impression that it is the complete list if > it isn't. > > Unless somebody promises to keep an up-to-date complete list there > (or even better, come up with a mechanism to help us keep that > promise automatically, perhaps by annotating pieces with structured > comments in config.txt and automatically appending such a section to > manual pages of relevant commands), that is. > > With a weaker phrase, e.g. "These configuration variables may be of > interest", such a list may not hurt readers, but personally I do not > think it adds much value to have a list of variables without even a > single line description of what each is used for. Okay. Does this work? -- 8< -- From: Ramkumar Ramachandra Date: Sun, 7 Oct 2012 17:24:36 +0530 Subject: [PATCH] Documentation/git-push: add a configuration variables section The list of configuration variables that affect the operation of a git command can often be hard to find. As a first step, add a "Configuration variables" section to git-push. The intent is to create similar sections in all manpages. Signed-off-by: Ramkumar Ramachandra --- Documentation/git-push.txt | 24 1 file changed, 24 insertions(+) diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index cb97cc1..a125536 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -426,6 +426,30 @@ Commits A and B would no longer belong to a branch with a sy and so would be unreachable. As such, these commits would be removed by a `git gc` command on the origin repository. +Configuration variables +--- + +These configuration variables may be of interest. For more +information see linkgit:git-config[1]. + +branch..remote +core.gitProxy +http.proxy +push.default +receive.autogc +receive.denyCurrentBranch +receive.denyDeleteCurrent +receive.denyDeletes +receive.denyNonFastForwards +receive.unpackLimit +receive.updateserverinfo +remote..mirror +remote..proxy +remote..push +remote..pushurl +remote..receivepack +remote..url + GIT --- Part of the linkgit:git[1] suite -- 1.7.12.1.428.g652398a.dirty -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Ramkumar Ramachandra writes: > Junio C Hamano wrote: >> >> With a weaker phrase, e.g. "These configuration variables may be of >> interest", such a list may not hurt readers, but personally I do not >> think it adds much value to have a list of variables without even a >> single line description of what each is used for. > > Okay. Does this work? Hrm, is it useful without even a single line description of what each is used for? Besides, how does it appear in the formatted documents? A thick paragraph that lists names of variables enumerated without comma in between? > -- 8< -- > From: Ramkumar Ramachandra > Date: Sun, 7 Oct 2012 17:24:36 +0530 > Subject: [PATCH] Documentation/git-push: add a configuration variables > section > > The list of configuration variables that affect the operation of a git > command can often be hard to find. As a first step, add a > "Configuration variables" section to git-push. The intent is to > create similar sections in all manpages. > > Signed-off-by: Ramkumar Ramachandra > --- > Documentation/git-push.txt | 24 > 1 file changed, 24 insertions(+) > > diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt > index cb97cc1..a125536 100644 > --- a/Documentation/git-push.txt > +++ b/Documentation/git-push.txt > @@ -426,6 +426,30 @@ Commits A and B would no longer belong to a > branch with a sy > and so would be unreachable. As such, these commits would be removed by > a `git gc` command on the origin repository. > > +Configuration variables > +--- > + > +These configuration variables may be of interest. For more > +information see linkgit:git-config[1]. > + > +branch..remote > +core.gitProxy > +http.proxy > +push.default > +receive.autogc > +receive.denyCurrentBranch > +receive.denyDeleteCurrent > +receive.denyDeletes > +receive.denyNonFastForwards > +receive.unpackLimit > +receive.updateserverinfo > +remote..mirror > +remote..proxy > +remote..push > +remote..pushurl > +remote..receivepack > +remote..url > + > GIT > --- > Part of the linkgit:git[1] suite -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Junio C Hamano wrote: > Ramkumar Ramachandra writes: > >> Junio C Hamano wrote: >>> >>> With a weaker phrase, e.g. "These configuration variables may be of >>> interest", such a list may not hurt readers, but personally I do not >>> think it adds much value to have a list of variables without even a >>> single line description of what each is used for. >> >> Okay. Does this work? > > Hrm, is it useful without even a single line description of what > each is used for? Should we replicate the description from git-config[1]? That seems like a waste. > Besides, how does it appear in the formatted documents? A thick > paragraph that lists names of variables enumerated without comma in > between? Oops; I didn't build it and check. Ram -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Jeff King writes:
> On Wed, Oct 03, 2012 at 11:26:55AM -0700, Junio C Hamano wrote:
>
>> Please do not label the list as "These variables affect this
>> command" to give a false impression that it is the complete list if
>> it isn't.
>>
>> Unless somebody promises to keep an up-to-date complete list there
>> (or even better, come up with a mechanism to help us keep that
>> promise automatically, perhaps by annotating pieces with structured
>> comments in config.txt and automatically appending such a section to
>> manual pages of relevant commands), that is.
>>
>> With a weaker phrase, e.g. "These configuration variables may be of
>> interest", such a list may not hurt readers, but personally I do not
>> think it adds much value to have a list of variables without even a
>> single line description of what each is used for.
>
> We talked a while ago about actually moving the config options into the
> individual manpages, and generating config.txt to simply contain an
> index of keys and where their definitions may be found. That also has
> the "list without description" characteristic. But presumably you would
> be looking for keys in the manual of the command you want to affect, and
> the master list would mostly be for redirecting you to the right
> manpage.
That cuts both ways for configuration variables that affects or are
affected by multiple commands, and that would range from the trivial
example of configuration variables for fetch and merge that appear
to take effect in "git pull" from the end users' perspective, to the
more complex ones like remotes.*.merge and remotes.*.url that are
set to make the @{upstream} notation work.
> It does break down a little when you have keys that could go in multiple
> pages. In many cases, this can be solved by a canonical location that
> describes the shared concepts. For example, `diff.*` should probably go
> into a `gitdiff(7)` that talks about the various diff options and
> formats.
>
> Of course, that only works if you think pulling out the shared diff bits
> from git-diff*, git-log, etc into a separate manpage is a good idea. I
> do, because I think it makes it more clear to the reader how the
> concepts connect (as opposed to simply including shared bits inline in
> the manpages, as we do now, with no indication that the same content is
> going to apply in many places). But it does have a downside that
> individual manpages are not as easily searchable via the pager, as you
> may have to follow a cross-reference to find what you want.
I suspect that approach would make individual manual pages less
approacheable by new people, as they will have more required
reading.
git(1) currently guides people to user manual, and then points at
individual pages, assuming that these shared concepts (e.g. the one
for "diff" you discuss in the above paragraph) are fully mastered
once the user manual is read. Perhaps we would need to replace it
with a "concepts" manual, or enhance it with more "concepts"
material?
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Fri, Oct 05, 2012 at 01:03:28PM -0700, Junio C Hamano wrote:
> >>> OK. I think I was surprised that some messages were controlled by
> >>> advice.* but gave no hints about that and I found that out by other
> >>> means. I'll check all the advice messages.
> >
> > It's about the commands, not the documents. For example I had no idea
> > I could set advice.statusHints to turn off some advice. "git status"
> > does not say that those messages can be turned off.
>
> OK, the messages are supposed to advise how to turn them off, so we
> would want some code updates in that case.
Something like this? It turns out none of the advice messages says
anything about advice.*.
This patch makes many output more verbose/annoying, (which is good,
more motivation to turn advice off). On the other hand, if a user sees
a message telling her/him to turn advice.statusHints off, (s)he may
miss other helpful advice as it turns the whole set off. I don't know
if that is good or bad for newbies.
Tests are broken due to output changes. Will fix it if it may have a
chance of entering git.git.
There are two advise() calls in sequencer.c that we may want to
trigger with a new advice config, by the way.
-- 8< --
diff --git a/advice.c b/advice.c
index edfbd4a..5b78c01 100644
--- a/advice.c
+++ b/advice.c
@@ -70,7 +70,8 @@ int error_resolve_conflict(const char *me)
advise(_("Fix them up in the work tree,\n"
"and then use 'git add/rm ' as\n"
"appropriate to mark resolution and make a commit,\n"
-"or use 'git commit -a'."));
+"or use 'git commit -a'.\n"
+"Set advice.resolveConflict to false to turn off this
message."));
return -1;
}
@@ -89,7 +90,9 @@ void detach_advice(const char *new_name)
"state without impacting any branches by performing another
checkout.\n\n"
"If you want to create a new branch to retain commits you create, you
may\n"
"do so (now or later) by using -b with the checkout command again.
Example:\n\n"
- " git checkout -b new_branch_name\n\n";
+ " git checkout -b new_branch_name\n"
+ "Set either advice.detachedHead to false to turn off this message\n\n"
+;
fprintf(stderr, fmt, new_name);
}
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 781295b..a805961 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -699,7 +699,9 @@ static void suggest_reattach(struct commit *commit, struct
rev_info *revs)
_(
"If you want to keep them by creating a new branch, "
"this may be a good time\nto do so with:\n\n"
- " git branch new_branch_name %s\n\n"),
+ " git branch new_branch_name %s\n"
+ "Set either advice.detachedHead to false"
+ " to turn off this message\n\n"),
sha1_to_hex(commit->object.sha1));
}
diff --git a/builtin/commit.c b/builtin/commit.c
index a17a5df..5a4d85f 100644
--- a/builtin/commit.c
+++ b/builtin/commit.c
@@ -50,7 +50,8 @@ N_("Your name and email address were configured automatically
based\n"
"\n"
"After doing this, you may fix the identity used for this commit with:\n"
"\n"
-"git commit --amend --reset-author\n");
+"git commit --amend --reset-author\n"
+"Set either advice.implicitIdentity to false to turn off this message\n");
static const char empty_amend_advice[] =
N_("You asked to amend the most recent commit, but doing so would make\n"
diff --git a/builtin/merge.c b/builtin/merge.c
index 0ec8f0d..754f51e 100644
--- a/builtin/merge.c
+++ b/builtin/merge.c
@@ -1227,14 +1227,18 @@ int cmd_merge(int argc, const char **argv, const char
*prefix)
*/
if (advice_resolve_conflict)
die(_("You have not concluded your merge (MERGE_HEAD
exists).\n"
- "Please, commit your changes before you can
merge."));
+ "Please, commit your changes before you can
merge.\n"
+ "Set advice.resolveConflict to false"
+ " to turn off this message\n"));
else
die(_("You have not concluded your merge (MERGE_HEAD
exists)."));
}
if (file_exists(git_path("CHERRY_PICK_HEAD"))) {
if (advice_resolve_conflict)
die(_("You have not concluded your cherry-pick
(CHERRY_PICK_HEAD exists).\n"
- "Please, commit your changes before you can
merge."));
+ "Please, commit your changes before you can
merge.\n"
+ "Set advice.resolveConflict to false"
+ " to turn off this message\n"));
else
die(_("You have not concluded your
Re: push.default documented in "man git-push"?
Nguyen Thai Ngoc Duy writes: > On Fri, Oct 05, 2012 at 01:03:28PM -0700, Junio C Hamano wrote: > >> OK, the messages are supposed to advise how to turn them off, so we >> would want some code updates in that case. > > Something like this? It turns out none of the advice messages says > anything about advice.*. Personally, I'm fine with the current situation. Advanced users can read the documentation, and for others, the messages are usually more helpful than annoying. > This patch makes many output more verbose/annoying, For example, it makes the output of git status look like: # On branch master # Changes to be committed: # (use "git reset HEAD ..." to unstage) # Set advice.statusHints to false to turn off this message # # modified: foo.txt # # Changes not staged for commit: # (use "git add ..." to update what will be committed) # (use "git checkout -- ..." to discard changes in working directory) # Set advice.statusHints to false to turn off this message # # modified: foo.txt # # Untracked files: # (use "git add ..." to include in what will be committed) # Set advice.statusHints to false to turn off this message # # bar.txt I think it's going really too far in verbosity, the actual information is hidden by the advices. > (which is good, more motivation to turn advice off). I disagree. Having advices turned on doesn't harm anyone. I don't remember anyone complaining about the verbosity of Git's advices. I've seen *many* more people complaining about the user-unfriendliness of Git. I'm fine with very verbose (and scary) messages when the user did something wrong (for example, the advice.implicitIdentity is something you should never see if you configured Git properly before commiting). But the user should not feel blamed for using the default configuration of advice messages. The tripple repetition in "git status" shown above really sounds like "hey, dumb user, why did you not set advice.statusHints already", and is doubly scary for newbies, because they are not told how to set the variable, nor what a config variable is to Git. I understand the motivation of making the advice.* section of "man git-config" more easily discoverable, but then picking a reasonable subset of the advice messages (e.g. places that are already verbose anyway, and not places that total beginners would see on a daily basis like "git status") would be much better than targetting exhaustivity IMHO. > @@ -89,7 +90,9 @@ void detach_advice(const char *new_name) > "state without impacting any branches by performing another > checkout.\n\n" > "If you want to create a new branch to retain commits you create, you > may\n" > "do so (now or later) by using -b with the checkout command again. > Example:\n\n" > - " git checkout -b new_branch_name\n\n"; > + " git checkout -b new_branch_name\n" > + "Set either advice.detachedHead to false to turn off this message\n\n" ^^ Wrong cut-and paste from "... either XXX or YYY ..."? (repeated several times below). -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
On Thu, Oct 11, 2012 at 9:18 PM, Matthieu Moy wrote: > For example, it makes the output of git status look like: > > # On branch master > # Changes to be committed: > # (use "git reset HEAD ..." to unstage) > # Set advice.statusHints to false to turn off this message > # > # modified: foo.txt > # > # Changes not staged for commit: > # (use "git add ..." to update what will be committed) > # (use "git checkout -- ..." to discard changes in working directory) > # Set advice.statusHints to false to turn off this message > # > # modified: foo.txt > # > # Untracked files: > # (use "git add ..." to include in what will be committed) > # Set advice.statusHints to false to turn off this message > # > # bar.txt And two more lines on my output: no changes added to commit (use "git add" and/or "git commit -a") Set advice.statusHints to false to turn off this message > I think it's going really too far in verbosity, the actual information > is hidden by the advices. We could make it only one extra line in this case by prepending "hint: " before the advice and say "you could turn the hints off by setting advice.statusHints" at the end. Not applicable in general though. >> (which is good, more motivation to turn advice off). > > I disagree. Having advices turned on doesn't harm anyone. I don't > remember anyone complaining about the verbosity of Git's advices. I've > seen *many* more people complaining about the user-unfriendliness of > Git. "git status" is actually quite verbose, but the advice only plays a part of it. So, not an actual complaint from me about the advice alone. >> - " git checkout -b new_branch_name\n\n"; >> + " git checkout -b new_branch_name\n" >> + "Set either advice.detachedHead to false to turn off this message\n\n" > ^^ > > Wrong cut-and paste from "... either XXX or YYY ..."? (repeated several > times below). Cut&Paste mistake. -- Duy -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: push.default documented in "man git-push"?
Matthieu Moy writes: > Nguyen Thai Ngoc Duy writes: > >> On Fri, Oct 05, 2012 at 01:03:28PM -0700, Junio C Hamano wrote: >> >>> OK, the messages are supposed to advise how to turn them off, so we >>> would want some code updates in that case. >> >> Something like this? It turns out none of the advice messages says >> anything about advice.*. > > Personally, I'm fine with the current situation. Advanced users can read > the documentation, and for others, the messages are usually more helpful > than annoying. OK, you convinced me. > I disagree. Having advices turned on doesn't harm anyone. I don't > remember anyone complaining about the verbosity of Git's advices. I've > seen *many* more people complaining about the user-unfriendliness of > Git. > > I'm fine with very verbose (and scary) messages when the user did > something wrong (for example, the advice.implicitIdentity is something > you should never see if you configured Git properly before commiting). > But the user should not feel blamed for using the default configuration > of advice messages. The tripple repetition in "git status" shown above > really sounds like "hey, dumb user, why did you not set > advice.statusHints already", and is doubly scary for newbies, because > they are not told how to set the variable, nor what a config variable is > to Git. Let's let the list of advice.* messages in Documentation/config.txt do their job. Nguyen, thanks for taking a look. I do agree the extra "here is how to rob helpful hints from yourself before you learn them" seems to do more harm than good. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
