From: "Julia Evans" <julia@jvns•ca>
To: "Junio C Hamano" <gitster@pobox•com>,
"Julia Evans" <gitgitgadget@gmail•com>
Cc: git@vger•kernel.org, "D. Ben Knoble" <ben.knoble@gmail•com>,
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail•com>
Subject: Re: [PATCH v2 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
Date: Mon, 15 Sep 2025 16:19:05 -0400 [thread overview]
Message-ID: <fbde4659-6191-44ab-a713-7b47f989de96@app.fastmail.com> (raw)
In-Reply-To: <xmqqa52zl6ar.fsf@gitster.g>
On Fri, Sep 12, 2025, at 5:17 PM, Junio C Hamano wrote:
> "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.
>> +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.
> 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! :)
next prev parent reply other threads:[~2025-09-15 20:19 UTC|newest]
Thread overview: 87+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-08-26 20:40 [PATCH 0/4] doc: git-push: clarify DESCRIPTION section & refspec definition Julia Evans via GitGitGadget
2025-08-26 20:40 ` [PATCH 1/4] doc: git-push: update intro Julia Evans via GitGitGadget
2025-08-28 13:53 ` D. Ben Knoble
2025-08-28 16:18 ` Junio C Hamano
2025-08-29 7:20 ` Kristoffer Haugsbakk
2025-08-28 17:47 ` Julia Evans
2025-08-28 19:39 ` D. Ben Knoble
2025-08-26 20:40 ` [PATCH 2/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-08-27 0:05 ` Junio C Hamano
2025-08-26 20:40 ` [PATCH 3/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-08-26 23:57 ` Junio C Hamano
2025-08-27 13:52 ` Julia Evans
2025-08-28 14:25 ` D. Ben Knoble
2025-08-26 20:40 ` [PATCH 4/4] doc: git-push: rewrite refspec specification Julia Evans via GitGitGadget
2025-08-26 23:34 ` Junio C Hamano
2025-08-27 13:10 ` Julia Evans
2025-08-28 19:28 ` D. Ben Knoble
2025-09-12 18:55 ` [PATCH v2 0/4] doc: git-push: clarify DESCRIPTION section & refspec definition Julia Evans via GitGitGadget
2025-09-12 18:55 ` [PATCH v2 1/4] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-09-12 20:54 ` Junio C Hamano
2025-09-15 20:00 ` Julia Evans
2025-09-16 1:44 ` Junio C Hamano
2025-09-16 18:46 ` Julia Evans
2025-09-16 20:38 ` Ben Knoble
2025-09-16 21:59 ` Junio C Hamano
2025-09-17 18:42 ` Junio C Hamano
2025-09-18 14:20 ` Julia Evans
2025-09-12 18:55 ` [PATCH v2 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-09-12 21:17 ` Junio C Hamano
2025-09-15 20:19 ` Julia Evans [this message]
2025-09-15 21:48 ` Junio C Hamano
2025-09-15 23:09 ` Julia Evans
2025-09-16 5:25 ` Junio C Hamano
2025-09-16 5:33 ` Junio C Hamano
2025-09-16 5:39 ` Junio C Hamano
2025-09-18 21:02 ` Julia Evans
2025-09-12 18:55 ` [PATCH v2 3/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-09-12 21:18 ` Junio C Hamano
2025-09-12 21:19 ` Junio C Hamano
2025-09-15 20:52 ` Julia Evans
2025-09-12 18:55 ` [PATCH v2 4/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 1/4] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-09-24 19:51 ` Junio C Hamano
2025-09-30 19:20 ` Julia Evans
2025-09-23 17:44 ` [PATCH v3 3/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 4/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-09-24 20:01 ` Junio C Hamano
2025-09-25 20:50 ` Julia Evans
2025-09-25 21:15 ` Junio C Hamano
2025-09-25 22:34 ` Julia Evans
2025-09-26 1:27 ` Junio C Hamano
2025-09-26 15:29 ` Junio C Hamano
2025-09-26 17:31 ` Julia Evans
2025-09-26 19:03 ` Junio C Hamano
2025-09-26 22:27 ` Julia Evans
2025-09-26 23:07 ` Junio C Hamano
2025-09-28 21:38 ` D. Ben Knoble
2025-09-23 17:56 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 1/5] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-09-30 23:39 ` Junio C Hamano
2025-10-03 18:23 ` Julia Evans
2025-10-03 19:12 ` Junio C Hamano
2025-10-01 17:30 ` Jean-Noël AVILA
2025-10-03 17:54 ` Julia Evans
2025-09-30 19:58 ` [PATCH v4 3/5] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-09-30 21:01 ` Junio C Hamano
2025-10-01 17:36 ` Jean-Noël AVILA
2025-09-30 19:58 ` [PATCH v4 5/5] doc: git-push: Add explanation of `git push origin main` Julia Evans via GitGitGadget
2025-10-01 22:29 ` D. Ben Knoble
2025-10-03 17:58 ` Julia Evans
2025-10-01 22:28 ` [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 1/5] doc: git-push: clarify intro Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch Julia Evans via GitGitGadget
2025-10-07 12:23 ` Kristoffer Haugsbakk
2025-10-07 13:35 ` Julia Evans
2025-10-07 18:35 ` D. Ben Knoble
2025-10-06 18:58 ` [PATCH v5 3/5] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 5/5] doc: git-push: Add explanation of `git push origin main` Julia Evans via GitGitGadget
2025-10-06 21:53 ` [PATCH v5 0/5] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
2025-10-06 22:07 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=fbde4659-6191-44ab-a713-7b47f989de96@app.fastmail.com \
--to=julia@jvns$(echo .)ca \
--cc=ben.knoble@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitgitgadget@gmail$(echo .)com \
--cc=gitster@pobox$(echo .)com \
--cc=kristofferhaugsbakk@fastmail$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox