# [PATCH v3 0/7] Documentation/shortlog improvements 13 messages from 2013-04-22 to 2013-04-29. Participants: Ramkumar Ramachandra, Junio C Hamano. Thread: https://gitlist.dev/t/33565 ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH v3 0/7] Documentation/shortlog improvements Message-ID: <1366608631-21734-1-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-1-git-send-email-artagnon%40gmail.com ``` 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 '..' to '' everywhere else. We use '' 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 .. git-log.txt: generalize .. 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 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 1/7] git-shortlog.txt: remove (-h|--help) from OPTIONS Message-ID: <1366608631-21734-2-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-2-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` To be consistent with the documentation of all the other commands, remove (-h|--help) from the OPTIONS section. Signed-off-by: Ramkumar Ramachandra --- Documentation/git-shortlog.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index c308e91..c7f7f51 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -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 -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 2/7] revisions.txt: clarify the .. and ... syntax Message-ID: <1366608631-21734-3-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-3-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` In .. and ..., if either or is omitted, it defaults to 'HEAD'. Add this detail to the document. Signed-off-by: Ramkumar Ramachandra --- Documentation/revisions.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 8855b1a..0a23129 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -244,11 +244,13 @@ To summarize: '..':: Include commits that are reachable from but exclude - those that are reachable from . + those that are reachable from . When either or + is omitted, it defaults to 'HEAD'. '\...':: Include commits that are reachable from either or - but exclude those that are reachable from both. + but exclude those that are reachable from both. When + either or is omitted, it defaults to 'HEAD'. '{caret}@', e.g. 'HEAD{caret}@':: A suffix '{caret}' followed by an at sign is the same as listing -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 3/7] git-log.txt: order OPTIONS properly; move .. Message-ID: <1366608631-21734-4-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-4-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` The OPTIONS section lists .. as the first item, but this is inconsistent with the ordering in SYNOPSIS. Move it down until it appears just before [[--] ...]. Signed-off-by: Ramkumar Ramachandra --- Documentation/git-log.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 69db578..64cc337 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -24,13 +24,6 @@ each commit introduces are shown. OPTIONS ------- -..:: - Show only commits between the named two commits. When - either or is omitted, it defaults to - `HEAD`, i.e. the tip of the current branch. - For a more complete list of ways to spell - and , 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. +..:: + Show only commits between the named two commits. When + either or is omitted, it defaults to + `HEAD`, i.e. the tip of the current branch. + For a more complete list of ways to spell + and , see linkgit:gitrevisions[7]. + [\--] ...:: Show only commits that are enough to explain how the files that match the specified paths came to be. See "History -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 4/7] git-log.txt: generalize .. Message-ID: <1366608631-21734-5-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-5-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` '..' is misleading, as there are many other forms that 'git log' can accept as an argument. Replace it with , referring to the section "Specifying Ranges" in revisions.txt, and rewrite the section appropriately. Signed-off-by: Ramkumar Ramachandra --- Documentation/git-log.txt | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 64cc337..9576695 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -9,7 +9,7 @@ git-log - Show commit logs SYNOPSIS -------- [verse] -'git log' [] [..] [[\--] ...] +'git log' [] [] [[\--] ...] DESCRIPTION ----------- @@ -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. -..:: - Show only commits between the named two commits. When - either or is omitted, it defaults to - `HEAD`, i.e. the tip of the current branch. - For a more complete list of ways to spell - and , see linkgit:gitrevisions[7]. +:: + Show only commits in the specified revision range. When no + 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 , see the "Specifying Ranges" + section of linkgit:gitrevisions[7]. [\--] ...:: Show only commits that are enough to explain how the files -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 5/7] git-log.txt: rewrite note on why "--" may be required Message-ID: <1366608631-21734-6-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-6-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` In its current form, the note talks about separating options from "branch names" and "refnames" in the same sentence. This is entirely inaccurate, as 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 --- Documentation/git-log.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 9576695..a976534 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -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[] -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 6/7] git-shortlog.txt: make SYNOPSIS match log, update OPTIONS Message-ID: <1366608631-21734-7-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-7-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` 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 --- Documentation/git-shortlog.txt | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/Documentation/git-shortlog.txt b/Documentation/git-shortlog.txt index c7f7f51..31af7f2 100644 --- a/Documentation/git-shortlog.txt +++ b/Documentation/git-shortlog.txt @@ -8,8 +8,8 @@ git-shortlog - Summarize 'git log' output SYNOPSIS -------- [verse] -git log --pretty=short | 'git shortlog' [-h] [-n] [-s] [-e] [-w] -'git shortlog' [-n|--numbered] [-s|--summary] [-e|--email] [-w[[,[,]]]] ... +git log --pretty=short | 'git shortlog' [] +'git shortlog' [] [] [[\--] ...] DESCRIPTION ----------- @@ -56,6 +56,21 @@ OPTIONS If width is `0` (zero) then indent the lines of the output without wrapping them. +:: + Show only commits in the specified revision range. When no + 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 , see the "Specifying Ranges" + section of linkgit:gitrevisions[7]. + +[\--] ...:: + 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 --------------- -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 05:30 Subject: [PATCH 7/7] builtin/shortlog.c: make usage string consistent with log Message-ID: <1366608631-21734-8-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366608631-21734-8-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-1-git-send-email-artagnon@gmail.com> ``` "--" 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 --- builtin/shortlog.c | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) 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] [--] [... ]"), - "", - N_("[rev-opts] are documented in git-rev-list(1)"), + N_("git shortlog [] [] [[--] [...]]"), NULL }; -- 1.8.2.1.501.gd2949c7 ``` ## Ramkumar Ramachandra, 2013-04-22 07:20 Subject: [PATCH 6.5/7] builtin/log.c: make usage string consistent with doc Message-ID: <1366615244-21825-1-git-send-email-artagnon@gmail.com> URL: https://gitlist.dev/e/1366615244-21825-1-git-send-email-artagnon%40gmail.com In-Reply-To: <1366608631-21734-8-git-send-email-artagnon@gmail.com> ``` Replace '..' with '', in accordance with the documentation. Signed-off-by: Ramkumar Ramachandra --- 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(-) 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_patch_subject_prefix = "PATCH"; static const char *fmt_pretty; static const char * const builtin_log_usage[] = { - N_("git log [] [..] [[--] ...]\n") + N_("git log [] [] [[--] ...]\n") N_(" or: git show [options]