Re: [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section
- From
D. Ben Knoble <ben.knoble@gmail.com>
- Date
- Oct 1, 2025, 22:28 UTC
- Message-ID
- <CALnO6CAmkzH=iHOU30Ud7jbP_91ovYuZBTx4nC_84ZPM53BoiA@mail.gmail.com>
- In-Reply-To
- <pull.1964.v4.git.1759262314.gitgitgadget@gmail.com>
On Tue, Sep 30, 2025 at 3:58 PM Julia Evans via GitGitGadget <gitgitgadget@gmail.com> wrote:
Show 17 quoted lines
> changes in v4: > > * Add "the simplest way to push is git push <remote> <branch>" 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.
Show 32 quoted lines
> 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 andRather, push.default=simple?
-- D. Ben Knoble