push.default documented in "man git-push"?

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)?

--dave

-- 
glasser@davidglasser.net | langtonlabs.org | flickr.com/photos/glasser/

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 <redacted>
Date: Tue, 2 Oct 2012 20:37:13 +0530
Subject: [PATCH] Documentation: mention `push.default` in git-push.txt

Signed-off-by: Ramkumar Ramachandra <redacted>
---
 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 <src>, followed
        by a colon `:`, followed by the destination ref <dst>.
        It is used to specify with what <src> object the <dst> 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 <src> 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

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 [off-list ref] wrote:

-- 
glasser@davidglasser.net | langtonlabs.org | flickr.com/photos/glasser/

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<--
From: Ramkumar Ramachandra <redacted>
Date: Tue, 2 Oct 2012 21:06:05 +0530
Subject: [PATCH] Documentation: mention `push.default` in git-push.txt

Signed-off-by: Ramkumar Ramachandra <redacted>
---
 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 <src>, followed
        by a colon `:`, followed by the destination ref <dst>.
        It is used to specify with what <src> object the <dst> 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 <src> 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 +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).

 --all::
        Instead of naming each ref to push, specifies that all

@@ -357,7 +359,7 @@ Examples
        `git push origin :`.
 +
 The default behavior of this command when no <refspec> is given can be
-configured by setting the `push` option of the remote.
+configured by setting the `push` option of the remote, or `push.default`.
 +
 For example, to default to pushing only the current branch to `origin`
 use `git config remote.origin.push HEAD`.  Any valid <refspec> (like

-- 
1.7.12.1.428.g652398a.dirty

On Tue, Oct 2, 2012 at 10:09 PM, Ramkumar Ramachandra
[off-list ref] wrote:

David Glasser wrote:

quoted

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

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)?

Ram

On Wed, Oct 3, 2012 at 3:17 PM, Ramkumar Ramachandra [off-list ref] wrote:

Hi Duy,

Nguyen Thai Ngoc Duy wrote:

quoted

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

[+CC: Junio, for comments]

Nguyen Thai Ngoc Duy wrote:

On Wed, Oct 3, 2012 at 3:17 PM, Ramkumar Ramachandra [off-list ref] wrote:

quoted

Hi Duy,

Nguyen Thai Ngoc Duy wrote:

quoted

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 <redacted>

-- 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.<name>.remote
+core.gitProxy
+http.proxy
+push.default
+receive.autogc
+receive.denyCurrentBranch
+receive.denyDeleteCurrent
+receive.denyDeletes
+receive.denyNonFastForwards
+receive.unpackLimit
+receive.updateserverinfo
+remote.<name>.mirror
+remote.<name>.proxy
+remote.<name>.push
+remote.<name>.pushurl
+remote.<name>.receivepack
+remote.<name>.url
+
 GIT
 ---
 Part of the linkgit:git[1] suite

On Wed, Oct 3, 2012 at 3:46 PM, Ramkumar Ramachandra [off-list ref] 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.<name>.*) 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

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/