shell: Rewrite documentation and improve error message

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 22cff99b457646af2570718d401b7c7f74839aa4..b68abff28a0fe27fbcb2bbffa2296cffb1297eaf 100644 (file)
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -11,7 +11,7 @@ SYNOPSIS
 [verse]
 'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>]
           [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream]
-          [<repository> <refspec>...]
+          [<repository> [<refspec>...]]
 
 DESCRIPTION
 -----------
@@ -41,7 +41,7 @@ OPTIONS[[OPTIONS]]
 +
 The <src> is often the name of the branch you would want to push, but
 it can be any arbitrary "SHA-1 expression", such as `master~4` or
-`HEAD` (see linkgit:git-rev-parse[1]).
+`HEAD` (see linkgit:gitrevisions[1]).
 +
 The <dst> tells which ref on the remote side is updated with this
 push. Arbitrary expressions cannot be used here, an actual ref must
@@ -69,11 +69,11 @@ nor in any Push line of the corresponding remotes file---see below).
 
 --all::
        Instead of naming each ref to push, specifies that all
-       refs under `$GIT_DIR/refs/heads/` be pushed.
+       refs under `refs/heads/` be pushed.
 
 --mirror::
        Instead of naming each ref to push, specifies that all
-       refs under `$GIT_DIR/refs/` (which includes but is not
+       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
@@ -96,7 +96,7 @@ nor in any Push line of the corresponding remotes file---see below).
        the same as prefixing all refs with a colon.
 
 --tags::
-       All refs under `$GIT_DIR/refs/tags` are pushed, in
+       All refs under `refs/tags` are pushed, in
        addition to refspecs explicitly listed on the command
        line.
 
@@ -141,19 +141,27 @@ useful if you write an alias or script around 'git push'.
 
 --thin::
 --no-thin::
-       These options are passed to 'git send-pack'.  Thin
-       transfer spends extra cycles to minimize the number of
-       objects to be sent and meant to be used on slower connection.
+       These options are passed to linkgit:git-send-pack[1]. A thin transfer
+       significantly reduces the amount of sent data when the sender and
+       receiver share many of the same objects in common. The default is
+       \--thin.
 
 -q::
 --quiet::
        Suppress all output, including the listing of updated refs,
-       unless an error occurs.
+       unless an error occurs. Progress is not reported to the standard
+       error stream.
 
 -v::
 --verbose::
        Run verbosely.
 
+--progress::
+       Progress status is reported on the standard error stream
+       by default when it is attached to a terminal, unless -q
+       is specified. This flag forces progress status even if the
+       standard error stream is not directed to a terminal.
+
 include::urls-remotes.txt[]
 
 OUTPUT