From: Julia Evans Date: Tue, 30 Sep 2025 19:58:33 +0000 (+0000) Subject: doc: git-push: clarify "what to push" X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e0c48fcef00d3d4048f2900bef6895bbd96cfba7;p=thirdparty%2Fgit.git doc: git-push: clarify "what to push" From user feedback: 6 users says they found the "what to push" paragraphs confusing, for many different reasons, including: * what does "..." in ... mean? * "consult XXX configuration" is hard to parse * it refers to the `git-config` man page even though the config information for `git push` is included in this man page under CONFIGURATION * the default ("push to a branch with the same name") is what they use 99% of the time, they would have expected it to appear earlier instead of at the very end * not understanding what the term "upstream" means in Git ("are branches tracked by some system besides their names?"") Also, the current explanation of `push.default=simple` ("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.") is not accurate: `push.default=simple` does not always require you to set a corresponding upstream branch. Address all of these by * using a numbered "in order of precedence" list * giving a more accurate explanation of how `push.default=simple` works * giving a little bit of context around "upstream branch": it's something that you may have to set explicitly * referring to the new UPSTREAM BRANCHES section The default behaviour is still discussed pretty late but it should be easier to skim now to get to the relevant information. In "`git push` may fail if...", I'm intentionally being vague about what exactly `git push` does, because (as discussed on the mailing list) the behaviour of `push.default=simple` is very confusing, perhaps broken, and certainly not worth trying to explain in an introductory context. `push.default.simple` sometimes requires you to set an upstream and sometimes doesn't and the exact conditions under which it does/doesn't are hard to describe. Signed-off-by: Julia Evans Signed-off-by: Junio C Hamano --- diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc index 808e0380b2..5c5ef35472 100644 --- a/Documentation/git-push.adoc +++ b/Documentation/git-push.adoc @@ -26,18 +26,20 @@ that isn't already on the remote. The `` argument defaults to the upstream for the current branch, or `origin` if there's no configured upstream. -When the command line does not specify what to push with `...` -arguments or `--all`, `--mirror`, `--tags` options, the command finds -the default `` 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`). - -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. +To decide which branches, tags, or other refs to push, Git uses +(in order of precedence): + +1. The `` argument(s) (for example `main` in `git push origin main`) + or the `--all`, `--mirror`, or `--tags` options +2. The `remote.*.push` configuration for the repository being pushed to +3. The `push.default` configuration. The default is `push.default=simple`, + which will push to a branch with the same name as the current branch. + See the <> section below for more on `push.default`. + +`git push` may fail if you haven't set an upstream for the current branch, +depending on what `push.default` is set to. +See the <> section below for more +on how to set and use upstreams. You can make interesting things happen to a repository every time you push into it, by setting up 'hooks' there. See @@ -702,7 +704,7 @@ a `git gc` command on the origin repository. include::transfer-data-leaks.adoc[] -CONFIGURATION +CONFIGURATION[[CONFIGURATION]] ------------- include::includes/cmd-config-section-all.adoc[]