From: "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: "Thomas Rast" <tr@thomasrast.ch>,
"Junio C Hamano" <gitster@pobox.com>,
"Matthieu Moy" <Matthieu.Moy@imag.fr>,
"SZEDER Gábor" <szeder.dev@gmail.com>,
"Derrick Stolee" <stolee@gmail.com>,
"Junio C Hamano" <gitster@pobox.com>
Subject: [PATCH v2 0/2] Improve line log documentation
Date: Thu, 26 Dec 2019 17:43:35 +0000 [thread overview]
Message-ID: <pull.494.v2.git.1577382217.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.494.git.1576559263.gitgitgadget@gmail.com>
These two patches add more information to the documentation for line history
(git log -L) :
* Mention explicitly that only the --patch and --no-patch diff formats are
supported
* Mention that parameters <start>, <end> and <funcname> must exist in the
starting revision
Regarding point 2 : I stumbled upon this while reading the history of
'filter_refs' in fetch-pack.c. I did
git log -s -L :filter_refs:fetch-pack.c
which shows a list of commits starting with 745f7a8cac (fetch-pack: move
core code to libgit.a, 2012-10-26). So then I did
git log -s -L :filter_refs:fetch-pack.c -L :filter_refs:builtin/fetch-pack.c
which fails with
fatal: -L parameter 'filter_refs' starting at line 1: no match
Changes since v1:
* Shorten the commit titles
* Use long options names for --patch and --no-patch
* Remove inexact mention of --function-context
* Reword the clarification regarding <start>, <end> and <funcname> so that
it doesn't apply only to regex parameters
* Also add this clarification to Documentation/gitk.txt since it applies
there as well
Philippe Blain (2):
doc: log, gitk: document accepted line-log diff formats
doc: log, gitk: line-log arguments must exist in starting revision
Documentation/git-log.txt | 8 ++++++--
Documentation/gitk.txt | 8 ++++++--
2 files changed, 12 insertions(+), 4 deletions(-)
base-commit: ad05a3d8e5a6a06443836b5e40434262d992889a
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-494%2Fphil-blain%2Fline-log-doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-494/phil-blain/line-log-doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/494
Range-diff vs v1:
1: 0ed04a8629 ! 1: e68ef0ced3 Documentation/git-log: document accepted line-log diff formats
@@ -1,18 +1,16 @@
Author: Philippe Blain <levraiphilippeblain@gmail.com>
- Documentation/git-log: document accepted line-log diff formats
+ doc: log, gitk: document accepted line-log diff formats
Currently the line-log functionality (git log -L) only supports
- displaying patch output (`-p`, its default behavior) and suppressing it
- (`-s`). A check was added in the code to that effect in 5314efaea (line-log:
- detect unsupported formats, 2019-03-10) but the documentation was not
+ displaying patch output (`-p | --patch`, its default behavior) and suppressing it
+ (`-s | --no-patch`). A check was added in the code to that effect in 5314efaea
+ (line-log: detect unsupported formats, 2019-03-10) but the documentation was not
updated.
Explicitly mention that `-L` implies `-p`, that patch output can be
suppressed using `-s`, and that all other diff formats are not allowed.
- Additionnally, mention that the ':<funcname>' form implies `--function-context`.
-
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
@@ -24,8 +22,7 @@
give zero or one positive revision arguments.
- You can specify this option more than once.
+ You can specify this option more than once. Implies `--patch`.
-+ If ``:<funcname>'' is given, implies `--function-context`.
-+ Patch output can be suppressed using `-s`, but other diff formats
++ Patch output can be suppressed using `--no-patch`, but other diff formats
+ (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
+ `--name-only`, `--name-status`, `--check`) are not currently implemented.
+
@@ -41,8 +38,7 @@
give zero or one positive revision arguments.
- You can specify this option more than once.
+ You can specify this option more than once. Implies `--patch`.
-+ If ``:<funcname>'' is given, implies `--function-context`.
-+ Patch output can be suppressed using `-s`, but other diff formats
++ Patch output can be suppressed using `--no-patch`, but other diff formats
+ (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
+ `--name-only`, `--name-status`, `--check`) are not currently implemented.
+
2: 4ea4eeae0c ! 2: c7d489794c Documentation/git-log: mention that line-log regex must match in starting revision
@@ -1,10 +1,10 @@
Author: Philippe Blain <levraiphilippeblain@gmail.com>
- Documentation/git-log: mention that line-log regex must match in starting revision
+ doc: log, gitk: line-log arguments must exist in starting revision
- When giving a regex as parameter <start> or <end> in
- `git log -L <start>,<end>:<file>`, or a function name in
- `git log -L :<funcname>:<file>`, the given regex must match in the starting
+ The line number, regex or offset parameters <start> and <end> in
+ `git log -L <start>,<end>:<file>`, or the function name regex in
+ `git log -L :<funcname>:<file>` must exist in the starting
revision, or else the command exits with a fatal error.
This is not obvious in the documentation, so add a note to that
@@ -20,8 +20,22 @@
not give any pathspec limiters. This is currently limited to
a walk starting from a single revision, i.e., you may only
- give zero or one positive revision arguments.
-+ give zero or one positive revision arguments, and any given regex for
-+ <start> or <end> (or <funcname>) must match in the starting revision.
++ give zero or one positive revision arguments, and
++ <start> and <end> (or <funcname>) must exist in the starting revision.
You can specify this option more than once. Implies `--patch`.
- If ``:<funcname>'' is given, implies `--function-context`.
- Patch output can be suppressed using `-s`, but other diff formats
+ Patch output can be suppressed using `--no-patch`, but other diff formats
+ (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
+
+ diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
+ --- a/Documentation/gitk.txt
+ +++ b/Documentation/gitk.txt
+@@
+ (or the function name regex <funcname>) within the <file>. You may
+ not give any pathspec limiters. This is currently limited to
+ a walk starting from a single revision, i.e., you may only
+- give zero or one positive revision arguments.
++ give zero or one positive revision arguments, and
++ <start> and <end> (or <funcname>) must exist in the starting revision.
+ You can specify this option more than once. Implies `--patch`.
+ Patch output can be suppressed using `--no-patch`, but other diff formats
+ (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
--
gitgitgadget
next prev parent reply other threads:[~2019-12-26 17:43 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-12-17 5:07 [PATCH 0/2] Improve line log documentation Philippe Blain via GitGitGadget
2019-12-17 5:07 ` [PATCH 1/2] Documentation/git-log: document accepted line-log diff formats Philippe Blain via GitGitGadget
2019-12-17 11:33 ` SZEDER Gábor
2019-12-18 2:44 ` Philippe Blain
2019-12-17 15:33 ` Derrick Stolee
2019-12-18 2:47 ` Philippe Blain
2019-12-17 5:07 ` [PATCH 2/2] Documentation/git-log: mention that line-log regex must match in starting revision Philippe Blain via GitGitGadget
2019-12-17 15:34 ` Derrick Stolee
2019-12-17 18:16 ` Junio C Hamano
2019-12-18 3:28 ` Philippe Blain
2019-12-18 10:55 ` Derrick Stolee
2019-12-18 11:49 ` SZEDER Gábor
2019-12-18 17:59 ` Junio C Hamano
2019-12-26 17:46 ` Philippe Blain
2019-12-18 11:09 ` SZEDER Gábor
2019-12-26 17:43 ` Philippe Blain via GitGitGadget [this message]
2019-12-26 17:43 ` [PATCH v2 1/2] doc: log, gitk: document accepted line-log diff formats Philippe Blain via GitGitGadget
2019-12-26 17:43 ` [PATCH v2 2/2] doc: log, gitk: line-log arguments must exist in starting revision Philippe Blain via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=pull.494.v2.git.1577382217.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=Matthieu.Moy@imag.fr \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=stolee@gmail.com \
--cc=szeder.dev@gmail.com \
--cc=tr@thomasrast.ch \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.