From: Julia Evans Date: Tue, 30 Sep 2025 19:20:23 GMT Subject: Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Message-ID: <74475ed5-9938-4cf5-a304-e78e5827e53d@app.fastmail.com> In-Reply-To: On Wed, Sep 24, 2025, at 3:51 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" writes: > >> Since the `git pull`, `git push`, and `git fetch` man pages already >> include sections on REMOTES and the syntax for URLs, add a section on >> UPSTREAM BRANCHES to `urls-remotes.adoc` and rename it to >> `urls-remotes-upstreams.adoc`. That's an awkward name but at least it's >> clear what's in the file. > > You no longer do any such thing ;-) I can locally everyting after > "and rename it ..." and replace it with a single full-stop "." so > unless there are other things you would need to update this topic > with, no need to correct only this part. Will fix this (and everything else you mentioned in this email), thanks. >> In the new UPSTREAM BRANCHES section, cover the various ways that >> upstreams branches are automatically set in Git, since users may >> mistakenly think that their branch does not have an upstream branch if >> they didn't explicitly set one. >> >> A terminology note: Git uses two terms for this concept: >> >> - "tracking" as in "the current branch is _tracking_ some remote" >> or the `--track` option to `git branch` > > Should we say "tracking some branch at a remote"? It is not like > the current branch tracks more than one (or all) branches at the > remote as a whole. > >> - "upstream" or "upstream branch", as in `git push --set-upstream`. >> This term is also used in the `git rebase` man page to refer to the >> first argument to `git rebase`, as well as in `git pull` to refer to >> the branch which is going to be merged into the current branch ("merge >> the upstream branch into the current branch") > > This side is fine. > >> Use "upstream branch" as a heading for this concept even though the term >> "upstream branch" is not always used strictly in the sense of "the >> tracking information for the current branch". "Upstream" is used much >> more often than "tracking" in the Git docs to refer to this concept and >> the goal is to help users understand the docs. > > Good. > >> diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc >> index 9b10151198..1138a5889d 100644 >> --- a/Documentation/urls-remotes.adoc >> +++ b/Documentation/urls-remotes.adoc >> @@ -91,6 +91,44 @@ git push uses: >> HEAD:refs/heads/ >> ------------ >> >> - >> - >> - >> +UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]] >> +-------------------------------------- > > Can we have at least two blank lines between these sections to make > it visually distinct from a gap between two paragraphs? I know it > would not make a difference in the rendered pages, but it would help > those who read the document in the source form. > >> + >> +Branches in Git can optionally have an upstream remote branch. >> +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 > > I think you'd want to finish this sentence with a full-stop ".", and > a few lines below, the point beginning with "Various commands". > >> +* 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" > > Other than these, all changes from the previous version look good to > me. > > Thanks.