{"thread":{"id":"22000","subject":"[PATCH] Reword -M, when in `git log`s documention, to suggest --follow","startedAt":"2009-12-21T20:40:59Z","lastAt":"2010-01-02T18:43:51Z","messageCount":5,"participants":["Alex Vandiver","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"130223","messageId":"1261428059-31286-1-git-send-email-alex@chmrr.net","threadId":"22000","inReplyTo":null,"subject":"[PATCH] Reword -M, when in `git log`s documention, to suggest --follow","fromName":"Alex Vandiver","fromEmail":"alex@chmrr.net","sentAt":"2009-12-21T20:40:59Z","receivedAt":"2009-12-21T20:40:59Z","isPatch":true,"sender":{"key":"alex@chmrr.net","avatar":"https://avatars.githubusercontent.com/u/28347?v=4"},"body":"The documentation for `git log` is sadly misleading when it comes\nto tracking renames.  By far the most common option that users\nnew to git want is the ability to view the history of a file\nacross renames.  Unfortunately, `git log --help` shows:\n\n    NAME\n           git-log - Show commit logs\n    [...]\n    OPTIONS\n    [...]\n           -M\n               Detect renames.\n\n...and most users stop reading there.  Unfortunately, what\nthey're generally looking for comes significantly later:\n\n    [...]\n           --follow\n               Continue listing the history of a file beyond renames.\n\nSigned-off-by: Alex Vandiver <alex@chmrr.net>\n---\n Documentation/diff-options.txt |    6 ++++++\n 1 files changed, 6 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 8707d0e..bcbad88 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -175,7 +175,13 @@ endif::git-format-patch[]\n \tBreak complete rewrite changes into pairs of delete and create.\n \n -M::\n+ifdef::git-log[]\n+\tShow renames in diff output.  See `--follow` to track history\n+\tacross renames.\n+endif::git-log[]\n+ifndef::git-log[]\n \tDetect renames.\n+endif::git-log[]\n \n -C::\n \tDetect copies as well as renames.  See also `--find-copies-harder`.\n-- \n1.6.6.rc0.363.g69d13.dirty\n"},{"id":"130651","messageId":"1262306496-sup-9430@utwig","threadId":"22000","inReplyTo":"1261428059-31286-1-git-send-email-alex@chmrr.net","subject":"Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow","fromName":"Alex Vandiver","fromEmail":"alex@chmrr.net","sentAt":"2010-01-01T00:45:48Z","receivedAt":"2010-01-01T00:45:48Z","isPatch":true,"sender":{"key":"alex@chmrr.net","avatar":"https://avatars.githubusercontent.com/u/28347?v=4"},"body":"At Mon Dec 21 15:40:59 -0500 2009, Alex Vandiver wrote:\n> [snip]\n\nAny thoughts on this doc patch?  I saw someone get rather frustrated\nat this particular failure mode, so I'd like to be able to reassure\nthem that it'll get fixed.\n - Alex\n-- \nNetworking -- only one letter away from not working\n"},{"id":"130653","messageId":"7vhbr6phlx.fsf@alter.siamese.dyndns.org","threadId":"22000","inReplyTo":"1261428059-31286-1-git-send-email-alex@chmrr.net","subject":"Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-01T04:35:38Z","receivedAt":"2010-01-01T04:35:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Alex Vandiver <alex@chmrr.net> writes:\n\n> The documentation for `git log` is sadly misleading when it comes\n> to tracking renames.  By far the most common option that users\n> new to git want is the ability to view the history of a file\n> across renames.  Unfortunately, `git log --help` shows:\n>\n>     NAME\n>            git-log - Show commit logs\n>     [...]\n>     OPTIONS\n>     [...]\n>            -M\n>                Detect renames.\n>\n> ...and most users stop reading there.  Unfortunately, what\n> they're generally looking for comes significantly later:\n>\n>     [...]\n>            --follow\n>                Continue listing the history of a file beyond renames.\n>\n> Signed-off-by: Alex Vandiver <alex@chmrr.net>\n> ---\n>  Documentation/diff-options.txt |    6 ++++++\n>  1 files changed, 6 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 8707d0e..bcbad88 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -175,7 +175,13 @@ endif::git-format-patch[]\n>  \tBreak complete rewrite changes into pairs of delete and create.\n>  \n>  -M::\n> +ifdef::git-log[]\n> +\tShow renames in diff output.  See `--follow` to track history\n> +\tacross renames.\n\nWith \"s/history/history of a single file/\", I think the new wording makes\nmore sense.\n\n> +endif::git-log[]\n> +ifndef::git-log[]\n>  \tDetect renames.\n> +endif::git-log[]\n\nAlso we probably should do s/Detect renames/Show renames in diff output/\nto match the earlier change.\n\n>  \n>  -C::\n>  \tDetect copies as well as renames.  See also `--find-copies-harder`.\n> -- \n> 1.6.6.rc0.363.g69d13.dirty\n"},{"id":"130681","messageId":"1262412622-sup-7473@utwig","threadId":"22000","inReplyTo":"7vhbr6phlx.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow","fromName":"Alex Vandiver","fromEmail":"alex@chmrr.net","sentAt":"2010-01-02T06:38:21Z","receivedAt":"2010-01-02T06:38:21Z","isPatch":true,"sender":{"key":"alex@chmrr.net","avatar":"https://avatars.githubusercontent.com/u/28347?v=4"},"body":"At Thu Dec 31 23:35:38 -0500 2009, Junio C Hamano wrote:\n> [snip]\n\nThinking about this more, I'm more convinced that this is just a\nsymptom of a bigger problem -- why does the help for `git log` start\noff with the _diff_ options, which do nothing unless you also use the\n-p option?  It adds ~230 lines of options that are irrelevant to the\nmost common usage model.  It seems to me like the more correct fix\nwould be to move the diff options to later in the file (after the\noptions that are `git log`-specific), or to remove them entirely, and\nreplace them with a pointer to git diff's options.\n - Alex\n-- \nNetworking -- only one letter away from not working\n"},{"id":"130694","messageId":"7v1vi8e49k.fsf@alter.siamese.dyndns.org","threadId":"22000","inReplyTo":"1262412622-sup-7473@utwig","subject":"Re: [PATCH] Reword -M, when in `git log`s documention, to suggest --follow","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-01-02T18:43:51Z","receivedAt":"2010-01-02T18:43:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Alex Vandiver <alex@chmrr.net> writes:\n\n> most common usage model.  It seems to me like the more correct fix\n> would be to move the diff options to later in the file (after the\n> options that are `git log`-specific), or to remove them entirely, and\n> replace them with a pointer to git diff's options.\n\nIIRC, the apporach we took earlier that people hated and resulted in the\ncurrent \"include\" approach was to say \"It also takes many of options that\ndiff family of commands take\".  So reordering may work better but dropping\nand referring would not, I suspect.\n"}]}