Merge branch 'rr/shortlog-doc'
Update documentation for "log" and "shortlog".
* rr/shortlog-doc:
builtin/shortlog.c: make usage string consistent with log
builtin/log.c: make usage string consistent with doc
git-shortlog.txt: make SYNOPSIS match log, update OPTIONS
git-log.txt: rewrite note on why "--" may be required
git-log.txt: generalize <since>..<until>
git-log.txt: order OPTIONS properly; move <since>..<until>
revisions.txt: clarify the .. and ... syntax
git-shortlog.txt: remove (-h|--help) from OPTIONS
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 69db578..a976534 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -9,7 +9,7 @@
SYNOPSIS
--------
[verse]
-'git log' [<options>] [<since>..<until>] [[\--] <path>...]
+'git log' [<options>] [<revision range>] [[\--] <path>...]
DESCRIPTION
-----------
@@ -24,13 +24,6 @@
OPTIONS
-------
-<since>..<until>::
- Show only commits between the named two commits. When
- either <since> or <until> is omitted, it defaults to
- `HEAD`, i.e. the tip of the current branch.
- For a more complete list of ways to spell <since>
- and <until>, see linkgit:gitrevisions[7].
-
--follow::
Continue listing the history of a file beyond renames
(works only for a single file).
@@ -69,14 +62,23 @@
Note that only message is considered, if also a diff is shown
its size is not included.
+<revision range>::
+ Show only commits in the specified revision range. When no
+ <revision range> is specified, it defaults to `HEAD` (i.e. the
+ whole history leading to the current commit). `origin..HEAD`
+ specifies all the commits reachable from the current commit
+ (i.e. `HEAD`), but not from `origin`. For a complete list of
+ ways to spell <revision range>, see the "Specifying Ranges"
+ section of linkgit:gitrevisions[7].
+
[\--] <path>...::
Show only commits that are enough to explain how the files
that match the specified paths came to be. See "History
Simplification" below for details and other simplification
modes.
+
-To prevent confusion with options and branch names, paths may need to
-be prefixed with "\-- " to separate them from options or refnames.
+Paths may need to be prefixed with "\-- " to separate them from
+options or the revision range, when confusion arises.
include::rev-list-options.txt[]
diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt
index c308e91..31af7f2 100644
--- a/Documentation/git-shortlog.txt
+++ b/Documentation/git-shortlog.txt
@@ -8,8 +8,8 @@
SYNOPSIS
--------
[verse]
-git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w]
-'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[<width>[,<indent1>[,<indent2>]]]] <commit>...
+git log --pretty=short | 'git shortlog' [<options>]
+'git shortlog' [<options>] [<revision range>] [[\--] <path>...]
DESCRIPTION
-----------
@@ -26,10 +26,6 @@
OPTIONS
-------
--h::
---help::
- Print a short usage message and exit.
-
-n::
--numbered::
Sort output according to the number of commits per author instead
@@ -60,6 +56,21 @@
If width is `0` (zero) then indent the lines of the output without wrapping
them.
+<revision range>::
+ Show only commits in the specified revision range. When no
+ <revision range> is specified, it defaults to `HEAD` (i.e. the
+ whole history leading to the current commit). `origin..HEAD`
+ specifies all the commits reachable from the current commit
+ (i.e. `HEAD`), but not from `origin`. For a complete list of
+ ways to spell <revision range>, see the "Specifying Ranges"
+ section of linkgit:gitrevisions[7].
+
+[\--] <path>...::
+ Consider only commits that are enough to explain how the files
+ that match the specified paths came to be.
++
+Paths may need to be prefixed with "\-- " to separate them from
+options or the revision range, when confusion arises.
MAPPING AUTHORS
---------------
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index a8ff691..d477b3f 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -244,11 +244,13 @@
'<rev1>..<rev2>'::
Include commits that are reachable from <rev2> but exclude
- those that are reachable from <rev1>.
+ those that are reachable from <rev1>. When either <rev1> or
+ <rev2> is omitted, it defaults to 'HEAD'.
'<rev1>\...<rev2>'::
Include commits that are reachable from either <rev1> or
- <rev2> but exclude those that are reachable from both.
+ <rev2> but exclude those that are reachable from both. When
+ either <rev1> or <rev2> is omitted, it defaults to 'HEAD'.
'<rev>{caret}@', e.g. 'HEAD{caret}@'::
A suffix '{caret}' followed by an at sign is the same as listing
diff --git a/builtin/log.c b/builtin/log.c
index ad46f72..6e56a50 100644
--- a/builtin/log.c
+++ b/builtin/log.c
@@ -37,7 +37,7 @@
static const char *fmt_pretty;
static const char * const builtin_log_usage[] = {
- N_("git log [<options>] [<since>..<until>] [[--] <path>...]\n")
+ N_("git log [<options>] [<revision range>] [[--] <path>...]\n")
N_(" or: git show [options] <object>..."),
NULL
};
diff --git a/builtin/shortlog.c b/builtin/shortlog.c
index 240bff3..1fd6f8a 100644
--- a/builtin/shortlog.c
+++ b/builtin/shortlog.c
@@ -10,9 +10,7 @@
#include "parse-options.h"
static char const * const shortlog_usage[] = {
- N_("git shortlog [-n] [-s] [-e] [-w] [rev-opts] [--] [<commit-id>... ]"),
- "",
- N_("[rev-opts] are documented in git-rev-list(1)"),
+ N_("git shortlog [<options>] [<revision range>] [[--] [<path>...]]"),
NULL
};
