From 5b696cb390385f4906df411be917ef0a7b92ebb7 Mon Sep 17 00:00:00 2001
From: Julia Evans <julia@jvns.ca>
Date: Mon, 6 Oct 2025 18:58:47 +0000
Subject: doc: git-push: clarify intro

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-push.adoc | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

(limited to 'Documentation/git-push.adoc')

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 5f5408e2c0..2b7f7de9dd 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]]
 ------------------
-- 
cgit v1.3-5-g9baa


From 3856d8937817c6815ecabaa3a927fc2e124e8155 Mon Sep 17 00:00:00 2001
From: Julia Evans <julia@jvns.ca>
Date: Mon, 6 Oct 2025 18:58:49 +0000
Subject: doc: git-push: clarify "where to push"

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-push.adoc | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

(limited to 'Documentation/git-push.adoc')

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 2b7f7de9dd..808e0380b2 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
-- 
cgit v1.3-5-g9baa


From 6e1688f1f462d7a704bbcc1dae612488b7ac6e29 Mon Sep 17 00:00:00 2001
From: Julia Evans <julia@jvns.ca>
Date: Mon, 6 Oct 2025 18:58:50 +0000
Subject: doc: git-push: clarify "what to push"

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-push.adoc | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

(limited to 'Documentation/git-push.adoc')

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 808e0380b2..484aa9025e 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
@@ -702,6 +704,7 @@ a `git gc` command on the origin repository.
 
 include::transfer-data-leaks.adoc[]
 
+[[CONFIGURATION]]
 CONFIGURATION
 -------------
 
-- 
cgit v1.3-5-g9baa


From a72504fe051272227f4097e8d664a9b7d871ec25 Mon Sep 17 00:00:00 2001
From: Julia Evans <julia@jvns.ca>
Date: Mon, 6 Oct 2025 18:58:51 +0000
Subject: doc: git-push: add explanation of `git push origin main`

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-push.adoc | 4 ++++
 1 file changed, 4 insertions(+)

(limited to 'Documentation/git-push.adoc')

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 484aa9025e..f187fd5934 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.
 
-- 
cgit v1.3-5-g9baa

