[PATCH] doc: clarify difference between `push.default` `simple` and `current`

From

Dan Fabulich via GitGitGadget <gitgitgadget@gmail.com>

Date

Jul 23, 2025, 23:00 UTC

Message-ID

<pull.1944.git.1753311625075.gitgitgadget@gmail.com>

From: Dan Fabulich <dan@fabulich.com>

Signed-off-by: Dan Fabulich <dan@fabulich.com>
---
    doc: clarify difference between push.default simple and current

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1944%2Fdfabulich%2Fgit-config-simple-doc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1944/dfabulich/git-config-simple-doc-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1944

 Documentation/config/push.adoc | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/Documentation/config/push.adoc b/Documentation/config/push.adoc
index 0acbbea18a3..3e03cb31606 100644
--- a/Documentation/config/push.adoc
+++ b/Documentation/config/push.adoc
@@ -15,7 +15,7 @@ push.default::
 	Different values are well-suited for
 	specific workflows; for instance, in a purely central workflow
 	(i.e. the fetch source is equal to the push destination),
-	`upstream` is probably what you want.  Possible values are:
+	`simple` is probably what you want.  Possible values are:
 +
 --
 
@@ -23,8 +23,8 @@ push.default::
   given. This is primarily meant for people who want to
   avoid mistakes by always being explicit.
 
-* `current` - push the current branch to update a branch with the same
-  name on the receiving end.  Works in both central and non-central
+* `current` - push the current branch to update the branch with the same
+  name on the remote.  Works in both central and non-central
   workflows.
 
 * `upstream` - push the current branch back to the branch whose
@@ -35,11 +35,13 @@ push.default::
 
 * `tracking` - This is a deprecated synonym for `upstream`.
 
-* `simple` - push the current branch with the same name on the remote.
+* `simple` - push the current branch to its upstream tracking branch,
+  but only if the upstream tracking branch has the same name as the
+  current branch. (`simple` will fail with an error if the upstream
+  tracking branch's name doesn't match the current branch's name.)
 +
-If you are working on a centralized workflow (pushing to the same repository you
-pull from, which is typically `origin`), then you need to configure an upstream
-branch with the same name.
+`simple` will also fail if the current branch doesn't have an upstream
+tracking branch configured, unless `push.autoSetupRemote` is enabled.
 +
 This mode is the default since Git 2.0, and is the safest option suited for
 beginners.

base-commit: 3f2a94875d2f41fe4758a439f68d8b73cfb19d0f

-- 
gitgitgadget