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