From: Junio C Hamano <gitster@pobox.com>
To: "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, "D. Ben Knoble" <ben.knoble@gmail.com>,
Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>,
Julia Evans <julia@jvns.ca>
Subject: Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
Date: Wed, 24 Sep 2025 12:51:50 -0700 [thread overview]
Message-ID: <xmqqwm5nk4rt.fsf@gitster.g> (raw)
In-Reply-To: <3ecfb5c3a67723f160e8161e212d77f95964539c.1758649472.git.gitgitgadget@gmail.com> (Julia Evans via GitGitGadget's message of "Tue, 23 Sep 2025 17:44:30 +0000")
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> 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.
next prev parent reply other threads:[~2025-09-24 19:51 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
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 [this message]
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=xmqqwm5nk4rt.fsf@gitster.g \
--to=gitster@pobox.com \
--cc=ben.knoble@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=julia@jvns.ca \
--cc=kristofferhaugsbakk@fastmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.