[PATCH] git-push.txt: Describe --repo option in more detail

[PATCH] git-push.txt: Describe --repo option in more detail

[Johannes Sixt]

From: Johannes Sixt <johannes.sixt@telecom.at>

The --repo option was described in a way that the reader would have to
assume that it is the same as the <repository> parameter. But it actually
servers a purpose, which is now written down.

Furthermore, the --mirror option was missing from the synopsis.

Signed-off-by: Johannes Sixt <johannes.sixt@telecom.at>
---
 I do not have the toolchain to format the documentation, so please take
 this with a grain of salt.

 -- Hannes

 Documentation/git-push.txt |   24 +++++++++++++++++++-----
 builtin-push.c             |    2 +-
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 45c9643..6150b1b 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -9,8 +9,8 @@ git-push - Update remote refs along with associated objects
 SYNOPSIS
 --------
 [verse]
-'git push' [--all] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
-	   [--repo=all] [-f | --force] [-v | --verbose]
+'git push' [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>]
+	   [--repo=<repository>] [-f | --force] [-v | --verbose]
 	   [<repository> <refspec>...]

 DESCRIPTION
@@ -101,9 +101,23 @@ nor in any Push line of the corresponding remotes file---see below).
 	This flag disables the check.  This can cause the
 	remote repository to lose commits; use it with care.

---repo=<repo>::
-	When no repository is specified the command defaults to
-	"origin"; this overrides it.
+--repo=<repository>::
+	This option is only relevant if no <repository> argument is
+	passed in the invocation. In this case, 'git-push' derives the
+	remote name from the current branch: If it tracks a remote
+	branch, then that remote repository is pushed to. Otherwise,
+	the name "origin" is used. For this latter case, this option
+	can be used to override the name "origin". In other words,
+	the difference between these two commands
++
+--------------------------
+git push public         #1
+git push --repo=public  #2
+--------------------------
++
+is that #1 always pushes to "public" whereas #2 pushes to "public"
+only if the current branch does not track a remote branch. This is
+useful if you write an alias or script around 'git-push'.

 --thin::
 --no-thin::
diff --git a/builtin-push.c b/builtin-push.c
index cc6666f..122fdcf 100644
--- a/builtin-push.c
+++ b/builtin-push.c
@@ -10,7 +10,7 @@
 #include "parse-options.h"

 static const char * const push_usage[] = {
-	"git push [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] [--repo=all] [-f | --force] [-v] [<repository> <refspec>...]",
+	"git push [--all | --mirror] [--dry-run] [--tags] [--receive-pack=<git-receive-pack>] [--repo=<repository>] [-f | --force] [-v] [<repository> <refspec>...]",
 	NULL,
 };

-- 
1.6.0.2.651.gd07df