From: Junio C Hamano Date: Wed, 24 Sep 2025 19:51:50 GMT Subject: Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Message-ID: In-Reply-To: <3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com> "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. > 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.