Subject: [PATCH v2] docs: update description for '--mirror' option for 'git push'

From: "Gustavo Velasco-Hernández via GitGitGadget" <[email-masked]>
Date: Tue, 16 Sep 2025 16:03:48 +0000

From: "Velasco-Hernandez, Gustavo" <[email-masked]>

The current description considers only created, updated or deleted refs
locally. However it does not address the case where new refs were created
on the remote end, in which case, are also deleted. The description has
been reworded to describe what is removed, updated or added. (Based on
Junio feedback)

Signed-off-by: Gustavo Velasco-Hernandez <[email-masked]>
---
    Docs: Update description for '--mirror' option for 'git push'

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2028%2Fgustavovelascoh%2Fgit-push-update-docs-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2028/gustavovelascoh/git-push-update-docs-v2
Pull-Request: https://github.com/git/git/pull/2028

Range-diff vs v1:

 1:  2be0bf6e73 ! 1:  ab077544b6 docs: update description for '--mirror' option for 'git push'
     @@ Commit message
      
          The current description considers only created, updated or deleted refs
          locally. However it does not address the case where new refs were created
     -    on the remote end, in which case, are also deleted.
     +    on the remote end, in which case, are also deleted. The description has
     +    been reworded to describe what is removed, updated or added. (Based on
     +    Junio feedback)
      
          Signed-off-by: Gustavo Velasco-Hernandez <[email-masked]>
      
       ## Documentation/git-push.adoc ##
      @@ Documentation/git-push.adoc: already exists on the remote side.
     - 	be mirrored to the remote repository.  Newly created local
     - 	refs will be pushed to the remote end, locally updated refs
     - 	will be force updated on the remote end, and deleted refs
     + 	Instead of naming each ref to push, specifies that all
     + 	refs under `refs/` (which includes but is not
     + 	limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
     +-	be mirrored to the remote repository.  Newly created local
     +-	refs will be pushed to the remote end, locally updated refs
     +-	will be force updated on the remote end, and deleted refs
      -	will be removed from the remote end.  This is the default
      -	if the configuration option `remote.<remote>.mirror` is
      -	set.
     -+	will be removed from the remote end. Any ref existing
     -+	in the remote end, but not locally, will be removed too.
     -+	This is the default if the configuration option
     -+	`remote.<remote>.mirror` is set.
     ++	be mirrored to the remote repository. This overwrites the
     ++	refs at the remote by (1) removing what is only at the remote,
     ++	(2) force-updating what both ends of the connection have, and
     ++	(3) adding what only exists locally. This is the default if
     ++	the configuration option `remote.<remote>.mirror` is set.
       
       -n::
       --dry-run::

 Documentation/git-push.adoc | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
index 5f5408e2c0..77ce4a27c8 100644
--- a/Documentation/git-push.adoc
+++ b/Documentation/git-push.adoc
@@ -163,12 +163,11 @@ already exists on the remote side.
 	Instead of naming each ref to push, specifies that all
 	refs under `refs/` (which includes but is not
 	limited to `refs/heads/`, `refs/remotes/`, and `refs/tags/`)
-	be mirrored to the remote repository.  Newly created local
-	refs will be pushed to the remote end, locally updated refs
-	will be force updated on the remote end, and deleted refs
-	will be removed from the remote end.  This is the default
-	if the configuration option `remote.<remote>.mirror` is
-	set.
+	be mirrored to the remote repository. This overwrites the
+	refs at the remote by (1) removing what is only at the remote,
+	(2) force-updating what both ends of the connection have, and
+	(3) adding what only exists locally. This is the default if
+	the configuration option `remote.<remote>.mirror` is set.
 
 -n::
 --dry-run::

base-commit: a483264b01b977f3e65a4419103c21e6af7412a2
-- 
gitgitgadget