threads / patch / 22000

patchReword -M, when in `git log`s documention, to suggest --follow

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

## tl;dr

5 messages between Dec 21, 2009 and Jan 2, 2010. Diffs are folded; open one to read it.

replies: 4people: 2as markdown or json

Alex Vandiver· Dec 21, 2009, 20:40 UTC · lore

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(-)

Show changes to Documentation/diff-options.txt +6 −0

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

Alex Vandiver· Jan 1, 2010, 00:45 UTC · re: Alex Vandiver · lore

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

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

Junio C Hamano· Jan 1, 2010, 04:35 UTC · re: Alex Vandiver · lore

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

Alex Vandiver <alex@chmrr.net> writes:

Show 36 quoted lines

> 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.

Show 5 quoted lines

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

Alex Vandiver· Jan 2, 2010, 06:38 UTC · re: Junio C Hamano · lore

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

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

Junio C Hamano· Jan 2, 2010, 18:43 UTC · re: Alex Vandiver · lore

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

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.