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

From: Julia Evans <julia@jvns.ca>
Date: Sep 15, 2025, 20:19 UTC
Message-ID: <fbde4659-6191-44ab-a713-7b47f989de96@app.fastmail.com>
In-Reply-To: <xmqqa52zl6ar.fsf@gitster.g>

On Fri, Sep 12, 2025, at 5:17 PM, Junio C Hamano wrote:

Show 8 quoted lines

> "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

Great, it felt awkward to me too. Will leave it as is.

Show 24 quoted lines

>> +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.

It makes sense to be more specific about `git push`. I like the idea of pointing out that you can use `pushremote` to make `git push` push to a different location.

I'm not comfortable with calling this a "triangular workflow" since there are other very popular ways to set up a sort of "triangular" workflow -- for example you can pull from one repo on the "main" branch and push to your personal repo on a feature branch. In that case each individual branch is set up in a "centralized" way but the overall workflow is "triangular". But it should be easy to talk about this without using the term "triangular workflow".

>     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.

This is great, will incorporate.

Show 32 quoted lines

> 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.
>
>> +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.

Great to hear! :)