* [PATCH v3 1/4] doc: git-push: clarify intro
2025-09-23 17:44 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Julia Evans via GitGitGadget
@ 2025-09-23 17:44 ` 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
` (4 subsequent siblings)
5 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-23 17:44 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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.
Many users also commented that receive hooks do not seem like the most
important thing to know about `git push`, and that this information
should not be the second sentence in the man page.
Use more familiar language to make it more accessible to users who do
not know what a "ref" is and move the "hooks" comment to the end.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index d1978650d6..25d972f248 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -19,12 +19,9 @@ SYNOPSIS
DESCRIPTION
-----------
-Updates remote refs using local refs, while sending objects
-necessary to complete the given refs.
-
-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].
+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.
When the command line does not specify where to push with the
`<repository>` argument, `branch.*.remote` configuration for the
@@ -44,6 +41,10 @@ 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]]
------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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 ` Julia Evans via GitGitGadget
2025-09-24 19:51 ` Junio C Hamano
2025-09-23 17:44 ` [PATCH v3 3/4] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
` (3 subsequent siblings)
5 siblings, 1 reply; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-23 17:44 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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` and rename it to
`urls-remotes-upstreams.adoc`. That's an awkward name but at least it's
clear what's in the file.
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`
- "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 <julia@jvns.ca>
---
Documentation/urls-remotes.adoc | 44 ++++++++++++++++++++++++++++++---
1 file changed, 41 insertions(+), 3 deletions(-)
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]]
+--------------------------------------
+
+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".
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-24 19:51 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans
"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.
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v3 2/4] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
2025-09-24 19:51 ` Junio C Hamano
@ 2025-09-30 19:20 ` Julia Evans
0 siblings, 0 replies; 87+ messages in thread
From: Julia Evans @ 2025-09-30 19:20 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans; +Cc: git, D. Ben Knoble, Kristoffer Haugsbakk
On Wed, Sep 24, 2025, at 3:51 PM, Junio C Hamano wrote:
> "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.
Will fix this (and everything else you mentioned in this email), thanks.
>> 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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* [PATCH v3 3/4] doc: git-push: clarify "where to push"
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-23 17:44 ` Julia Evans via GitGitGadget
2025-09-23 17:44 ` [PATCH v3 4/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
` (2 subsequent siblings)
5 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-23 17:44 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
Be clearer about what we're describing ("which repository" instead of
"where to push"), and start with a positive "try X, then Y, then Z"
instead of a negative ("if X is not specified..").
Signed-off-by: Julia Evans <julia@jvns.ca>
---
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 25d972f248..368f2625a2 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -23,10 +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.
-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`.
When the command line does not specify what to push with `<refspec>...`
arguments or `--all`, `--mirror`, `--tags` options, the command finds
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-23 17:44 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Julia Evans via GitGitGadget
` (2 preceding siblings ...)
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 ` Julia Evans via GitGitGadget
2025-09-24 20:01 ` Junio C Hamano
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
5 siblings, 1 reply; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-23 17:44 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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?"")
Address all of these by using a numbered "in order of precedence" list
(similar to the previous commit), by giving a little bit of context
around "upstream branch": it's something that you may have to set
explicitly, and 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.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 26 ++++++++++++++------------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 368f2625a2..839e6abeec 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -28,18 +28,20 @@ argument (for example `git push dev`), then if that's not specified the
upstream configuration for the current branch, and then defaults
to `origin`.
-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 section below for more on `push.default`.
+
+As a safety measure, `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 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
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
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
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-24 20:01 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> -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.
That's a lot of text, and ...
> +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 section below for more on `push.default`.
.. the above gives us vastly more pleasant readability improvement.
Nice.
I do not know if you want to do anything to the lack of any
punctuation at the end of sentences 1. and 2. (I would have written
';' if I were writing this myself).
> +As a safety measure, `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 section below for more on how to set and
> +use upstreams.
This feels a bit out of place, as the safety measure, as I
understand it, is only relevant in 3. and only when push.default is
set to "simple". If we are referring the user to the configuration
section, then it may be a better place to say that the "simple"
setting requires you to integrate with the branch with the same name.
Thanks.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-24 20:01 ` Junio C Hamano
@ 2025-09-25 20:50 ` Julia Evans
2025-09-25 21:15 ` Junio C Hamano
0 siblings, 1 reply; 87+ messages in thread
From: Julia Evans @ 2025-09-25 20:50 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans; +Cc: git, D. Ben Knoble, Kristoffer Haugsbakk
On Wed, Sep 24, 2025, at 4:01 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> -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.
>
> That's a lot of text, and ...
>
>> +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 section below for more on `push.default`.
>
> .. the above gives us vastly more pleasant readability improvement.
> Nice.
>
> I do not know if you want to do anything to the lack of any
> punctuation at the end of sentences 1. and 2. (I would have written
> ';' if I were writing this myself).
>
>> +As a safety measure, `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 section below for more on how to set and
>> +use upstreams.
>
> This feels a bit out of place, as the safety measure, as I
> understand it, is only relevant in 3. and only when push.default is
> set to "simple". If we are referring the user to the configuration
> section, then it may be a better place to say that the "simple"
> setting requires you to integrate with the branch with the same name.
That makes sense. My goal here is really to communicate that you may need
to set an upstream for `git push` to work, since it hasn't been mentioned yet
that the upstream branch might be involved in deciding what remote branch
to push to, and it comes up pretty often when using the command.
Perhaps this instead:
"Depending on the value of `push.default`, git push` may fail if the current
branch doesn't have a configured upstream branch.
See the UPSTREAM BRANCHES section below for more on how to set and
use upstreams."
> Thanks.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-25 20:50 ` Julia Evans
@ 2025-09-25 21:15 ` Junio C Hamano
2025-09-25 22:34 ` Julia Evans
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-25 21:15 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
"Julia Evans" <julia@jvns.ca> writes:
>>> +As a safety measure, `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 section below for more on how to set and
>>> +use upstreams.
>>
>> This feels a bit out of place, as the safety measure, as I
>> understand it, is only relevant in 3. and only when push.default is
>> set to "simple". If we are referring the user to the configuration
>> section, then it may be a better place to say that the "simple"
>> setting requires you to integrate with the branch with the same name.
>
> That makes sense. My goal here is really to communicate that you may need
> to set an upstream for `git push` to work, since it hasn't been mentioned yet
> that the upstream branch might be involved in deciding what remote branch
> to push to, and it comes up pretty often when using the command.
Actually, I think it is a mistake to tell people to use unadorned
"git push" all the time. Have them say "git push origin mytopic",
get them feel sick of doing so all the time, and then tell them they
do not have to if they set an upstream for the current branch. IOW,
"sometimes you need to" is the source of the confusion that comes
from giving them too much DWIMmery. You'd by default need to tell
Git, because you know more about your project than Git does, until
you tell Git once, after which Git knows what to do.
> Perhaps this instead:
>
> "Depending on the value of `push.default`, git push` may fail if the current
> branch doesn't have a configured upstream branch.
> See the UPSTREAM BRANCHES section below for more on how to set and
> use upstreams."
So, rather, something like this
"git push" needs to know what branch to push to update what
branch of which repository. It is done by giving command line
arguments and/or setting configuration variables to the command.
See UPSTREAM BRANCHES section for more information.
would be more in line with a preferrable mindset users would have to
successfully use "git push", I think.
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-25 21:15 ` Junio C Hamano
@ 2025-09-25 22:34 ` Julia Evans
2025-09-26 1:27 ` Junio C Hamano
0 siblings, 1 reply; 87+ messages in thread
From: Julia Evans @ 2025-09-25 22:34 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
On Thu, Sep 25, 2025, at 5:15 PM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
>>>> +As a safety measure, `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 section below for more on how to set and
>>>> +use upstreams.
>>>
>>> This feels a bit out of place, as the safety measure, as I
>>> understand it, is only relevant in 3. and only when push.default is
>>> set to "simple". If we are referring the user to the configuration
>>> section, then it may be a better place to say that the "simple"
>>> setting requires you to integrate with the branch with the same name.
>>
>> That makes sense. My goal here is really to communicate that you may need
>> to set an upstream for `git push` to work, since it hasn't been mentioned yet
>> that the upstream branch might be involved in deciding what remote branch
>> to push to, and it comes up pretty often when using the command.
>
> Actually, I think it is a mistake to tell people to use unadorned
> "git push" all the time. Have them say "git push origin mytopic",
> get them feel sick of doing so all the time, and then tell them they
> do not have to if they set an upstream for the current branch. IOW,
> "sometimes you need to" is the source of the confusion that comes
> from giving them too much DWIMmery. You'd by default need to tell
> Git, because you know more about your project than Git does, until
> you tell Git once, after which Git knows what to do.
>
>> Perhaps this instead:
>>
>> "Depending on the value of `push.default`, git push` may fail if the current
>> branch doesn't have a configured upstream branch.
>> See the UPSTREAM BRANCHES section below for more on how to set and
>> use upstreams."
>
> So, rather, something like this
>
> "git push" needs to know what branch to push to update what
> branch of which repository. It is done by giving command line
> arguments and/or setting configuration variables to the command.
> See UPSTREAM BRANCHES section for more information.
>
> would be more in line with a preferrable mindset users would have to
> successfully use "git push", I think.
In principle I like the idea of saying that "git push needs to know
what branch to update...", it's a clear statement and it seems logical.
But I'm not sure it's true in this case: we just said above that
"The default is `push.default=simple`, which will push to a branch with
the same name as the current branch." So with push.default=simple,
Git already knows what branch it will update, it's the branch with the
same name.
As I understand it, with push.default=simple, the reason you need to set
the upstream is not to tell Git what branch to update (since Git will not
even let you set the upstream to a branch with a different name), but
instead it's more of a safety check to prevent you from accidentally
pushing a branch that you didn't mean to. Is that wrong?
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-25 22:34 ` Julia Evans
@ 2025-09-26 1:27 ` Junio C Hamano
2025-09-26 15:29 ` Junio C Hamano
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-26 1:27 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
"Julia Evans" <julia@jvns.ca> writes:
> As I understand it, with push.default=simple, the reason you need to set
> the upstream is not to tell Git what branch to update (since Git will not
> even let you set the upstream to a branch with a different name), but
> instead it's more of a safety check to prevent you from accidentally
> pushing a branch that you didn't mean to. Is that wrong?
Your understanding is correct, but when push.default=simple
castrates "git push", and you are on branch 'foo', it is dubious to
argue that "git push" _knows_ it will be pushed to 'foo' at origin.
It is very much conditional---what Git is being told is that the
push would be made there only if branch.foo.{remote,merge} were set
up to push these. If the setting is not there, then Git does not
know where to push to.
I agree with you that setting these configurations is *not* about
letting Git know. It is about lifting that conditional that
prevents Git from knowing where to push to.
> But I'm not sure it's true in this case: we just said above that
> "The default is `push.default=simple`, which will push to a branch with
> the same name as the current branch."
So I think this simplified statement is what causes confusion. It
says push.default=simple will push to such and such place, but that
is not true. push.default=simple only means that no settings that
points a branch with different name as your upstream is accepted.
And configured upstream is what determines what branch at what
remote is updated with a push.
You can tell the same story about push.default=upstream; configured
upstream is what determines what branch at what remote is updated in
this case, too, and it won't push out if you do not have your
upstream configured.
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-26 1:27 ` Junio C Hamano
@ 2025-09-26 15:29 ` Junio C Hamano
2025-09-26 17:31 ` Julia Evans
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-26 15:29 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
Junio C Hamano <gitster@pobox.com> writes:
>> But I'm not sure it's true in this case: we just said above that
>> "The default is `push.default=simple`, which will push to a branch with
>> the same name as the current branch."
>
> So I think this simplified statement is what causes confusion. It
> says push.default=simple will push to such and such place, but that
> is not true....
After sleeping on this, I do think that at the crux of confusing
wording in the current draft is the lack of stress on "simple" being
a narrower special case of more general "upstream" for various
push.default modes. In either of these modes, unless told otherwise
with the configuration file or the command line arguments, "git
push" pushes to update the upstream of the current branch. There
is, as you said, an additional safety measure in the "simple" mode,
that rejects a configuration to have a branch whose name is
different in the remote repository as the upstream branch.
In other words, the push.default=simple mode does not tell Git to
push to a branch with the same name. Rather, as a variant of the
push.default=upstream mode, it tells Git to follow the same "push to
the upstream branch" rule, which requires you to configure your
upstream. But the mode gives additional limit on the name of the
branch that can be set to upstream.
We should make our text clear enough that anybody who read about the
push.default=simple configuration easily understand the above. We
would need to find a good division between what to put in the main
text and what to leave out to the "see ... for more detauls" part to
guide those who read about "git push" command to the same
realization without bombarding them with descriptions of full range
of possible values of push.default.
Peeking our earlier exchange to help me formulate my thinking a
bit...
> +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 section below for more on `push.default`.
> +
> +As a safety measure, `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 section below for more on how to set and
> +use upstreams.
... here is my attempt.
3. The `push.default` configuration. The default is `simple`,
which is a variant of `upstream`. In either mode, "git push"
updates the configured upstream branch (see the UPSTREAM
BRANCHES section for more on how to set and use upstreams).
The 'simple' mode has an additional limitation that the name
of your configured upstream must be the same as your branch.
(iow, I rolled the "As a safety measure" paragraph into 3. itself).
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-26 15:29 ` Junio C Hamano
@ 2025-09-26 17:31 ` Julia Evans
2025-09-26 19:03 ` Junio C Hamano
0 siblings, 1 reply; 87+ messages in thread
From: Julia Evans @ 2025-09-26 17:31 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
On Fri, Sep 26, 2025, at 11:29 AM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>>> But I'm not sure it's true in this case: we just said above that
>>> "The default is `push.default=simple`, which will push to a branch with
>>> the same name as the current branch."
>>
>> So I think this simplified statement is what causes confusion. It
>> says push.default=simple will push to such and such place, but that
>> is not true....
>
> After sleeping on this, I do think that at the crux of confusing
> wording in the current draft is the lack of stress on "simple" being
> a narrower special case of more general "upstream" for various
> push.default modes. In either of these modes, unless told otherwise
> with the configuration file or the command line arguments, "git
> push" pushes to update the upstream of the current branch. There
> is, as you said, an additional safety measure in the "simple" mode,
> that rejects a configuration to have a branch whose name is
> different in the remote repository as the upstream branch.
>
> In other words, the push.default=simple mode does not tell Git to
> push to a branch with the same name. Rather, as a variant of the
> push.default=upstream mode, it tells Git to follow the same "push to
> the upstream branch" rule, which requires you to configure your
> upstream. But the mode gives additional limit on the name of the
> branch that can be set to upstream.
I like the idea of explaining it as "push.default=simple uses the
configured upstream branch, with the restriction that the upstream
branch must have the same name".
But as I learned from you earlier in this thread: https://lore.kernel.org/git/pull.1964.v2.git.1757703309.gitgitgadget@gmail.com/T/#m896f4a32ca462d69637b56f9bdfaa61e55e6b952
push.default=simple will sometimes push the current branch
to the remote branch with the same name even if there's no configured
upstream branch.
So it seems more accurate to say that push.default.simple will push
to the branch with the same name, with the restriction that you might
have to set an upstream, because the branch must always have the
same name, but whether or not you have to set an upstream depends
on the situation.
Personally that behaviour seems unintuitive to me: I always
thought that push.default=simple _did_ require you to set an
upstream branch and after spending many hours thinking about I still
can't really describe in a way that feels satisfactory to me why
it sometimes doesn't and under what conditions that happens.
One idea I had was to change Git's behaviour so that push.default=simple
_does_ require you to set an upstream branch, and then we could
document that behaviour. That's how it used to work when
push.default=simple was originally created and it's not clear to me if the
change to make push.default=simple _not_ always require you to
set an upstream was intentional or not. I did a git bisect to find out when
this changed, and it was in https://github.com/git/git/commit/ed2b18292bfeedc98c9e2b6bd8a35d8001dab2fc
commit ed2b18292bfeed
I tried to write a patch to require setting an upstream branch, though my
commit message has some mistakes and I'm not at all sure of my
understanding of the code.
https://github.com/jvns/git/commit/3553479892b11c50de939707e7f00aa7c7cb2f9d
> We should make our text clear enough that anybody who read about the
> push.default=simple configuration easily understand the above. We
> would need to find a good division between what to put in the main
> text and what to leave out to the "see ... for more detauls" part to
> guide those who read about "git push" command to the same
> realization without bombarding them with descriptions of full range
> of possible values of push.default.
>
> Peeking our earlier exchange to help me formulate my thinking a
> bit...
>
>> +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 section below for more on `push.default`.
>> +
>> +As a safety measure, `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 section below for more on how to set and
>> +use upstreams.
>
> ... here is my attempt.
>
> 3. The `push.default` configuration. The default is `simple`,
> which is a variant of `upstream`. In either mode, "git push"
> updates the configured upstream branch (see the UPSTREAM
> BRANCHES section for more on how to set and use upstreams).
> The 'simple' mode has an additional limitation that the name
> of your configured upstream must be the same as your branch.
>
> (iow, I rolled the "As a safety measure" paragraph into 3. itself).
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-26 17:31 ` Julia Evans
@ 2025-09-26 19:03 ` Junio C Hamano
2025-09-26 22:27 ` Julia Evans
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-26 19:03 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
"Julia Evans" <julia@jvns.ca> writes:
>> In other words, the push.default=simple mode does not tell Git to
>> push to a branch with the same name. Rather, as a variant of the
>> push.default=upstream mode, it tells Git to follow the same "push to
>> the upstream branch" rule, which requires you to configure your
>> upstream. But the mode gives additional limit on the name of the
>> branch that can be set to upstream.
>
> I like the idea of explaining it as "push.default=simple uses the
> configured upstream branch, with the restriction that the upstream
> branch must have the same name".
>
> But as I learned from you earlier in this thread: https://lore.kernel.org/git/pull.1964.v2.git.1757703309.gitgitgadget@gmail.com/T/#m896f4a32ca462d69637b56f9bdfaa61e55e6b952
> push.default=simple will sometimes push the current branch
> to the remote branch with the same name even if there's no configured
> upstream branch.
It was not me teaching anybody, though. I was showing my puzzlement
and confusion.
When b55e6775 (push: introduce new push.default mode "simple",
2012-04-24) introduced the "simple" mode, the intention was fairly
clear:
push: introduce new push.default mode "simple"
When calling "git push" without argument, we want to allow Git to do
something simple to explain and safe. push.default=matching is unsafe
when used to push to shared repositories, and hard to explain to
beginners in some contexts. It is debatable whether 'upstream' or
'current' is the safest or the easiest to explain, so introduce a new
mode called 'simple' that is the intersection of them: push to the
upstream branch, but only if it has the same name remotely. If not, give
an error that suggests the right command to push explicitely to
'upstream' or 'current'.
A question is whether to allow pushing when no upstream is configured. An
argument in favor of allowing the push is that it makes the new mode work
in more cases. On the other hand, refusing to push when no upstream is
configured encourages the user to set the upstream, which will be
beneficial on the next pull. Lacking better argument, we chose to deny
the push, because it will be easier to change in the future if someone
shows us wrong.
Original-patch-by: Jeff King <peff@peff.net>
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
We did reject a "git push" (no other arguments) in an unconfigured
repository using push.default=simple.
We must have _broken_ it along the way somewhere over the years.
In the output from
$ git log --all-match --grep=push.default --grep=simple
there are a handful of changes that touch PUSH_DEFAULT_SIMPLE in
ancient history; ed2b1829 (push: change `simple` to accommodate
triangular workflows, 2013-06-19), seems to have broken the
unconfigured case, which 00a6fa07 (push: truly use "simple" as
default, not "upstream", 2014-11-26) tried to fix it, and then
another commit e291c75a (remote.c: add branch_get_push, 2015-05-21)
further tweaked on the triangular (i.e. the remote you are pushing
to is different from the remote you are fetching from) workflow.
But that is long time ago; I do not think we can _fix_ the breakage
as that would be a big behaviour change. If 'simple' works to
update the branch with the same name as your current branch at the
remote you cloned from without you having to do anything special,
such a convinience is something the existing users we acquired over
the past 10 years must have become very accustomed to already. We
cannot break them.
And that is my excuse for stopping to look into the detauls of
these commits the above "git log" command found ;-)
> So it seems more accurate to say that push.default.simple will push
> to the branch with the same name, with the restriction that you might
> have to set an upstream, because the branch must always have the
> same name, but whether or not you have to set an upstream depends
> on the situation.
Now, I am still confused as I was when I wrote the message you
cited earlier.
Do we ever have a case where, with the "simple" mode, you have to
set an upstream? You may have set an upstream in a way that is not
compatible with the "simple" mode and need to fix it, but otherwise,
it appears that the "simple" mode should always work for an
unsuspecting user who does not configure their repository and
remotes into some nonstandard shape.
And if so, perhaps we do not need any special warning/note to write
for a place where we talk about "git push" generally (as opposed to
where we talk about push.default=simple settings)?
Thanks.
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-26 19:03 ` Junio C Hamano
@ 2025-09-26 22:27 ` Julia Evans
2025-09-26 23:07 ` Junio C Hamano
0 siblings, 1 reply; 87+ messages in thread
From: Julia Evans @ 2025-09-26 22:27 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
On Fri, Sep 26, 2025, at 3:03 PM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
>>> In other words, the push.default=simple mode does not tell Git to
>>> push to a branch with the same name. Rather, as a variant of the
>>> push.default=upstream mode, it tells Git to follow the same "push to
>>> the upstream branch" rule, which requires you to configure your
>>> upstream. But the mode gives additional limit on the name of the
>>> branch that can be set to upstream.
>>
>> I like the idea of explaining it as "push.default=simple uses the
>> configured upstream branch, with the restriction that the upstream
>> branch must have the same name".
>>
>> But as I learned from you earlier in this thread: https://lore.kernel.org/git/pull.1964.v2.git.1757703309.gitgitgadget@gmail.com/T/#m896f4a32ca462d69637b56f9bdfaa61e55e6b952
>> push.default=simple will sometimes push the current branch
>> to the remote branch with the same name even if there's no configured
>> upstream branch.
>
> It was not me teaching anybody, though. I was showing my puzzlement
> and confusion.
Oh, I'm glad I'm not the only one who's been confused about how
`push.default=simple` behaves :)
> When b55e6775 (push: introduce new push.default mode "simple",
> 2012-04-24) introduced the "simple" mode, the intention was fairly
> clear:
>
> push: introduce new push.default mode "simple"
>
> When calling "git push" without argument, we want to allow Git to do
> something simple to explain and safe. push.default=matching is unsafe
> when used to push to shared repositories, and hard to explain to
> beginners in some contexts. It is debatable whether 'upstream' or
> 'current' is the safest or the easiest to explain, so introduce a new
> mode called 'simple' that is the intersection of them: push to the
> upstream branch, but only if it has the same name remotely. If not, give
> an error that suggests the right command to push explicitely to
> 'upstream' or 'current'.
>
> A question is whether to allow pushing when no upstream is configured. An
> argument in favor of allowing the push is that it makes the new mode work
> in more cases. On the other hand, refusing to push when no upstream is
> configured encourages the user to set the upstream, which will be
> beneficial on the next pull. Lacking better argument, we chose to deny
> the push, because it will be easier to change in the future if someone
> shows us wrong.
>
> Original-patch-by: Jeff King <peff@peff.net>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>
> We did reject a "git push" (no other arguments) in an unconfigured
> repository using push.default=simple.
>
> We must have _broken_ it along the way somewhere over the years.
>
> In the output from
>
> $ git log --all-match --grep=push.default --grep=simple
>
> there are a handful of changes that touch PUSH_DEFAULT_SIMPLE in
> ancient history; ed2b1829 (push: change `simple` to accommodate
> triangular workflows, 2013-06-19), seems to have broken the
> unconfigured case, which 00a6fa07 (push: truly use "simple" as
> default, not "upstream", 2014-11-26) tried to fix it, and then
> another commit e291c75a (remote.c: add branch_get_push, 2015-05-21)
> further tweaked on the triangular (i.e. the remote you are pushing
> to is different from the remote you are fetching from) workflow.
>
> But that is long time ago; I do not think we can _fix_ the breakage
> as that would be a big behaviour change. If 'simple' works to
> update the branch with the same name as your current branch at the
> remote you cloned from without you having to do anything special,
> such a convinience is something the existing users we acquired over
> the past 10 years must have become very accustomed to already. We
> cannot break them.
That makes sense, can’t break backwards compatibility.
> And that is my excuse for stopping to look into the detauls of
> these commits the above "git log" command found ;-)
>
>> So it seems more accurate to say that push.default.simple will push
>> to the branch with the same name, with the restriction that you might
>> have to set an upstream, because the branch must always have the
>> same name, but whether or not you have to set an upstream depends
>> on the situation.
>
> Now, I am still confused as I was when I wrote the message you
> cited earlier.
>
> Do we ever have a case where, with the "simple" mode, you have to
> set an upstream?
Yes. If you clone a repository, create a new branch, and run `git push`
(to push to `origin`), Git will complain that you haven’t set an upstream
for that branch, like this:
$ git push
fatal: The current branch testtesttesttest has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin testtesttesttest
To have this happen automatically for branches without a tracking
upstream, see 'push.autoSetupRemote' in 'git help config'
I use `push.default=simple` and this has happened to me a lot in the
past, personally I set `push.autoSetupRemote` to deal with this.
My best guess from my experimentation and from reading some
of the commit messages/code is that the rules for how
`push.default=simple` works are something like:
1. If the remote you're pushing to is the remote that `git pull`
would normally pull from if run without any arguments,
then require the user to set an upstream
(with the idea that the remote is somehow "special"
and should be protected from accidental pushes)
2. Otherwise, push to the branch to with the same name
without requiring an upstream to be set
That said, the exact details of how push.default=simple works
(ironically) seem complicated enough that I don't think it's worth
documenting in detail at the beginning of the `git push` man page.
I definitely haven't been able to fully understand what they are yet.
Certainly it's true that sometimes you have to set an upstream
and sometimes you don't.
To go back to the original text I suggested:
> 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 section below for more on `push.default`.
>
> As a safety measure, `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 section below for more on how to set and
> use upstreams.
The words "may fail" are definitely vague, and I agree it doesn't feel good
to give a vague explanation like this. But if we think the current
behaviour is "broken" and hard to understand and that we have to keep it for
backwards compatibility reasons, giving a slightly vague explanation
(perhaps with a reference to where someone can read all the gritty
details) might be the best path.
I do like the idea (that I think you mentioned before) of adding a very
simple sentence like this near the beginning explaining what
`git push origin main` does, since it's easy to explain, and someone could
easily successfully start using `git push` without knowing any other
information.
> `git push origin main` will push the local `main` branch to the `main`
branch on `origin`.
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-26 22:27 ` Julia Evans
@ 2025-09-26 23:07 ` Junio C Hamano
2025-09-28 21:38 ` D. Ben Knoble
0 siblings, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-26 23:07 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
"Julia Evans" <julia@jvns.ca> writes:
> On Fri, Sep 26, 2025, at 3:03 PM, Junio C Hamano wrote:
>> "Julia Evans" <julia@jvns.ca> writes:
>>
>>>> In other words, the push.default=simple mode does not tell Git to
>>>> push to a branch with the same name. Rather, as a variant of the
>>>> push.default=upstream mode, it tells Git to follow the same "push to
>>>> the upstream branch" rule, which requires you to configure your
>>>> upstream. But the mode gives additional limit on the name of the
>>>> branch that can be set to upstream.
>>>
>>> I like the idea of explaining it as "push.default=simple uses the
>>> configured upstream branch, with the restriction that the upstream
>>> branch must have the same name".
>>>
>>> But as I learned from you earlier in this thread: https://lore.kernel.org/git/pull.1964.v2.git.1757703309.gitgitgadget@gmail.com/T/#m896f4a32ca462d69637b56f9bdfaa61e55e6b952
>>> push.default=simple will sometimes push the current branch
>>> to the remote branch with the same name even if there's no configured
>>> upstream branch.
>>
>> It was not me teaching anybody, though. I was showing my puzzlement
>> and confusion.
>> Now, I am still confused as I was when I wrote the message you
>> cited earlier.
>>
>> Do we ever have a case where, with the "simple" mode, you have to
>> set an upstream?
>
> Yes. If you clone a repository, create a new branch, and run `git push`
> (to push to `origin`), Git will complain that you haven’t set an upstream
> for that branch, like this:
>
> $ git push
> fatal: The current branch testtesttesttest has no upstream branch.
> To push the current branch and set the remote as upstream, use
>
> git push --set-upstream origin testtesttesttest
> To have this happen automatically for branches without a tracking
> upstream, see 'push.autoSetupRemote' in 'git help config'
Hmph, that contradicts with the observation we had in the message
you cited earlier, but it does reproduce for me as well. Puzzled
again.
> My best guess from my experimentation and from reading some
> of the commit messages/code is that the rules for how
> `push.default=simple` works are something like:
>
> 1. If the remote you're pushing to is the remote that `git pull`
> would normally pull from if run without any arguments,
> then require the user to set an upstream
> (with the idea that the remote is somehow "special"
> and should be protected from accidental pushes)
This is the traditional 'simple'
> 2. Otherwise, push to the branch to with the same name
> without requiring an upstream to be set
This is what 'triangular' feature we saw earlier in the "git log"
output in my message you are responding to had a few commits for.
> That said, the exact details of how push.default=simple works
> (ironically) seem complicated enough that I don't think it's worth
> documenting in detail at the beginning of the `git push` man page.
Totally agreed.
> To go back to the original text I suggested:
>
>> 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 section below for more on `push.default`.
>>
>> As a safety measure, `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 section below for more on how to set and
>> use upstreams.
>
> The words "may fail" are definitely vague, and I agree it doesn't feel good
> to give a vague explanation like this. But if we think the current
> behaviour is "broken" and hard to understand and that we have to keep it for
> backwards compatibility reasons, giving a slightly vague explanation
> (perhaps with a reference to where someone can read all the gritty
> details) might be the best path.
OK. Thanks for helping me think this through.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"
2025-09-26 23:07 ` Junio C Hamano
@ 2025-09-28 21:38 ` D. Ben Knoble
0 siblings, 0 replies; 87+ messages in thread
From: D. Ben Knoble @ 2025-09-28 21:38 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Julia Evans, Julia Evans, git, Kristoffer Haugsbakk
On Fri, Sep 26, 2025 at 7:07 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Julia Evans" <julia@jvns.ca> writes:
> > My best guess from my experimentation and from reading some
> > of the commit messages/code is that the rules for how
> > `push.default=simple` works are something like:
> >
> > 1. If the remote you're pushing to is the remote that `git pull`
> > would normally pull from if run without any arguments,
> > then require the user to set an upstream
> > (with the idea that the remote is somehow "special"
> > and should be protected from accidental pushes)
>
> This is the traditional 'simple'
>
>
> > 2. Otherwise, push to the branch to with the same name
> > without requiring an upstream to be set
>
> This is what 'triangular' feature we saw earlier in the "git log"
> output in my message you are responding to had a few commits for.
>
> > That said, the exact details of how push.default=simple works
> > (ironically) seem complicated enough that I don't think it's worth
> > documenting in detail at the beginning of the `git push` man page.
>
> Totally agreed.
Seconded: Julia and I spent quite a bit of time in Discord trying to
piece this puzzle back together [1], and while I don't think we found
_all_ the commits you listed, we found most of them. My summary was
> I think the logic is:
>
> - pushing to the same remote you pull from? Only if @{upstream} is set (?? and maybe something about branch name matching, i don't remember),
> - pushing somewhere else? Pushes to destination=same name
[1]: https://discord.com/channels/1042895022950994071/1412969828066787462
Getting a clear picture _somewhere_ of this default would probably be nice.
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section
2025-09-23 17:44 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Julia Evans via GitGitGadget
` (3 preceding siblings ...)
2025-09-23 17:44 ` [PATCH v3 4/4] doc: git-push: clarify "what " Julia Evans via GitGitGadget
@ 2025-09-23 17:56 ` D. Ben Knoble
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
5 siblings, 0 replies; 87+ messages in thread
From: D. Ben Knoble @ 2025-09-23 17:56 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Kristoffer Haugsbakk, Julia Evans
On Tue, Sep 23, 2025 at 1:44 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> I surveyed 16 Git users about the git push man page. Here's a rewrite of the
> DESCRIPTION section and the definition of <refspec> based on the feedback.
> The goal is to clarify it while communicating the same information. The most
> common piece of feedback was that folks didn't understand what the term
> "ref" means. Most of the users who said they did not understand the term
> "ref" have been using Git for 10+ years.
>
> changes in v2:
>
> * The biggest change is to add a new UPSTREAM BRANCHES section to explain
> what an upstream is
> * Drop the "refspec" changes from this patch series, I've made revisions to
> them based on the comments here but I felt like this was getting too big.
> * Added some backticks `` that I'd missed, from Ben's review
> * From Junio's review, "The current branch must have a configured upstream
> with the same name, so this will fail when pushing a new branch" was not
> true, so replace it with a less detailed but hopefully true statement.
> After a very long conversation with Ben I realized that actually
> push.default=simple's behaviour is not really that simple (perhaps I
> should think of it as more "safe" than "simple", since "current" seems
> simpler), so it's more realistic to refer any questions to the
> CONFIGURATION section which describes the behaviour in more detail.
> * Rewrite all the commits to explain the problem they're trying to solve &
> thinking behind them in more detail. Let me know if I added too much /
> not enough detail.
>
> changes in v3:
>
> * mention that git push also needs to send data in addition to updating the
> branch, from Junio's review
> * fix a newline, from Junio's review
> * un-rename urls-remotes.adoc, from Junio's review
> * mention pushRemote and git checkout in the UPSTREAM BRANCHES section and
> be clearer about what's meant by "the relationship between the current
> branch and the upstream", from Junio's review
> * fix AsciiDoc formatting issue, from Junio's review
>
> Julia Evans (4):
> doc: git-push: clarify intro
> doc: add an UPSTREAM BRANCHES section to pull/push/fetch
> doc: git-push: clarify "where to push"
> doc: git-push: clarify "what to push"
>
> Documentation/git-push.adoc | 43 +++++++++++++++++---------------
> Documentation/urls-remotes.adoc | 44 ++++++++++++++++++++++++++++++---
> 2 files changed, 64 insertions(+), 23 deletions(-)
>
>
> base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v3
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v3
> Pull-Request: https://github.com/gitgitgadget/git/pull/1964
>
> Range-diff vs v2:
>
> 1: 270edd2b00 ! 1: 2870c77e80 doc: git-push: clarify intro
> @@ Documentation/git-push.adoc: SYNOPSIS
> -every time you push into it, by setting up 'hooks' there. See
> -documentation for linkgit:git-receive-pack[1].
> +Updates one or more branches, tags, or other references in a remote
> -+repository from your local repository.
> ++repository from your local repository, and sends all necessary data
> ++that isn't already on the remote.
>
> When the command line does not specify where to push with the
> `<repository>` argument, `branch.*.remote` configuration for the
> @@ Documentation/git-push.adoc: corresponding upstream branch, but as a safety meas
> +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]]
> ------------------
> 2: 0ec629d403 ! 2: 3ecfb5c3a6 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
> @@ Commit message
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
>
> - ## Documentation/git-fetch.adoc ##
> -@@ Documentation/git-fetch.adoc: include::pull-fetch-param.adoc[]
> - Read refspecs, one per line, from stdin in addition to those provided
> - as arguments. The "tag <name>" format is not supported.
> -
> --include::urls-remotes.adoc[]
> -+include::urls-remotes-upstreams.adoc[]
> -
> -
> - CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
> -
> - ## Documentation/git-pull.adoc ##
> -@@ Documentation/git-pull.adoc: include::fetch-options.adoc[]
> -
> - include::pull-fetch-param.adoc[]
> -
> --include::urls-remotes.adoc[]
> -+include::urls-remotes-upstreams.adoc[]
> -
> - include::merge-strategies.adoc[]
> -
> -
> - ## Documentation/git-push.adoc ##
> -@@ Documentation/git-push.adoc: further recursion will occur. In this case, "only" is treated as "on-demand".
> - --ipv6::
> - Use IPv6 addresses only, ignoring IPv4 addresses.
> -
> --include::urls-remotes.adoc[]
> -+include::urls-remotes-upstreams.adoc[]
> -
> - OUTPUT
> - ------
> -
> - ## Documentation/urls-remotes.adoc => Documentation/urls-remotes-upstreams.adoc ##
> -@@ Documentation/urls-remotes-upstreams.adoc: git push uses:
> + ## Documentation/urls-remotes.adoc ##
> +@@ Documentation/urls-remotes.adoc: git push uses:
> HEAD:refs/heads/<head>
> ------------
>
> @@ Documentation/urls-remotes-upstreams.adoc: git push uses:
> +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"
> ++* 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
> -+```
> ++ [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`,
> 3: 374740c678 ! 3: bfd6072983 doc: git-push: clarify "where to push"
> @@ Commit message
> doc: git-push: clarify "where to push"
>
> 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"
> + "where to push"), and start with a positive "try X, then Y, then Z"
> instead of a negative ("if X is not specified..").
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
>
> ## Documentation/git-push.adoc ##
> -@@ Documentation/git-push.adoc: DESCRIPTION
> - Updates one or more branches, tags, or other references in a remote
> - repository from your local repository.
> +@@ Documentation/git-push.adoc: 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.
>
> -When the command line does not specify where to push with the
> -`<repository>` argument, `branch.*.remote` configuration for the
> 4: 59732f1e47 = 4: be6453d010 doc: git-push: clarify "what to push"
>
> --
> gitgitgadget
Range-diff looks good to me. Thanks Julia!
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 87+ messages in thread* [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section
2025-09-23 17:44 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section Julia Evans via GitGitGadget
` (4 preceding siblings ...)
2025-09-23 17:56 ` [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
@ 2025-09-30 19:58 ` Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 1/5] doc: git-push: clarify intro Julia Evans via GitGitGadget
` (6 more replies)
5 siblings, 7 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-30 19:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans
I surveyed 16 Git users about the git push man page. Here's a rewrite of the
DESCRIPTION section and the definition of <refspec> based on the feedback.
The goal is to clarify it while communicating the same information. The most
common piece of feedback was that folks didn't understand what the term
"ref" means. Most of the users who said they did not understand the term
"ref" have been using Git for 10+ years.
changes in v2:
* The biggest change is to add a new UPSTREAM BRANCHES section to explain
what an upstream is
* Drop the "refspec" changes from this patch series, I've made revisions to
them based on the comments here but I felt like this was getting too big.
* Added some backticks `` that I'd missed, from Ben's review
* From Junio's review, "The current branch must have a configured upstream
with the same name, so this will fail when pushing a new branch" was not
true, so replace it with a less detailed but hopefully true statement.
After a very long conversation with Ben I realized that actually
push.default=simple's behaviour is not really that simple (perhaps I
should think of it as more "safe" than "simple", since "current" seems
simpler), so it's more realistic to refer any questions to the
CONFIGURATION section which describes the behaviour in more detail.
* Rewrite all the commits to explain the problem they're trying to solve &
thinking behind them in more detail. Let me know if I added too much /
not enough detail.
changes in v3:
* mention that git push also needs to send data in addition to updating the
branch, from Junio's review
* fix a newline, from Junio's review
* un-rename urls-remotes.adoc, from Junio's review
* mention pushRemote and git checkout in the UPSTREAM BRANCHES section and
be clearer about what's meant by "the relationship between the current
branch and the upstream", from Junio's review
* fix AsciiDoc formatting issue, from Junio's review
changes in v4:
* Add "the simplest way to push is git push <remote> <branch>" at the
beginning since (as discussed) this is the form of git push that's
easiest to explain.
* Remove "as a safety measure" since (as discussed with Junio) the reason
that git push sometimes requires you to set an upstream is very
confusing, and "as a safety measure..." makes it sound more principled
than it is. Also update the commit message to say that the previous
explanation was not describing push.default=simple's behaviour
accurately.
* Reword "To decide which repository to push to..." because I felt like it
was still phrased in a clunky way.
* Make UPSTREAM BRANCHES and CONFIGURATION into actual links in the HTML
docs
* Fix formatting in UPSTREAM BRANCHES section, from Junio's review
* Fix some commit message mistakes, from Junio's review
Julia Evans (5):
doc: git-push: clarify intro
doc: add an UPSTREAM BRANCHES section to pull/push/fetch
doc: git-push: clarify "where to push"
doc: git-push: clarify "what to push"
doc: git-push: Add explanation of `git push origin main`
Documentation/git-push.adoc | 47 ++++++++++++++++++---------------
Documentation/urls-remotes.adoc | 43 ++++++++++++++++++++++++++++--
2 files changed, 67 insertions(+), 23 deletions(-)
base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/1964
Range-diff vs v3:
1: 2870c77e80 = 1: d3160fb0af doc: git-push: clarify intro
2: 3ecfb5c3a6 ! 2: 69825d4634 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
@@ Commit message
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.
+ 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
@@ Commit message
A terminology note: Git uses two terms for this concept:
- - "tracking" as in "the current branch is _tracking_ some remote"
+ - "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
@@ Commit message
## Documentation/urls-remotes.adoc ##
@@ Documentation/urls-remotes.adoc: git push uses:
- HEAD:refs/heads/<head>
------------
--
+
-
-
+UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
@@ Documentation/urls-remotes.adoc: git push uses:
+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 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
@@ Documentation/urls-remotes.adoc: git push uses:
+ 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"
++ respectively".
+
+The upstream is stored in `.git/config`, in the "remote" and "merge"
+fields. For example, if `main`'s upstream is `origin/main`:
3: bfd6072983 ! 3: 244c35ef2b doc: git-push: clarify "where to push"
@@ Metadata
## Commit message ##
doc: git-push: clarify "where to push"
- Be clearer about what we're describing ("which repository" instead of
- "where to push"), and start with a positive "try X, then Y, then Z"
- instead of a negative ("if X is not specified..").
+ It's not obvious that "`branch.*.remote` configuration"` refers to the
+ upstream, so say "upstream" instead.
+
+ The sentence is also quite hard to parse right now, use "defaults to" to
+ simplify it.
Signed-off-by: Julia Evans <julia@jvns.ca>
@@ Documentation/git-push.adoc: Updates one or more branches, tags, or other refere
-`<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`.
++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
4: be6453d010 ! 4: c1d4ea8d27 doc: git-push: clarify "what to push"
@@ Commit message
* not understanding what the term "upstream" means in Git
("are branches tracked by some system besides their names?"")
- Address all of these by using a numbered "in order of precedence" list
- (similar to the previous commit), by giving a little bit of context
- around "upstream branch": it's something that you may have to set
- explicitly, and referring to the new UPSTREAM BRANCHES section.
+ 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 <julia@jvns.ca>
## Documentation/git-push.adoc ##
-@@ Documentation/git-push.adoc: argument (for example `git push dev`), then if that's not specified the
- upstream configuration for the current branch, and then defaults
- to `origin`.
+@@ Documentation/git-push.adoc: 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
@@ Documentation/git-push.adoc: argument (for example `git push dev`), then if that
+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 section below for more on `push.default`.
++ See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`.
+
-+As a safety measure, `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 section below for more on how to set and
-+use upstreams.
++`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/git-push.adoc: a `git gc` command on the origin repository.
+
+ include::transfer-data-leaks.adoc[]
+
+-CONFIGURATION
++CONFIGURATION[[CONFIGURATION]]
+ -------------
+
+ include::includes/cmd-config-section-all.adoc[]
-: ---------- > 5: 9435f0ce8d doc: git-push: Add explanation of `git push origin main`
--
gitgitgadget
^ permalink raw reply [flat|nested] 87+ messages in thread* [PATCH v4 1/5] doc: git-push: clarify intro
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
@ 2025-09-30 19:58 ` 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
` (5 subsequent siblings)
6 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-30 19:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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.
Many users also commented that receive hooks do not seem like the most
important thing to know about `git push`, and that this information
should not be the second sentence in the man page.
Use more familiar language to make it more accessible to users who do
not know what a "ref" is and move the "hooks" comment to the end.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index d1978650d6..25d972f248 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -19,12 +19,9 @@ SYNOPSIS
DESCRIPTION
-----------
-Updates remote refs using local refs, while sending objects
-necessary to complete the given refs.
-
-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].
+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.
When the command line does not specify where to push with the
`<repository>` argument, `branch.*.remote` configuration for the
@@ -44,6 +41,10 @@ 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]]
------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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 ` Julia Evans via GitGitGadget
2025-09-30 23:39 ` Junio C Hamano
2025-10-01 17:30 ` Jean-Noël AVILA
2025-09-30 19:58 ` [PATCH v4 3/5] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
` (4 subsequent siblings)
6 siblings, 2 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-30 19:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
---
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]]
+--------------------------------------
+
+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".
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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-01 17:30 ` Jean-Noël AVILA
1 sibling, 1 reply; 87+ messages in thread
From: Junio C Hamano @ 2025-09-30 23:39 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans
"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.
> +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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
2025-09-30 23:39 ` Junio C Hamano
@ 2025-10-03 18:23 ` Julia Evans
2025-10-03 19:12 ` Junio C Hamano
0 siblings, 1 reply; 87+ messages in thread
From: Julia Evans @ 2025-10-03 18:23 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans; +Cc: git, D. Ben Knoble, Kristoffer Haugsbakk
On Tue, Sep 30, 2025, at 7:39 PM, Junio C Hamano wrote:
> "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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
2025-10-03 18:23 ` Julia Evans
@ 2025-10-03 19:12 ` Junio C Hamano
0 siblings, 0 replies; 87+ messages in thread
From: Junio C Hamano @ 2025-10-03 19:12 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, D. Ben Knoble, Kristoffer Haugsbakk
"Julia Evans" <julia@jvns.ca> 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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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-01 17:30 ` Jean-Noël AVILA
2025-10-03 17:54 ` Julia Evans
1 sibling, 1 reply; 87+ messages in thread
From: Jean-Noël AVILA @ 2025-10-01 17:30 UTC (permalink / raw)
To: git, Julia Evans via GitGitGadget
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
On Tuesday, 30 September 2025 21:58:31 CEST Julia Evans via GitGitGadget
wrote:
> From: Julia Evans <julia@jvns.ca>
>
> 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 <julia@jvns.ca>
> ---
> 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
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v4 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
2025-10-01 17:30 ` Jean-Noël AVILA
@ 2025-10-03 17:54 ` Julia Evans
0 siblings, 0 replies; 87+ messages in thread
From: Julia Evans @ 2025-10-03 17:54 UTC (permalink / raw)
To: Jean-Noël AVILA, git, Julia Evans
Cc: D. Ben Knoble, Kristoffer Haugsbakk
>> +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/xmqqqzw7arls.fsf@gitster.g/
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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* [PATCH v4 3/5] doc: git-push: clarify "where to push"
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 19:58 ` Julia Evans via GitGitGadget
2025-09-30 19:58 ` [PATCH v4 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
` (3 subsequent siblings)
6 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-30 19:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
It's not obvious that "`branch.*.remote` configuration"` refers to the
upstream, so say "upstream" instead.
The sentence is also quite hard to parse right now, use "defaults to" to
simplify it.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 25d972f248..acdf25e5cd 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -23,10 +23,8 @@ 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.
-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'.
+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
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v4 4/5] doc: git-push: clarify "what to push"
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
` (2 preceding siblings ...)
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 ` 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
` (2 subsequent siblings)
6 siblings, 2 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-30 19:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
---
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 `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]]
-------------
include::includes/cmd-config-section-all.adoc[]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v4 4/5] doc: git-push: clarify "what to push"
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
1 sibling, 0 replies; 87+ messages in thread
From: Junio C Hamano @ 2025-09-30 21:01 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> 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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v4 4/5] doc: git-push: clarify "what to push"
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
1 sibling, 0 replies; 87+ messages in thread
From: Jean-Noël AVILA @ 2025-10-01 17:36 UTC (permalink / raw)
To: git, Julia Evans via GitGitGadget
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
On Tuesday, 30 September 2025 21:58:33 CEST Julia Evans via GitGitGadget
wrote:
> From: Julia Evans <julia@jvns.ca>
>
> 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 <julia@jvns.ca>
> ---
> 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
^ permalink raw reply [flat|nested] 87+ messages in thread
* [PATCH v4 5/5] doc: git-push: Add explanation of `git push origin main`
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
` (3 preceding siblings ...)
2025-09-30 19:58 ` [PATCH v4 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
@ 2025-09-30 19:58 ` Julia Evans via GitGitGadget
2025-10-01 22:29 ` D. Ben Knoble
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
6 siblings, 1 reply; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-09-30 19:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
---
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`.
+
The `<repository>` argument defaults to the upstream for the current branch,
or `origin` if there's no configured upstream.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v4 5/5] doc: git-push: Add explanation of `git push origin main`
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
0 siblings, 1 reply; 87+ messages in thread
From: D. Ben Knoble @ 2025-10-01 22:29 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Kristoffer Haugsbakk, Julia Evans
On Tue, Sep 30, 2025 at 3:58 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Julia Evans <julia@jvns.ca>
>
> 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 <julia@jvns.ca>
> ---
> 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 Knoble
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v4 5/5] doc: git-push: Add explanation of `git push origin main`
2025-10-01 22:29 ` D. Ben Knoble
@ 2025-10-03 17:58 ` Julia Evans
0 siblings, 0 replies; 87+ messages in thread
From: Julia Evans @ 2025-10-03 17:58 UTC (permalink / raw)
To: D. Ben Knoble, Julia Evans; +Cc: git, Kristoffer Haugsbakk
>> +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.
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
` (4 preceding siblings ...)
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:28 ` D. Ben Knoble
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
6 siblings, 0 replies; 87+ messages in thread
From: D. Ben Knoble @ 2025-10-01 22:28 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Kristoffer Haugsbakk, Julia Evans
On Tue, Sep 30, 2025 at 3:58 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> changes in v4:
>
> * Add "the simplest way to push is git push <remote> <branch>" at the
> beginning since (as discussed) this is the form of git push that's
> easiest to explain.
> * Remove "as a safety measure" since (as discussed with Junio) the reason
> that git push sometimes requires you to set an upstream is very
> confusing, and "as a safety measure..." makes it sound more principled
> than it is. Also update the commit message to say that the previous
> explanation was not describing push.default=simple's behaviour
> accurately.
> * Reword "To decide which repository to push to..." because I felt like it
> was still phrased in a clunky way.
> * Make UPSTREAM BRANCHES and CONFIGURATION into actual links in the HTML
> docs
> * Fix formatting in UPSTREAM BRANCHES section, from Junio's review
> * Fix some commit message mistakes, from Junio's review
Great work.
> 4: be6453d010 ! 4: c1d4ea8d27 doc: git-push: clarify "what to push"
> @@ Commit message
> * not understanding what the term "upstream" means in Git
> ("are branches tracked by some system besides their names?"")
>
> - Address all of these by using a numbered "in order of precedence" list
> - (similar to the previous commit), by giving a little bit of context
> - around "upstream branch": it's something that you may have to set
> - explicitly, and referring to the new UPSTREAM BRANCHES section.
> + 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
Rather, push.default=simple?
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 87+ messages in thread* [PATCH v5 0/5] doc: git-push: clarify DESCRIPTION section
2025-09-30 19:58 ` [PATCH v4 0/5] " Julia Evans via GitGitGadget
` (5 preceding siblings ...)
2025-10-01 22:28 ` [PATCH v4 0/5] doc: git-push: clarify DESCRIPTION section D. Ben Knoble
@ 2025-10-06 18:58 ` Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 1/5] doc: git-push: clarify intro Julia Evans via GitGitGadget
` (6 more replies)
6 siblings, 7 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-10-06 18:58 UTC (permalink / raw)
To: git; +Cc: D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans
I surveyed 16 Git users about the git push man page. Here's a rewrite of the
DESCRIPTION section and the definition of <refspec> based on the feedback.
The goal is to clarify it while communicating the same information. The most
common piece of feedback was that folks didn't understand what the term
"ref" means. Most of the users who said they did not understand the term
"ref" have been using Git for 10+ years.
changes in v2:
* The biggest change is to add a new UPSTREAM BRANCHES section to explain
what an upstream is
* Drop the "refspec" changes from this patch series, I've made revisions to
them based on the comments here but I felt like this was getting too big.
* Added some backticks `` that I'd missed, from Ben's review
* From Junio's review, "The current branch must have a configured upstream
with the same name, so this will fail when pushing a new branch" was not
true, so replace it with a less detailed but hopefully true statement.
After a very long conversation with Ben I realized that actually
push.default=simple's behaviour is not really that simple (perhaps I
should think of it as more "safe" than "simple", since "current" seems
simpler), so it's more realistic to refer any questions to the
CONFIGURATION section which describes the behaviour in more detail.
* Rewrite all the commits to explain the problem they're trying to solve &
thinking behind them in more detail. Let me know if I added too much /
not enough detail.
changes in v3:
* mention that git push also needs to send data in addition to updating the
branch, from Junio's review
* fix a newline, from Junio's review
* un-rename urls-remotes.adoc, from Junio's review
* mention pushRemote and git checkout in the UPSTREAM BRANCHES section and
be clearer about what's meant by "the relationship between the current
branch and the upstream", from Junio's review
* fix AsciiDoc formatting issue, from Junio's review
changes in v4:
* Add "the simplest way to push is git push <remote> <branch>" at the
beginning since (as discussed) this is the form of git push that's
easiest to explain.
* Remove "as a safety measure" since (as discussed with Junio) the reason
that git push sometimes requires you to set an upstream is very
confusing, and "as a safety measure..." makes it sound more principled
than it is. Also update the commit message to say that the previous
explanation was not describing push.default=simple's behaviour
accurately.
* Reword "To decide which repository to push to..." because I felt like it
was still phrased in a clunky way.
* Make UPSTREAM BRANCHES and CONFIGURATION into actual links in the HTML
docs
* Fix formatting in UPSTREAM BRANCHES section, from Junio's review
* Fix some commit message mistakes, from Junio's review
changes in v5:
* remove a bad example of git branch --track, from Junio's review
* fix some formatting issues, from Jean-Noël's review
Julia Evans (5):
doc: git-push: clarify intro
doc: add an UPSTREAM BRANCHES section to pull/push/fetch
doc: git-push: clarify "where to push"
doc: git-push: clarify "what to push"
doc: git-push: Add explanation of `git push origin main`
Documentation/git-push.adoc | 46 +++++++++++++++++++--------------
Documentation/urls-remotes.adoc | 42 ++++++++++++++++++++++++++++++
2 files changed, 68 insertions(+), 20 deletions(-)
base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/1964
Range-diff vs v4:
1: d3160fb0af = 1: 4811ce1c86 doc: git-push: clarify intro
2: 69825d4634 ! 2: 10a9718421 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
@@ Documentation/urls-remotes.adoc: git push uses:
------------
--
--
-+UPSTREAM BRANCHES[[UPSTREAM-BRANCHES]]
-+--------------------------------------
++[[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:
@@ Documentation/urls-remotes.adoc: git push uses:
+
+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
-+
+
++------------
++[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`,
++`git push --set-upstream <remote> <branch>`
+but Git will often automatically set the upstream for you, for example:
+
+* When you clone a repository, Git will automatically set the upstream
3: 244c35ef2b = 3: 336023fbf1 doc: git-push: clarify "where to push"
4: c1d4ea8d27 ! 4: 8e82c508f6 doc: git-push: clarify "what to push"
@@ Documentation/git-push.adoc: a `git gc` command on the origin repository.
include::transfer-data-leaks.adoc[]
--CONFIGURATION
-+CONFIGURATION[[CONFIGURATION]]
++[[CONFIGURATION]]
+ CONFIGURATION
-------------
- include::includes/cmd-config-section-all.adoc[]
5: 9435f0ce8d = 5: ddeb8ecabe doc: git-push: Add explanation of `git push origin main`
--
gitgitgadget
^ permalink raw reply [flat|nested] 87+ messages in thread* [PATCH v5 1/5] doc: git-push: clarify intro
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
@ 2025-10-06 18:58 ` 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
` (5 subsequent siblings)
6 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-10-06 18:58 UTC (permalink / raw)
To: git
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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.
Many users also commented that receive hooks do not seem like the most
important thing to know about `git push`, and that this information
should not be the second sentence in the man page.
Use more familiar language to make it more accessible to users who do
not know what a "ref" is and move the "hooks" comment to the end.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index d1978650d6..25d972f248 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -19,12 +19,9 @@ SYNOPSIS
DESCRIPTION
-----------
-Updates remote refs using local refs, while sending objects
-necessary to complete the given refs.
-
-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].
+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.
When the command line does not specify where to push with the
`<repository>` argument, `branch.*.remote` configuration for the
@@ -44,6 +41,10 @@ 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]]
------------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v5 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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 ` Julia Evans via GitGitGadget
2025-10-07 12:23 ` Kristoffer Haugsbakk
2025-10-06 18:58 ` [PATCH v5 3/5] doc: git-push: clarify "where to push" Julia Evans via GitGitGadget
` (4 subsequent siblings)
6 siblings, 1 reply; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-10-06 18:58 UTC (permalink / raw)
To: git
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
---
Documentation/urls-remotes.adoc | 42 +++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)
diff --git a/Documentation/urls-remotes.adoc b/Documentation/urls-remotes.adoc
index 9b10151198..57b1646d3e 100644
--- a/Documentation/urls-remotes.adoc
+++ b/Documentation/urls-remotes.adoc
@@ -92,5 +92,47 @@ git push uses:
------------
+[[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>`
+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".
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v5 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
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
0 siblings, 1 reply; 87+ messages in thread
From: Kristoffer Haugsbakk @ 2025-10-07 12:23 UTC (permalink / raw)
To: Josh Soref, git; +Cc: D. Ben Knoble, Jean-Noël AVILA, Julia Evans
On Mon, Oct 6, 2025, at 20:58, Julia Evans via GitGitGadget wrote:
>[snip]
>
> 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.
nit: s/either/, either/ ?
I think that would flow better given the long distance between the last
punctuation/comma and the end of the sentence.
>
> 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
nit: s/upstreams branches/upstream branches/
> mistakenly think that their branch does not have an upstream branch if
> they didn't explicitly set one.
>
>[snip]
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v5 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
2025-10-07 12:23 ` Kristoffer Haugsbakk
@ 2025-10-07 13:35 ` Julia Evans
2025-10-07 18:35 ` D. Ben Knoble
0 siblings, 1 reply; 87+ messages in thread
From: Julia Evans @ 2025-10-07 13:35 UTC (permalink / raw)
To: Kristoffer Haugsbakk, Julia Evans, git
Cc: D. Ben Knoble, Jean-Noël AVILA
On Tue, Oct 7, 2025, at 8:23 AM, Kristoffer Haugsbakk wrote:
> On Mon, Oct 6, 2025, at 20:58, Julia Evans via GitGitGadget wrote:
>>[snip]
>>
>> 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.
>
> nit: s/either/, either/ ?
>
> I think that would flow better given the long distance between the last
> punctuation/comma and the end of the sentence.
Is it the norm in this project to provide detailed copy editing feedback
on commit messages like this? Of course it's important for commit
messages to be accurate and to explain the motivation behind the
changes, but I'm surprised by the attention to commas.
>>
>> 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
>
> nit: s/upstreams branches/upstream branches/
Will fix this typo if there's anything else to address (or if folks think that this
is worth a re-roll on its own, not sure what the norms are).
^ permalink raw reply [flat|nested] 87+ messages in thread
* Re: [PATCH v5 2/5] doc: add an UPSTREAM BRANCHES section to pull/push/fetch
2025-10-07 13:35 ` Julia Evans
@ 2025-10-07 18:35 ` D. Ben Knoble
0 siblings, 0 replies; 87+ messages in thread
From: D. Ben Knoble @ 2025-10-07 18:35 UTC (permalink / raw)
To: Julia Evans; +Cc: Kristoffer Haugsbakk, Julia Evans, git, Jean-Noël AVILA
On Tue, Oct 7, 2025 at 9:35 AM Julia Evans <julia@jvns.ca> wrote:
>
> On Tue, Oct 7, 2025, at 8:23 AM, Kristoffer Haugsbakk wrote:
> > On Mon, Oct 6, 2025, at 20:58, Julia Evans via GitGitGadget wrote:
> >>[snip]
> >>
> >> 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.
> >
> > nit: s/either/, either/ ?
> >
> > I think that would flow better given the long distance between the last
> > punctuation/comma and the end of the sentence.
>
> Is it the norm in this project to provide detailed copy editing feedback
> on commit messages like this? Of course it's important for commit
> messages to be accurate and to explain the motivation behind the
> changes, but I'm surprised by the attention to commas.
AFAIK, yes, though I can see how it might appear discouraging to
irregular contributors.
>
> >>
> >> 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
> >
> > nit: s/upstreams branches/upstream branches/
>
> Will fix this typo if there's anything else to address (or if folks think that this
> is worth a re-roll on its own, not sure what the norms are).
It usually ends up depending on whether Junio applies the typo-fixes
locally, I think. If there's nothing else and Junio grabs these, then
we probably don't need another re-roll.
--
D. Ben Knoble
^ permalink raw reply [flat|nested] 87+ messages in thread
* [PATCH v5 3/5] doc: git-push: clarify "where to push"
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-06 18:58 ` Julia Evans via GitGitGadget
2025-10-06 18:58 ` [PATCH v5 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
` (3 subsequent siblings)
6 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-10-06 18:58 UTC (permalink / raw)
To: git
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
It's not obvious that "`branch.*.remote` configuration"` refers to the
upstream, so say "upstream" instead.
The sentence is also quite hard to parse right now, use "defaults to" to
simplify it.
Signed-off-by: Julia Evans <julia@jvns.ca>
---
Documentation/git-push.adoc | 6 ++----
1 file changed, 2 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 25d972f248..acdf25e5cd 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -23,10 +23,8 @@ 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.
-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'.
+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
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v5 4/5] doc: git-push: clarify "what to push"
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
` (2 preceding siblings ...)
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 ` 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
` (2 subsequent siblings)
6 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-10-06 18:58 UTC (permalink / raw)
To: git
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
---
Documentation/git-push.adoc | 27 +++++++++++++++------------
1 file changed, 15 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index acdf25e5cd..aa01efcc0a 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 `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,6 +698,7 @@ a `git gc` command on the origin repository.
include::transfer-data-leaks.adoc[]
+[[CONFIGURATION]]
CONFIGURATION
-------------
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* [PATCH v5 5/5] doc: git-push: Add explanation of `git push origin main`
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
` (3 preceding siblings ...)
2025-10-06 18:58 ` [PATCH v5 4/5] doc: git-push: clarify "what " Julia Evans via GitGitGadget
@ 2025-10-06 18:58 ` 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
6 siblings, 0 replies; 87+ messages in thread
From: Julia Evans via GitGitGadget @ 2025-10-06 18:58 UTC (permalink / raw)
To: git
Cc: D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
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 <julia@jvns.ca>
---
Documentation/git-push.adoc | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index aa01efcc0a..36bf1cc438 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`.
+
The `<repository>` argument defaults to the upstream for the current branch,
or `origin` if there's no configured upstream.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 87+ messages in thread* Re: [PATCH v5 0/5] doc: git-push: clarify DESCRIPTION section
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
` (4 preceding siblings ...)
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 ` D. Ben Knoble
2025-10-06 22:07 ` Junio C Hamano
6 siblings, 0 replies; 87+ messages in thread
From: D. Ben Knoble @ 2025-10-06 21:53 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, Kristoffer Haugsbakk, Jean-Noël AVILA, Julia Evans
On Mon, Oct 6, 2025 at 2:58 PM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> changes in v5:
>
> * remove a bad example of git branch --track, from Junio's review
> * fix some formatting issues, from Jean-Noël's review
>
> Julia Evans (5):
> doc: git-push: clarify intro
> doc: add an UPSTREAM BRANCHES section to pull/push/fetch
> doc: git-push: clarify "where to push"
> doc: git-push: clarify "what to push"
> doc: git-push: Add explanation of `git push origin main`
>
> Documentation/git-push.adoc | 46 +++++++++++++++++++--------------
> Documentation/urls-remotes.adoc | 42 ++++++++++++++++++++++++++++++
> 2 files changed, 68 insertions(+), 20 deletions(-)
>
>
> base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v5
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v5
> Pull-Request: https://github.com/gitgitgadget/git/pull/1964
>
> Range-diff vs v4:
No complaints from me, and range-diff looks good.
Thanks again!
^ permalink raw reply [flat|nested] 87+ messages in thread* Re: [PATCH v5 0/5] doc: git-push: clarify DESCRIPTION section
2025-10-06 18:58 ` [PATCH v5 " Julia Evans via GitGitGadget
` (5 preceding siblings ...)
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
6 siblings, 0 replies; 87+ messages in thread
From: Junio C Hamano @ 2025-10-06 22:07 UTC (permalink / raw)
To: Julia Evans via GitGitGadget
Cc: git, D. Ben Knoble, Kristoffer Haugsbakk, Jean-Noël AVILA,
Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> I surveyed 16 Git users about the git push man page. Here's a rewrite of the
> DESCRIPTION section and the definition of <refspec> based on the feedback.
> The goal is to clarify it while communicating the same information. The most
> common piece of feedback was that folks didn't understand what the term
> "ref" means. Most of the users who said they did not understand the term
> "ref" have been using Git for 10+ years.
> ...
> changes in v5:
>
> * remove a bad example of git branch --track, from Junio's review
> * fix some formatting issues, from Jean-Noël's review
Thanks for working on this; I have no further comments to add.
Shall we mark the topic for 'next'?
^ permalink raw reply [flat|nested] 87+ messages in thread