From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 01 Jan 2010 04:35:38 GMT
Subject: Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow
Message-ID: <7vhbr6phlx.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1261428059-31286-1-git-send-email-alex@chmrr.net>

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