From: Jean-Noël AVILA Date: Wed, 01 Oct 2025 17:36:09 GMT Subject: Re: [PATCH v4 4/5] doc: git-push: clarify "what to push" Message-ID: <5015949.GXAFRqVoOG@cayenne> In-Reply-To: On Tuesday, 30 September 2025 21:58:33 CEST Julia Evans via GitGitGadget wrote: > From: Julia Evans > > 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 > --- > Documentation/git-push.adoc | 28 +++++++++++++++------------- > 1 file changed, 15 insertions(+), 13 deletions(-) > > diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc > index acdf25e5cd..2848cf2e1f 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 Good: using the cross-reference with custom label is translator's friendly. Thank you. > `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 > @@ -696,7 +698,7 @@ a `git gc` command on the origin repository. > > include::transfer-data-leaks.adoc[] > > -CONFIGURATION > +CONFIGURATION[[CONFIGURATION]] > ------------- Same remark concerning anchors. Otherwise, LGTM