Subject: Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch

From: Junio C Hamano <[email-masked]>
Date: Wed, 24 Sep 2025 12:51:50 -0700

"Julia Evans via GitGitGadget" <[email-masked]> 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/<head>
>  ------------
>  
> -
> -
> -
> +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.<name>.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.