doc: git-push: clarify DESCRIPTION section #1964
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -19,30 +19,35 @@ SYNOPSIS | |
| DESCRIPTION | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> From user feedback, 5 users are unsure what "ref" and/or "objects" means
> in this context. 3 users said they don't know what "complete the refs"
> means.
Well, "this concept I do not understand" from many users is not
necessarily mean that the concept does not have to be taught.
> -Updates remote refs using local refs, while sending objects
> -necessary to complete the given refs.
>
> +Updates one or more branches, tags, or other references in a remote
> +repository from your local repository.
This is a very good rewrite of the first half of the sentence.
Complete loss of the latter is a bit disturbing.
Send data that records commits, directories, and files
(collectively called "objects"), and update branches, tags and
other references at the remote repository, to make newer part of
the history available there.
or something?
> @@ -44,6 +40,9 @@ corresponding upstream branch, but as a safety measure, the push is
> aborted if the upstream branch does not have the same name as the
> local one.
>
> +You can make interesting things happen to a repository
> +every time you push into it, by setting up 'hooks' there. See
> +documentation for linkgit:git-receive-pack[1].
>
> OPTIONS[[OPTIONS]]
> ------------------
Moving the description of the secondary effect down like this is a
welcome change.
The original had two blank lines to separate the previous section
and the subsequent OPTIONS section, but now we have only one. It
would not make a difference in the rendered output, but having a
blank lines between paragraphs and two blank lines between sections,
if done consistently, would help reading the documentation in the
source form.
Thanks.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): > Well, "this concept I do not understand" from many users is not
> necessarily mean that the concept does not have to be taught.
That's true. I'll try to explain in more detail why I think terms can be
omitted (or why they can't!) in the future.
Here we're talking about two terms: refs and objects.
Re "refs": I think "refs" is pretty relevant to `git push`, which is why I left it in
(as "or other references", to give readers a hint that a branch is a type
of ref/reference).
Re "objects": I can't think right now of a common reason why it would be useful
to understand the details of how Git's object database works in the context of
"git push", do you have an example? I think `git show` is a much better example
of a command where the term "object" is relevant, because you can use `git show`
to show blob objects.
>> -Updates remote refs using local refs, while sending objects
>> -necessary to complete the given refs.
>>
>> +Updates one or more branches, tags, or other references in a remote
>> +repository from your local repository.
>
> This is a very good rewrite of the first half of the sentence.
> Complete loss of the latter is a bit disturbing.
>
> Send data that records commits, directories, and files
> (collectively called "objects"), and update branches, tags and
> other references at the remote repository, to make newer part of
> the history available there.
>
> or something?
Will try this:
Updates one or more branches, tags, or other references in a remote
repository from your local repository, and sends all necessary data in
those branches or tags that isn't already on the remote.
The goal there is to make sure the reader knows that git push may need to
send a significant amount of data, depending on what's in the new commits
you're pushing.
>> OPTIONS[[OPTIONS]]
>> ------------------
>
> Moving the description of the secondary effect down like this is a
> welcome change.
>
> The original had two blank lines to separate the previous section
> and the subsequent OPTIONS section, but now we have only one.
Will fix.There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans" <[email protected]> writes:
> Re "refs": I think "refs" is pretty relevant to `git push`, which is why I left it in
> (as "or other references", to give readers a hint that a branch is a type
> of ref/reference).
I have (and I didn't have) no issues with "refs" -> "references".
> Will try this:
>
> Updates one or more branches, tags, or other references in a remote
> repository from your local repository, and sends all necessary data in
> those branches or tags that isn't already on the remote.
>
> The goal there is to make sure the reader knows that git push may need to
> send a significant amount of data, depending on what's in the new commits
> you're pushing.
Yes. I do not partculary see the point of deliberately trying to be
vague by saying "data" (in "all necessary data") instead of "tags,
commits, trees, and blobs (collectively known as objects), but I
agree with the stated goal here.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): >> Will try this:
>>
>> Updates one or more branches, tags, or other references in a remote
>> repository from your local repository, and sends all necessary data in
>> those branches or tags that isn't already on the remote.
>>
>> The goal there is to make sure the reader knows that git push may need to
>> send a significant amount of data, depending on what's in the new commits
>> you're pushing.
>
> Yes. I do not partculary see the point of deliberately trying to be
> vague by saying "data" (in "all necessary data") instead of "tags,
> commits, trees, and blobs (collectively known as objects), but I
> agree with the stated goal here.
What we're trying to prevent here is readers getting distracted by trying to
learn concepts which are not necessary to understand how `git push` works.
For example, one user commented:
> I had to look up what the term "object" meant...
It's not necessary to know what an "object" is to understand how to use `git
push` (though if you have an example of why it is necessary, I would love
to hear it!) If it's not necessary to understand the command, readers should
not feel like they have to look it up to understand its documentation.
I think "..., and sends all necessary commits or other objects that aren't
already on the remote." might work if we want to add more detail, since it
gives users a hint that maybe they can ignore the "or other objects" part if
they're not sure what an "object" is.There was a problem hiding this comment. On the Git mailing list, Ben Knoble wrote (reply to this): > Le 16 sept. 2025 à 14:46, Julia Evans <[email protected]> a écrit :
>
> I think "..., and sends all necessary commits or other objects that aren't
> already on the remote." might work if we want to add more detail, since it
> gives users a hint that maybe they can ignore the "or other objects" part if
> they're not sure what an "object" is.
Nit, without wading into the above discussion: shouldn’t that be « and other objects »?There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): Ben Knoble <[email protected]> writes:
>> Le 16 sept. 2025 à 14:46, Julia Evans <[email protected]> a écrit :
>>
>> I think "..., and sends all necessary commits or other objects that aren't
>> already on the remote." might work if we want to add more detail, since it
>> gives users a hint that maybe they can ignore the "or other objects" part if
>> they're not sure what an "object" is.
>
> Nit, without wading into the above discussion: shouldn’t that be « and other objects »?
You could push a tag that points at a blob, so it is possible that
the push transfers only "other objects", but "necessary commits and
other objects" would naturally cover the case where the number of
necessary commits is zero ;-), so I tend to agree that *and* would
read better in that sentence.
But if we really want to do the progressive disclosure, I am OK with
the idea that hiding the details behind a vague words like "transfer
data necessary for updated branches" without saying what these data
are would work OK.
Thanks.There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): Junio C Hamano <[email protected]> writes:
> "Julia Evans" <[email protected]> writes:
>
>> Re "refs": I think "refs" is pretty relevant to `git push`, which is why I left it in
>> (as "or other references", to give readers a hint that a branch is a type
>> of ref/reference).
>
> I have (and I didn't have) no issues with "refs" -> "references".
>
>> Will try this:
>>
>> Updates one or more branches, tags, or other references in a remote
>> repository from your local repository, and sends all necessary data in
>> those branches or tags that isn't already on the remote.
>>
>> The goal there is to make sure the reader knows that git push may need to
>> send a significant amount of data, depending on what's in the new commits
>> you're pushing.
>
> Yes. I do not partculary see the point of deliberately trying to be
> vague by saying "data" (in "all necessary data") instead of "tags,
> commits, trees, and blobs (collectively known as objects), but I
> agree with the stated goal here.
Let me change my mind here.
If you are trying to avoid overwhelming the readers by carefully
trying not to write things that do not have to be said at each point
in the teaching, I do agree that the deliberate vagueness I
mentioned above is a good idea. You seem to have better "taste" of
knowing what the right amount of detail to give, a lot better than I
do.
Please keep these goodness coming.
Thanks.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): > Let me change my mind here.
>
> If you are trying to avoid overwhelming the readers by carefully
> trying not to write things that do not have to be said at each point
> in the teaching, I do agree that the deliberate vagueness I
> mentioned above is a good idea. You seem to have better "taste" of
> knowing what the right amount of detail to give, a lot better than I
> do.
>
> Please keep these goodness coming.
Thanks so much for the encouragement, it really helps a lot. I've
appreciated your detailed reviews.
let's keep going!
- Julia |
||
| ----------- | ||
|
|
||
| Updates one or more branches, tags, or other references in a remote | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Signed-off-by: Julia Evans <[email protected]>
>
> Be clearer about what we're describing ("which repository" instead of
> "what to push"), and start with a positive "try X, then Y, then Z"
> instead of a negative ("if X is not specified..").
Since I like this simple rule so much, if it is generally applicable
everywhere, I'd like to have it or a variant of it in one of our
developer facing documentation as a tip to write better
documentation.
> Signed-off-by: Julia Evans <[email protected]>
There is some funny ordering problem with the commit log body and
sign-off.
> ---
> Documentation/git-push.adoc | 8 ++++----
> 1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index e73b64f61fd0..5c934486c33d 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -22,10 +22,10 @@ DESCRIPTION
> Updates one or more branches, tags, or other references in a remote
> repository from your local repository.
>
> -When the command line does not specify where to push with the
> -`<repository>` argument, `branch.*.remote` configuration for the
> -current branch is consulted to determine where to push. If the
> -configuration is missing, it defaults to 'origin'.
> +To decide which repository to push to, Git uses the `<repository>`
> +argument (for example `git push dev`), then if that's not specified the
> +`branch.*.remote` configuration for the current branch, and then defaults
> +to `origin`.
Very nicely done.
> When the command line does not specify what to push with `<refspec>...`
> arguments or `--all`, `--mirror`, `--tags` options, the command findsThere was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> -When the command line does not specify where to push with the
> -`<repository>` argument, `branch.*.remote` configuration for the
> -current branch is consulted to determine where to push. If the
> -configuration is missing, it defaults to 'origin'.
> +To decide which repository to push to, Git uses the `<repository>`
> +argument (for example `git push dev`), then if that's not specified the
> +upstream configuration for the current branch, and then defaults
> +to `origin`.
OK. Much less awkward and much clearer. Nice.There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> From: Julia Evans <[email protected]>
>
> Be clearer about what we're describing ("which repository" instead of
> "what to push"), and start with a positive "try X, then Y, then Z"
I forgot to say, even though I did spot:
"what to push" -> "where to push"
"what to push" is the topic of the next patch.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): >> Be clearer about what we're describing ("which repository" instead of
>> "what to push"), and start with a positive "try X, then Y, then Z"
>
> I forgot to say, even though I did spot:
>
> "what to push" -> "where to push"
>
> "what to push" is the topic of the next patch.
Thanks for spotting that. Will fix. |
||
| repository from your local repository, and sends all necessary data | ||
|
There was a problem hiding this comment. On the Git mailing list, "D. Ben Knoble" wrote (reply to this): On Tue, Sep 30, 2025 at 3:58 PM Julia Evans via GitGitGadget
<[email protected]> wrote:
>
> From: Julia Evans <[email protected]>
>
> What happens if you run `git push` without any arguments is actually
> extremely complex to explain, as discussed in the previous commit.
>
> But it's very easy to explain what `git push <remote> <branch>` does, so
> start the man page by explaining what that does.
>
> The hope is that someone could just stop reading the man page here and
> never learn anything else about `git push`, and that would be fine.
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-push.adoc | 4 ++++
> 1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index 2848cf2e1f..c0e743d4a8 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -23,6 +23,10 @@ Updates one or more branches, tags, or other references in a remote
> repository from your local repository, and sends all necessary data
> that isn't already on the remote.
>
> +The simplest way to push is `git push <remote> <branch>`.
> +`git push origin main` will push the local `main` branch to the `main`
> +branch on the remote named `origin`.
Perhaps "For example," to avoid starting with punctuation/commands?
I'm not sure if that kind of thing is actually confusing for readers
or not, though. If not, I'll stop recommending such changes.
--
D. Ben KnobleThere was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): >> +The simplest way to push is `git push <remote> <branch>`.
>> +`git push origin main` will push the local `main` branch to the `main`
>> +branch on the remote named `origin`.
>
> Perhaps "For example," to avoid starting with punctuation/commands?
> I'm not sure if that kind of thing is actually confusing for readers
> or not, though. If not, I'll stop recommending such changes.
I don't think I've ever been told by a reader that it's confusing. |
||
| that isn't already on the remote. | ||
|
|
||
| The simplest way to push is `git push <remote> <branch>`. | ||
| `git push origin main` will push the local `main` branch to the `main` | ||
| branch on the remote named `origin`. | ||
|
|
||
| The `<repository>` argument defaults to the upstream for the current branch, | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> writes:
> +To decide which branches, tags, or other refs to push, Git uses
> +(in order of precedence):
> +
> +1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
> + or the `--all`, `--mirror`, or `--tags` options
> +2. The `remote.*.push` configuration for the repository being pushed to
> +3. The `push.default` configuration. The default is `push.default=simple`,
> + which will push to a branch with the same name as the current branch.
> + See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`.
> +
> +`git push` may fail if you haven't set an upstream for the current branch,
> +depending on what `push.default` is set to.
> +See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more
> +on how to set and use upstreams.
Reads well, does not tell any lies, and I like it.
> @@ -696,7 +698,7 @@ a `git gc` command on the origin repository.
>
> include::transfer-data-leaks.adoc[]
>
> -CONFIGURATION
> +CONFIGURATION[[CONFIGURATION]]
> -------------
Looking at what we have in previous steps (e.g., post context of
1/5, the title of the new section in 2/5), I think you'd need to
elongate the underline.There was a problem hiding this comment. On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Tuesday, 30 September 2025 21:58:33 CEST Julia Evans via GitGitGadget
wrote:
> From: Julia Evans <[email protected]>
>
> From user feedback: 6 users says they found the "what to push"
> paragraphs confusing, for many different reasons, including:
>
> * what does "..." in <refspec>... mean?
> * "consult XXX configuration" is hard to parse
> * it refers to the `git-config` man page even though the config
> information for `git push` is included in this man page under
> CONFIGURATION
> * the default ("push to a branch with the same name") is what they use
> 99% of the time, they would have expected it to appear earlier instead
> of at the very end
> * not understanding what the term "upstream" means in Git
> ("are branches tracked by some system besides their names?"")
>
> Also, the current explanation of `push.default=simple` ("the
> current branch is pushed to the corresponding upstream branch, but
> as a safety measure, the push is aborted if the upstream branch
> does not have the same name as the local one.") is not accurate:
> `push.default=simple` does not always require you to set a corresponding
> upstream branch.
>
> Address all of these by
>
> * using a numbered "in order of precedence" list
> * giving a more accurate explanation of how `push.default=simple` works
> * giving a little bit of context around "upstream branch": it's
> something that you may have to set explicitly
> * referring to the new UPSTREAM BRANCHES section
>
> The default behaviour is still discussed pretty late but it should be
> easier to skim now to get to the relevant information.
>
> In "`git push` may fail if...", I'm intentionally being vague about
> what exactly `git push` does, because (as discussed on the mailing list)
> the behaviour of `push.default=simple` is very confusing, perhaps broken,
> and certainly not worth trying to explain in an introductory context.
> `push.default.simple` sometimes requires you to set an upstream and
> sometimes doesn't and the exact conditions under which it does/doesn't
> are hard to describe.
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/git-push.adoc | 28 +++++++++++++++-------------
> 1 file changed, 15 insertions(+), 13 deletions(-)
>
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index acdf25e5cd..2848cf2e1f 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -26,18 +26,20 @@ that isn't already on the remote.
> The `<repository>` argument defaults to the upstream for the current
branch,
> or `origin` if there's no configured upstream.
>
> -When the command line does not specify what to push with `<refspec>...`
> -arguments or `--all`, `--mirror`, `--tags` options, the command finds
> -the default `<refspec>` by consulting `remote.*.push` configuration,
> -and if it is not found, honors `push.default` configuration to decide
> -what to push (See linkgit:git-config[1] for the meaning of `push.default`).
> -
> -When neither the command-line nor the configuration specifies what to
> -push, the default behavior is used, which corresponds to the `simple`
> -value for `push.default`: the current branch is pushed to the
> -corresponding upstream branch, but as a safety measure, the push is
> -aborted if the upstream branch does not have the same name as the
> -local one.
> +To decide which branches, tags, or other refs to push, Git uses
> +(in order of precedence):
> +
> +1. The `<refspec>` argument(s) (for example `main` in `git push origin
main`)
> + or the `--all`, `--mirror`, or `--tags` options
> +2. The `remote.*.push` configuration for the repository being pushed to
> +3. The `push.default` configuration. The default is `push.default=simple`,
> + which will push to a branch with the same name as the current branch.
> + See the <<CONFIGURATION,CONFIGURATION>> section below for more on
Good: using the cross-reference with custom label is translator's friendly.
Thank you.
> `push.default`. +
> +`git push` may fail if you haven't set an upstream for the current branch,
> +depending on what `push.default` is set to.
> +See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more
> +on how to set and use upstreams.
>
> You can make interesting things happen to a repository
> every time you push into it, by setting up 'hooks' there. See
> @@ -696,7 +698,7 @@ a `git gc` command on the origin repository.
>
> include::transfer-data-leaks.adoc[]
>
> -CONFIGURATION
> +CONFIGURATION[[CONFIGURATION]]
> -------------
Same remark concerning anchors.
Otherwise, LGTM
|
||
| or `origin` if there's no configured upstream. | ||
|
|
||
| To decide which branches, tags, or other refs to push, Git uses | ||
| (in order of precedence): | ||
|
|
||
| 1. The `<refspec>` argument(s) (for example `main` in `git push origin main`) | ||
| or the `--all`, `--mirror`, or `--tags` options | ||
| 2. The `remote.*.push` configuration for the repository being pushed to | ||
| 3. The `push.default` configuration. The default is `push.default=simple`, | ||
| which will push to a branch with the same name as the current branch. | ||
| See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`. | ||
|
|
||
| `git push` may fail if you haven't set an upstream for the current branch, | ||
| depending on what `push.default` is set to. | ||
| See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more | ||
| on how to set and use upstreams. | ||
|
|
||
| You can make interesting things happen to a repository | ||
| every time you push into it, by setting up 'hooks' there. See | ||
| documentation for linkgit:git-receive-pack[1]. | ||
|
|
||
|
|
||
| OPTIONS[[OPTIONS]] | ||
|
|
@@ -697,7 +702,7 @@ a `git gc` command on the origin repository. | |
|
|
||
| include::transfer-data-leaks.adoc[] | ||
|
|
||
| CONFIGURATION[[CONFIGURATION]] | ||
| ------------- | ||
|
|
||
| include::includes/cmd-config-section-all.adoc[] | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -92,5 +92,44 @@ git push uses: | |
| ------------ | ||
|
There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans via GitGitGadget" <[email protected]> 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.
> +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 else looked great. Thanks for working on this.There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): On Tue, Sep 30, 2025, at 7:39 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <[email protected]> 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.There was a problem hiding this comment. On the Git mailing list, Junio C Hamano wrote (reply to this): "Julia Evans" <[email protected]> writes:
> 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.
As we do not have to be exhausitive here, it is a good way out.
There was a problem hiding this comment. On the Git mailing list, Jean-Noël AVILA wrote (reply to this): On Tuesday, 30 September 2025 21:58:31 CEST Julia Evans via GitGitGadget
wrote:
> From: Julia Evans <[email protected]>
>
> From user feedback: one user mentioned that they don't know what the
> term "upstream branch" means. As far as I can tell, the most complete
> description is under the `--track` option in `git branch`. Upstreams
> are an important concept in Git and the `git branch` man page is not an
> obvious place for that information to live.
>
> There's also a very terse description of "upstream branch" in the
> glossary that's missing a lot of key information, like the fact that the
> upstream is used by `git status` and `git pull`, as well as a
> description in `git-config` in `branch.<name>.remote` which doesn't
> explain the relationship to `git status` either.
>
> 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`.
>
> 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 tracking information for the 'foo' branch"
> or the `--track` option to `git branch`
> - "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")
>
> 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.
>
> Signed-off-by: Julia Evans <[email protected]>
> ---
> Documentation/urls-remotes.adoc | 43 +++++++++++++++++++++++++++++++--
> 1 file changed, 41 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-
remotes.adoc
> index 9b10151198..dba5adeb58 100644
> --- a/Documentation/urls-remotes.adoc
> +++ b/Documentation/urls-remotes.adoc
> @@ -92,5 +92,44 @@ git push uses:
> ------------
>
>
> -
> -
> +UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
> +--------------------------------------
Please do not put anchors on the same line as the paragraph. The anchor is
attached to the paragraph (the block in asciidoc terminology) if it is not
attached to an inline element. So it can appear just before the block with the
same effect.
Additionally, this clears up the text from the anchor, which is safer for
translation.
[[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 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".
> +
> +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
> +
Please mark the code block with a dedicated fence:
----
[branch "main"]
remote = origin
merge = refs/heads/main
----
using tabs may lead to issues if the text is modified later.
> +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".
Thanks
There was a problem hiding this comment. On the Git mailing list, "Julia Evans" wrote (reply to this): >> +UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
>> +--------------------------------------
>
> Please do not put anchors on the same line as the paragraph.
Thanks, will fix. I just copied that from elsewhere in the
documentation, but I agree the anchors should be on the line above.
>> +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
>> +
>
> Please mark the code block with a dedicated fence:
>
> ----
> [branch "main"]
> remote = origin
> merge = refs/heads/main
> ----
>
> using tabs may lead to issues if the text is modified later.
Can do -- previously I was using backticks but they didn't work, so I
switched to indenting it as discussed here:
https://lore.kernel.org/git/[email protected]/
But I can use ---- instead.
It might be useful to document both of those in the part of
CodingGuidelines that explains documentation formatting,
I don't see them there. |
||
|
|
||
|
|
||
| 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 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". | ||
|
|
||
| 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". | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, Junio C Hamano wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Julia Evans" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "D. Ben Knoble" wrote (reply to this):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this):