From: Julia Evans via GitGitGadget Date: Mon, 06 Oct 2025 18:58:46 GMT Subject: [PATCH v5 0/5] doc: git-push: clarify DESCRIPTION section Message-ID: In-Reply-To: I surveyed 16 Git users about the git push man page. Here's a rewrite of the DESCRIPTION section and the definition of based on the feedback. The goal is to clarify it while communicating the same information. The most common piece of feedback was that folks didn't understand what the term "ref" means. Most of the users who said they did not understand the term "ref" have been using Git for 10+ years. changes in v2: * The biggest change is to add a new UPSTREAM BRANCHES section to explain what an upstream is * Drop the "refspec" changes from this patch series, I've made revisions to them based on the comments here but I felt like this was getting too big. * Added some backticks `` that I'd missed, from Ben's review * From Junio's review, "The current branch must have a configured upstream with the same name, so this will fail when pushing a new branch" was not true, so replace it with a less detailed but hopefully true statement. After a very long conversation with Ben I realized that actually push.default=simple's behaviour is not really that simple (perhaps I should think of it as more "safe" than "simple", since "current" seems simpler), so it's more realistic to refer any questions to the CONFIGURATION section which describes the behaviour in more detail. * Rewrite all the commits to explain the problem they're trying to solve & thinking behind them in more detail. Let me know if I added too much / not enough detail. changes in v3: * mention that git push also needs to send data in addition to updating the branch, from Junio's review * fix a newline, from Junio's review * un-rename urls-remotes.adoc, from Junio's review * mention pushRemote and git checkout in the UPSTREAM BRANCHES section and be clearer about what's meant by "the relationship between the current branch and the upstream", from Junio's review * fix AsciiDoc formatting issue, from Junio's review 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 changes in v5: * remove a bad example of git branch --track, from Junio's review * fix some formatting issues, from Jean-Noël's review Julia Evans (5): doc: git-push: clarify intro doc: add an UPSTREAM BRANCHES section to pull/push/fetch doc: git-push: clarify "where to push" doc: git-push: clarify "what to push" doc: git-push: Add explanation of `git push origin main` Documentation/git-push.adoc | 46 +++++++++++++++++++-------------- Documentation/urls-remotes.adoc | 42 ++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 20 deletions(-) base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v5 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v5 Pull-Request: https://github.com/gitgitgadget/git/pull/1964 Range-diff vs v4: 1: d3160fb0af = 1: 4811ce1c86 doc: git-push: clarify intro 2: 69825d4634 ! 2: 10a9718421 doc: add an UPSTREAM BRANCHES section to pull/push/fetch @@ Documentation/urls-remotes.adoc: git push uses: ------------ -- -- -+UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]] -+-------------------------------------- ++[[UPSTREAM-BRANCHES]] ++UPSTREAM BRANCHES ++----------------- + +Branches in Git can optionally have an upstream remote branch. +Git defaults to using the upstream branch for remote operations, for example: @@ Documentation/urls-remotes.adoc: git push uses: + +The upstream is stored in `.git/config`, in the "remote" and "merge" +fields. For example, if `main`'s upstream is `origin/main`: -+ -+ [branch "main"] -+ remote = origin -+ merge = refs/heads/main -+ + ++------------ ++[branch "main"] ++ remote = origin ++ merge = refs/heads/main ++------------ + +You can set an upstream branch explicitly with -+`git push --set-upstream ` or `git branch --track`, ++`git push --set-upstream ` +but Git will often automatically set the upstream for you, for example: + +* When you clone a repository, Git will automatically set the upstream 3: 244c35ef2b = 3: 336023fbf1 doc: git-push: clarify "where to push" 4: c1d4ea8d27 ! 4: 8e82c508f6 doc: git-push: clarify "what to push" @@ Documentation/git-push.adoc: a `git gc` command on the origin repository. include::transfer-data-leaks.adoc[] --CONFIGURATION -+CONFIGURATION[[CONFIGURATION]] ++[[CONFIGURATION]] + CONFIGURATION ------------- - include::includes/cmd-config-section-all.adoc[] 5: 9435f0ce8d = 5: ddeb8ecabe doc: git-push: Add explanation of `git push origin main` -- gitgitgadget