git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v2] doc: clarify push.default=simple behavior

From
IGIvan Baluta via GitGitGadget <gitgitgadget@gmail.com>
Date
May 26, 2026, 03:58 UTC
Message-ID
<pull.2115.v2.git.1779767888508.gitgitgadget@gmail.com>
In-Reply-To
<pull.2115.git.1779433093971.gitgitgadget@gmail.com>
From: Ivan Baluta <ivanbaluta.dev@gmail.com>

The documentation for the 'simple' push mode currently singles out the centralized workflow, which can cause confusion about its behavior in other scenarios, such as triangular workflows.

Clarify that 'simple' always pushes the current branch to a branch of the same name, but only enforces the strict upstream tracking requirement when pushing back to the same remote being pulled from.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Ivan Baluta <ivanbaluta.dev@gmail.com>
---
    doc: clarify push.default=simple in triangular workflows
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2115%2Fivanbaluta%2Fdoc-push-simple-triangular-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2115/ivanbaluta/doc-push-simple-triangular-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2115
Range-diff vs v1:
 1:  37ff842622 ! 1:  3deb7f5b0c doc: clarify push.default=simple in triangular workflows
     @@
       ## Metadata ##
     -Author: ivanbaluta <ivanbaluta.dev@gmail.com>
     +Author: Ivan Baluta <ivanbaluta.dev@gmail.com>
      
       ## Commit message ##
     -    doc: clarify push.default=simple in triangular workflows
     +    doc: clarify push.default=simple behavior
      
     -    The documentation for 'simple' push mode currently focuses on the
     -    centralized workflow. However, the implementation in builtin/push.c
     -    falls back to 'current' behavior when pushing to a remote different
     -    from the upstream (a triangular workflow).
     +    The documentation for the 'simple' push mode currently singles out
     +    the centralized workflow, which can cause confusion about its
     +    behavior in other scenarios, such as triangular workflows.
      
     -    Clarify this in the manual to align the documentation with the
     -    long-standing implementation and prevent user confusion.
     +    Clarify that 'simple' always pushes the current branch to a branch
     +    of the same name, but only enforces the strict upstream tracking
     +    requirement when pushing back to the same remote being pulled from.
      
     -    Signed-off-by: ivanbaluta <ivanbaluta.dev@gmail.com>
     +    Suggested-by: Junio C Hamano <gitster@pobox.com>
     +    Signed-off-by: Ivan Baluta <ivanbaluta.dev@gmail.com>
      
       ## Documentation/config/push.adoc ##
     -@@ Documentation/config/push.adoc: 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.
     +@@ Documentation/config/push.adoc: this is a deprecated synonym for `upstream`.
     + `simple`;;
     + push the current branch with the same name on the remote.
     + +
     +-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.
     ++This mode requires that the remote repository to be pushed to is
     ++known.  When pushing back to the same remote you pull from, the
     ++current branch must also have an upstream tracking branch with the
     ++same name.
       +
     -+In a triangular workflow (pushing to a remote different from the upstream),
     -+`simple` behaves like `current`.
     -++
       This mode is the default since Git 2.0, and is the safest option suited for
       beginners.
     - 
 Documentation/config/push.adoc | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/config/push.adoc b/Documentation/config/push.adoc
index d9112b2260..28132eedfe 100644
--- a/Documentation/config/push.adoc
+++ b/Documentation/config/push.adoc
@@ -41,9 +41,10 @@ this is a deprecated synonym for `upstream`.
 `simple`;;
 push the current branch with the same name on the remote.
 +
-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.
+This mode requires that the remote repository to be pushed to is
+known.  When pushing back to the same remote you pull from, the
+current branch must also have an upstream tracking branch with the
+same name.
 +
 This mode is the default since Git 2.0, and is the safest option suited for
 beginners.

base-commit: 59ff4886a579f4bc91e976fe18590b9ae02c7a08
-- 
gitgitgadget
Previous: Иван БалутаNext: Junio C Hamano
Message 4 of 5 in “doc: clarify push.default=simple in triangular workflows”
  1. doc: clarify push.default=simple in triangular workflowsIvan Baluta via GitGitGadget, May 22, 2026
  2. Junio C HamanoMay 22, 2026
  3. Иван БалутаMay 25, 2026
  4. doc: clarify push.default=simple behaviorIvan Baluta via GitGitGadget, May 26, 2026
  5. Junio C HamanoJun 1, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.