From: D. Ben Knoble Date: Tue, 23 Sep 2025 17:56:56 GMT Subject: Re: [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Message-ID: In-Reply-To: On Tue, Sep 23, 2025 at 1:44 PM Julia Evans via GitGitGadget wrote: > > 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 > > Julia Evans (4): > 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" > > Documentation/git-push.adoc | 43 +++++++++++++++++--------------- > Documentation/urls-remotes.adoc | 44 ++++++++++++++++++++++++++++++--- > 2 files changed, 64 insertions(+), 23 deletions(-) > > > base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0 > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v3 > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v3 > Pull-Request: https://github.com/gitgitgadget/git/pull/1964 > > Range-diff vs v2: > > 1: 270edd2b00 ! 1: 2870c77e80 doc: git-push: clarify intro > @@ Documentation/git-push.adoc: SYNOPSIS > -every time you push into it, by setting up 'hooks' there. See > -documentation for linkgit:git-receive-pack[1]. > +Updates one or more branches, tags, or other references in a remote > -+repository from your local repository. > ++repository from your local repository, and sends all necessary data > ++that isn't already on the remote. > > When the command line does not specify where to push with the > `` argument, `branch.*.remote` configuration for the > @@ Documentation/git-push.adoc: corresponding upstream branch, but as a safety meas > +You can make interesting things happen to a repository > +every time you push into it, by setting up 'hooks' there. See > +documentation for linkgit:git-receive-pack[1]. > ++ > > OPTIONS[[OPTIONS]] > ------------------ > 2: 0ec629d403 ! 2: 3ecfb5c3a6 doc: add an UPSTREAM BRANCHES section to pull/push/fetch > @@ Commit message > > Signed-off-by: Julia Evans > > - ## Documentation/git-fetch.adoc ## > -@@ Documentation/git-fetch.adoc: include::pull-fetch-param.adoc[] > - Read refspecs, one per line, from stdin in addition to those provided > - as arguments. The "tag " format is not supported. > - > --include::urls-remotes.adoc[] > -+include::urls-remotes-upstreams.adoc[] > - > - > - CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]] > - > - ## Documentation/git-pull.adoc ## > -@@ Documentation/git-pull.adoc: include::fetch-options.adoc[] > - > - include::pull-fetch-param.adoc[] > - > --include::urls-remotes.adoc[] > -+include::urls-remotes-upstreams.adoc[] > - > - include::merge-strategies.adoc[] > - > - > - ## Documentation/git-push.adoc ## > -@@ Documentation/git-push.adoc: further recursion will occur. In this case, "only" is treated as "on-demand". > - --ipv6:: > - Use IPv6 addresses only, ignoring IPv4 addresses. > - > --include::urls-remotes.adoc[] > -+include::urls-remotes-upstreams.adoc[] > - > - OUTPUT > - ------ > - > - ## Documentation/urls-remotes.adoc => Documentation/urls-remotes-upstreams.adoc ## > -@@ Documentation/urls-remotes-upstreams.adoc: git push uses: > + ## Documentation/urls-remotes.adoc ## > +@@ Documentation/urls-remotes.adoc: git push uses: > HEAD:refs/heads/ > ------------ > > @@ Documentation/urls-remotes-upstreams.adoc: git push uses: > +Git defaults to using the upstream branch for remote operations, for example: > + > +* It's the default for `git pull` or `git fetch` with no arguments > -+* It's sometimes the default for `git push` with no arguments. See the > -+ `push.default` section of linkgit:git-config[1] for the details. > -+* `git status` and `git branch -v` will show the > -+ relationship between the current branch and the upstream, > -+ for example "Your branch is up to date with origin/main" > ++* It's the default for `git push` with no arguments, with some exceptions. > ++ For example, you can use the `branch..pushRemote` option to push > ++ to a different remote than you pull from, and by default with > ++ `push.default=simple` the upstream branch you configure must have > ++ the same name. > ++* Various commands, including `git checkout` and `git status`, will > ++ show you how many commits have been added to your current branch and > ++ the upstream since you forked from it, for example "Your branch and > ++ 'origin/main' have diverged, and have 2 and 3 different commits each > ++ respectively" > + > +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`, > 3: 374740c678 ! 3: bfd6072983 doc: git-push: clarify "where to push" > @@ Commit message > doc: git-push: clarify "where to push" > > Be clearer about what we're describing ("which repository" instead of > - "what to push"), and start with a positive "try X, then Y, then Z" > + "where to push"), and start with a positive "try X, then Y, then Z" > instead of a negative ("if X is not specified.."). > > Signed-off-by: Julia Evans > > ## Documentation/git-push.adoc ## > -@@ Documentation/git-push.adoc: DESCRIPTION > - Updates one or more branches, tags, or other references in a remote > - repository from your local repository. > +@@ Documentation/git-push.adoc: Updates one or more branches, tags, or other references in a remote > + repository from your local repository, and sends all necessary data > + that isn't already on the remote. > > -When the command line does not specify where to push with the > -`` argument, `branch.*.remote` configuration for the > 4: 59732f1e47 = 4: be6453d010 doc: git-push: clarify "what to push" > > -- > gitgitgadget Range-diff looks good to me. Thanks Julia! -- D. Ben Knoble