From: D. Ben Knoble Date: Wed, 01 Oct 2025 22:28:18 GMT Subject: Re: [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section Message-ID: In-Reply-To: On Tue, Sep 30, 2025 at 3:58 PM Julia Evans via GitGitGadget wrote: > changes in v4: > > * Add "the simplest way to push is git push " at the > beginning since (as discussed) this is the form of git push that's > easiest to explain. > * Remove "as a safety measure" since (as discussed with Junio) the reason > that git push sometimes requires you to set an upstream is very > confusing, and "as a safety measure..." makes it sound more principled > than it is. Also update the commit message to say that the previous > explanation was not describing push.default=simple's behaviour > accurately. > * Reword "To decide which repository to push to..." because I felt like it > was still phrased in a clunky way. > * Make UPSTREAM BRANCHES and CONFIGURATION into actual links in the HTML > docs > * Fix formatting in UPSTREAM BRANCHES section, from Junio's review > * Fix some commit message mistakes, from Junio's review Great work. > 4: be6453d010 ! 4: c1d4ea8d27 doc: git-push: clarify "what to push" > @@ Commit message > * not understanding what the term "upstream" means in Git > ("are branches tracked by some system besides their names?"") > > - Address all of these by using a numbered "in order of precedence" list > - (similar to the previous commit), by giving a little bit of context > - around "upstream branch": it's something that you may have to set > - explicitly, and referring to the new UPSTREAM BRANCHES section. > + 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 Rather, push.default=simple? -- D. Ben Knoble