Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow

3 messages, 2 authors, 2016-06-15 · open the first message on its own page

Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow

From: Junio C Hamano <hidden>
Date: 2016-06-15 22:47:57

Alex Vandiver [off-list ref] writes:

quoted hunk

The documentation for `git log` is sadly misleading when it comes
to tracking renames.  By far the most common option that users
new to git want is the ability to view the history of a file
across renames.  Unfortunately, `git log --help` shows:

    NAME
           git-log - Show commit logs
    [...]
    OPTIONS
    [...]
           -M
               Detect renames.

...and most users stop reading there.  Unfortunately, what
they're generally looking for comes significantly later:

    [...]
           --follow
               Continue listing the history of a file beyond renames.

Signed-off-by: Alex Vandiver <redacted>
---
 Documentation/diff-options.txt |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 8707d0e..bcbad88 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt

@@ -175,7 +175,13 @@ endif::git-format-patch[]
 	Break complete rewrite changes into pairs of delete and create.
 
 -M::
+ifdef::git-log[]
+	Show renames in diff output.  See `--follow` to track history
+	across renames.

With "s/history/history of a single file/", I think the new wording makes
more sense.

+endif::git-log[]
+ifndef::git-log[]
 	Detect renames.
+endif::git-log[]

Also we probably should do s/Detect renames/Show renames in diff output/
to match the earlier change.

 
 -C::
 	Detect copies as well as renames.  See also `--find-copies-harder`.
-- 
1.6.6.rc0.363.g69d13.dirty

Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow

From: Alex Vandiver <hidden>
Date: 2016-06-15 22:47:57

At Thu Dec 31 23:35:38 -0500 2009, Junio C Hamano wrote:

[snip]

Thinking about this more, I'm more convinced that this is just a
symptom of a bigger problem -- why does the help for `git log` start
off with the _diff_ options, which do nothing unless you also use the
-p option?  It adds ~230 lines of options that are irrelevant to the
most common usage model.  It seems to me like the more correct fix
would be to move the diff options to later in the file (after the
options that are `git log`-specific), or to remove them entirely, and
replace them with a pointer to git diff's options.
 - Alex
-- 
Networking -- only one letter away from not working

Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow

From: Junio C Hamano <hidden>
Date: 2016-06-15 22:47:57

Alex Vandiver [off-list ref] writes:

most common usage model.  It seems to me like the more correct fix
would be to move the diff options to later in the file (after the
options that are `git log`-specific), or to remove them entirely, and
replace them with a pointer to git diff's options.

IIRC, the apporach we took earlier that people hated and resulted in the
current "include" approach was to say "It also takes many of options that
diff family of commands take".  So reordering may work better but dropping
and referring would not, I suspect.

`h`	back out one level
`j`	next message in thread
`k`	previous message in thread
`l`	drill in
`Esc`	close help / fold thread tree
`?`	toggle this help