[PATCH 3/4] doc: git-push: clarify "what to push"
From: Julia Evans <julia@jvns.ca>
- Be more explicit about what we're describing ("which branches" instead
of "what to push")
- Split out the ways to specify which branches into a numbered list,
since there are 5 different ways to specify it and it's a lot to parse
in paragraph form
- The explanation of "push.default=simple" is confusing to some users,
use an explanation more similar to the one in `man git-config`
- Mention the most common case where push.default=simple is likely to
fail, and how to handle itSigned-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 23 +++++++++++++----------
1 file changed, 13 insertions(+), 10 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 5c934486c33d..0232195515c9 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -27,18 +27,21 @@ argument (for example `git push dev`), then if that's not specified the
`branch.*.remote` configuration for the current branch, and then defaults
to `origin`.
-When the command line does not specify what to push with `<refspec>...`
-arguments or `--all`, `--mirror`, `--tags` options, the command finds
-the default `<refspec>` by consulting `remote.*.push` configuration,
-and if it is not found, honors `push.default` configuration to decide
-what to push (See linkgit:git-config[1] for the meaning of `push.default`).
+To decide which branches, tags, or other refs to push, Git uses
+(in order of precedence):
+
+1. The <refspec> argument(s) (for example `main` in `git push origin main`)
+ or the `--all`, `--mirror`, or `--tags` options
+2. The `remote.*.push` configuration for the current branch
+3. The `push.default` configuration (See linkgit:git-config[1] for
+ the meaning of `push.default`).
When neither the command-line nor the configuration specifies what to
-push, the default behavior is used, which corresponds to the `simple`
-value for `push.default`: the current branch is pushed to the
-corresponding upstream branch, but as a safety measure, the push is
-aborted if the upstream branch does not have the same name as the
-local one.
+push, the current branch is pushed to the branch with the same name
+on the remote. The current branch must have a configured upstream with
+the same name, so this will fail when pushing a new branch.
+You can run `git push -u <repository> <current-branch>`
+to configure the upstream.
You can make interesting things happen to a repository
every time you push into it, by setting up 'hooks' there. See
--
gitgitgadget
Julia Evans via GitGitGadget <gitgitgadget@gmail.com>