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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 12, 2025, 21:17 UTC
Message-ID: <xmqqa52zl6ar.fsf@gitster.g>
In-Reply-To: <0ec629d4037bf5d1ccc248ca1bbd87ccc08119a3.1757703309.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes-upstreams.adoc
> similarity index 63%
> rename from Documentation/urls-remotes.adoc
> rename to Documentation/urls-remotes-upstreams.adoc

I'd personally recommend against making this rename, as we would likely add more kinds of information later, just like we are adding one now with this patch, than we would remove any. For example, we may find that this is a good place to also touch upon a triangular workflow, where you would track your upstream by pulling from there, and then you publish your work to your own remote that others can pull from (and the expectation is that your upstream would pull from that publishing repository of yours, which complets the triangle), instead of leaving it vague in the `git push` description as "See push.default and git-config for details" in the section we are adding in this patch. We will not rename the file again to Documentation/urls-remotes-upstreams-triangles.adoc when that happens ;-).

Show 22 quoted lines

> index 9b10151198..1e9c56dc5f 100644
> --- a/Documentation/urls-remotes.adoc
> +++ b/Documentation/urls-remotes-upstreams.adoc
> @@ -91,6 +91,41 @@ git push uses:
>  	HEAD:refs/heads/<head>
>  ------------
>  
> -
> -
> -
> +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:
> +
> +* 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"

Although I would rewrite the second one (i.e. "push") for clarity, to be more explicit that we are discussing only about centralized workflow in this description, the above is a good write up. Here is my version, including the push one:

    It is the default for `git fetch` (hence `git pull`) and `git
    push` when no arguments are given, and you are using the
    centralized workflow.  To use a triangular workflow, in which
    you fetch/pull from your upstream but you push your work to a
    third repository, `git push` can be configured to push to
    somewhere other than your upstream remote branch.

    Various commands, including `git status`, `git checkout`, and
    `git branch -v`, reminds you how many commits you have on top of
    your upstream, and how many commits they added to your upstream
    since your branch has forked from it.

When we would upgrade this file with a more detailed description of the triangular workflow, we'd remove the "To use a triangular..." sentence from above, and leave it to the new section.

Show 25 quoted lines

> +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
> +```
> +
> +You can set an upstream branch explicitly with
> +`git push --set-upstream <remote> <branch>` or `git branch --track`,
> +but Git will often automatically set the upstream for you, for example:
> +
> +* When you clone a repository, Git will automatically set the upstream
> +  for the default branch.
> +* If you have the `push.autoSetupRemote` configuration option set,
> +  `git push` will automatically set the upstream the first time you push
> +  a branch.
> +* Checking out a remote-tracking branch with `git checkout <branch>`
> +  will automatically create a local branch with that name and set
> +  the upstream to the remote branch.
> +
> +[NOTE]
> +Upstream branches are sometimes referred to as "tracking information",
> +as in "set the branch's tracking information".

Everything you wrote here looks like a great addition. Nicely done.