Documentation/git-push: clarify the description of defaults

We describe what gets pushed by default when the command line does not give any <refspec> under the bullet point of <refspec>. It is a bit unfriendly to expect users to read on <refspec> when they are not giving any in the first place. "What gets pushed" is determined by taking many factors (<refspec> argument being only one of them) into account, and is a property of the entire command, not an individual argument. Also we do not describe "Where the push goes" when the command line does not say. Give the description on "what gets pushed to where" upfront before explaining individual arguments and options. Also update the description of <refspec> to say what it is, what it is used for, before explaining what shape it takes. Signed-off-by: Junio C Hamano <gitster@pobox.com>

Junio C Hamano committed Mar 8, 2013 at 09:44 UTC cfe1348da60b75f6093f8fb6741630b06693e57a
1 file changed +14 -9
Documentation/git-push.txt
+14 -9
@@ -23,6 +23,17 @@ You can make interesting things happen to a repository
23 every time you push into it, by setting up 'hooks' there. See
24 documentation for linkgit:git-receive-pack[1].
25
26 +When the command line does not specify where to push with the
27 +`<repository>` argument, `branch.*.remote` configuration for the
28 +current branch is consulted to determine where to push. If the
29 +configuration is missing, it defaults to 'origin'.
30 +
31 +When the command line does not specify what to push with `<refspec>...`
32 +arguments or `--all`, `--mirror`, `--tags` options, the command finds
33 +the default `<refspec>` by consulting `remote.*.push` configuration,
34 +and if it is not found, honors `push.default` configuration to decide
35 +what to push (See gitlink:git-config[1] for the meaning of `push.default`).
36 +
37
38 OPTIONS[[OPTIONS]]
39 ------------------
@@ -33,13 +44,10 @@ OPTIONS[[OPTIONS]]
44 of a remote (see the section <<REMOTES,REMOTES>> below).
45
46 <refspec>...::
47 + Specify what destination ref to update with what source object.
48 The format of a <refspec> parameter is an optional plus
37 - `+`, followed by the source ref <src>, followed
49 + `+`, followed by the source object <src>, followed
50 by a colon `:`, followed by the destination ref <dst>.
39 - It is used to specify with what <src> object the <dst> ref
40 - in the remote repository is to be updated. If not specified,
41 - the behavior of the command is controlled by the `push.default`
42 - configuration variable.
51 +
52 The <src> is often the name of the branch you would want to push, but
53 it can be any arbitrary "SHA-1 expression", such as `master~4` or
@@ -65,10 +73,7 @@ the remote repository.
73 The special refspec `:` (or `+:` to allow non-fast-forward updates)
74 directs git to push "matching" branches: for every branch that exists on
75 the local side, the remote side is updated if a branch of the same name
68 -already exists on the remote side. This is the default operation mode
69 -if no explicit refspec is found (that is neither on the command line
70 -nor in any Push line of the corresponding remotes file---see below) and
71 -no `push.default` configuration variable is set.
76 +already exists on the remote side.
77
78 --all::
79 Instead of naming each ref to push, specifies that all