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

From: Julia Evans <julia@jvns.ca>
Date: Oct 3, 2025, 18:23 UTC
Message-ID: <a5757e8e-9b9d-424c-a576-1e70af3b7795@app.fastmail.com>
In-Reply-To: <xmqqtt0j33yq.fsf@gitster.g>

On Tue, Sep 30, 2025, at 7:39 PM, Junio C Hamano wrote:

Show 8 quoted lines

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> +You can set an upstream branch explicitly with
>> +`git push --set-upstream <remote> <branch>` or `git branch --track`,
>
> I am wondering if this confuses beginners, appearing as if the
> latter does not need any other command line arguments, as the former
> does say two pieces of information needs to be given.

That makes sense.

I tried to read the documentation for `git branch --track` to figure out how to give an example, but I found it very hard to understand how it's intended to be used since there are so many options for `--track=`.

Usually when I'm creating a new branch, I want to set an upstream which doesn't exist yet on the remote, and I couldn't figure out whether or not it's possible to do that with `git branch --track`.

My best idea right now is to delete the mention of `git branch --track` here if I can't figure out how it's intended to be used.