Hi,
The re-roll was necessary due to minor/silly mistakes in v2, as
pointed out by Junio.
The builtin/shortlog.c patch has moved to the end until we change
'<since>..<until>' to '<revision range>' everywhere else. We use
'<revision range>' here too.
[4/7] has been replaced with the version Junio fixed up and put in
`pu`.
[6/7] has been updated to copy sections from log.txt properly, and
omit the "see below for History Simplification" part.
Thanks.
Ramkumar Ramachandra (7):
git-shortlog.txt: remove (-h|--help) from OPTIONS
revisions.txt: clarify the .. and ... syntax
git-log.txt: order OPTIONS properly; move <since>..<until>
git-log.txt: generalize <since>..<until>
git-log.txt: rewrite note on why "--" may be required
git-shortlog.txt: make SYNOPSIS match log, update OPTIONS
builtin/shortlog.c: make usage string consistent with log
Documentation/git-log.txt | 22 ++++++++++++----------
Documentation/git-shortlog.txt | 23 +++++++++++++++++------
Documentation/revisions.txt | 6 ++++--
builtin/shortlog.c | 4 +---
4 files changed, 34 insertions(+), 21 deletions(-)
--
1.8.2.1.501.gd2949c7
In its current form, the note talks about separating options from
"branch names" and "refnames" in the same sentence. This is entirely
inaccurate, as <revision range> need not be a set of branch names or
ref names. Rewrite it to use the word "revision range", to be
consistent with the SYNOPSIS.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Documentation/git-log.txt | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
@@ -77,8 +77,8 @@ produced by --stat etc. 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[]
'<since>..<until>' is misleading, as there are many other forms that
'git log' can accept as an argument. Replace it with <revision range>,
referring to the section "Specifying Ranges" in revisions.txt, and
rewrite the section appropriately.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Documentation/git-log.txt | 16 +++++++++-------
1 file changed, 9 insertions(+), 7 deletions(-)
@@ -62,12 +62,14 @@ produced by --stat etc. Note that only message is considered, if also a diff is shown its size is not included.-<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].+<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
To be consistent with the documentation of all the other commands,
remove (-h|--help) from the OPTIONS section.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Documentation/git-shortlog.txt | 4 ----
1 file changed, 4 deletions(-)
@@ -26,10 +26,6 @@ reference to the current repository. OPTIONS ---------h::---help::- Print a short usage message and exit.- -n:: --numbered:: Sort output according to the number of commits per author instead
The OPTIONS section lists <since>..<until> as the first item, but this
is inconsistent with the ordering in SYNOPSIS. Move it down until it
appears just before [[--] <path>...].
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Documentation/git-log.txt | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
@@ -24,13 +24,6 @@ each commit introduces are shown. 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,6 +62,13 @@ produced by --stat etc. Note that only message is considered, if also a diff is shown its size is not included.+<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].+ [\--] <path>...:: Show only commits that are enough to explain how the files that match the specified paths came to be. See "History
In <rev1>..<rev2> and <rev1>...<rev2>, if either <rev1> or <rev2> is
omitted, it defaults to 'HEAD'. Add this detail to the document.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Documentation/revisions.txt | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
@@ -244,11 +244,13 @@ To summarize: '<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
There are broadly two problems with the current SYNOPSIS. First, it
completely omits the detail that paths can be specified. Second, it
attempts to list all the options: this is futile as, in addition to
the options unique to it, it accepts all the options that git-rev-list
accepts. In fixing these problems, make the SYNOPSIS consistent with
that in git-log.txt. Also add the corresponding sections to OPTIONS.
Save adding the options from rev-list-options.txt for a later patch,
as it requires some work to pick out the options that are relevant to
shortlog.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Documentation/git-shortlog.txt | 19 +++++++++++++++++--
1 file changed, 17 insertions(+), 2 deletions(-)
@@ -56,6 +56,21 @@ OPTIONS 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 ---------------
"--" is used to separate pathspecs from the rev specs, and not rev
specs from the options, as the shortlog_usage string currently
indicates. In correcting this usage string, make it consistent with
the log_usage string.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
builtin/shortlog.c | 4 +---
1 file changed, 1 insertion(+), 3 deletions(-)
Replace '<since>..<until>' with '<revision range>', in accordance with
the documentation.
Signed-off-by: Ramkumar Ramachandra <redacted>
---
Junio: sorry I missed this detail. Can you squeeze this patch
between [6/7] and [7/7] so that the commit message in [7/7] makes
sense?
Thanks.
builtin/log.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)