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

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

[Alex Vandiver]

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 <alex@chmrr.net>
---
 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.
+endif::git-log[]
+ifndef::git-log[]
 	Detect renames.
+endif::git-log[]
 
 -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

[Alex Vandiver]

At Mon Dec 21 15:40:59 -0500 2009, Alex Vandiver wrote:
> [snip]

Any thoughts on this doc patch?  I saw someone get rather frustrated
at this particular failure mode, so I'd like to be able to reassure
them that it'll get fixed.
 - Alex
-- 
Networking -- only one letter away from not working

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

[Junio C Hamano]

Alex Vandiver <alex@chmrr.net> writes:

> 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 <alex@chmrr.net>
> ---
>  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

[Alex Vandiver]

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

[Junio C Hamano]

Alex Vandiver <alex@chmrr.net> 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.