{"thread":{"id":"24330","subject":"[PATCH] Reorganize `git-log' man page to clarify common diff options.","startedAt":"2010-07-08T02:14:31Z","lastAt":"2010-07-08T02:14:31Z","messageCount":1,"participants":["Eli Barzilay"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"145077","messageId":"19509.13447.589906.225601@winooski.ccs.neu.edu","threadId":"24330","inReplyTo":null,"subject":"[PATCH] Reorganize `git-log' man page to clarify common diff options.","fromName":"Eli Barzilay","fromEmail":"eli@barzilay.org","sentAt":"2010-07-08T02:14:31Z","receivedAt":"2010-07-08T02:14:31Z","isPatch":true,"sender":{"key":"eli@barzilay.org","avatar":"https://avatars.githubusercontent.com/u/185905?v=4"},"body":"This will reduce considerably the common confusion where people miss the\n`--follow' option, and wonder why `-M'/`-C' is not working.\n\n* Move the diff options include to after the log-specific flags, and add\n  a \"Common diff options\" subtitle before them.  (These options apply\n  only when patches are shown, which is not a common use case among\n  newbies, so having them first is confusing.)\n\n* Move the `--follow' description to the top of the listed options.  The\n  options before that seem less important: `--full-diff' applies only\n  when patches are shown, `--source' and `--decorate' are less useful\n  with many common commit specifications.\n\n* Clarify that `--follow' works only for a single path argument.\n\nSigned-off-by: Eli Barzilay <eli@barzilay.org>\n---\n\nThis is a resend of a patch I sent about two months ago.  It seems\nthat there was agreement that it is useful -- but it seems that it got\nlost in the noise.\n\n Documentation/git-log.txt |   15 +++++++++------\n 1 files changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 0e6ff31..c925d36 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -23,9 +23,6 @@ each commit introduces are shown.\n OPTIONS\n -------\n \n-:git-log: 1\n-include::diff-options.txt[]\n-\n -<n>::\n \tLimits the number of commits to show.\n \n@@ -37,6 +34,10 @@ include::diff-options.txt[]\n \tand <until>, see \"SPECIFYING REVISIONS\" section in\n \tlinkgit:git-rev-parse[1].\n \n+--follow::\n+\tContinue listing the history of a file beyond renames\n+\t(works only for a single file).\n+\n --no-decorate::\n --decorate[=short|full|no]::\n \tPrint out the ref names of any commits that are shown. If 'short' is\n@@ -56,9 +57,6 @@ include::diff-options.txt[]\n \tthe specified paths; this means that \"<path>...\" limits only\n \tcommits, and doesn't limit diff for those commits.\n \n---follow::\n-\tContinue listing the history of a file beyond renames/copies.\n-\n --log-size::\n \tBefore the log message print out its size in bytes. Intended\n \tmainly for porcelain tools consumption. If git is unable to\n@@ -72,6 +70,11 @@ include::diff-options.txt[]\n \tto be prefixed with \"\\-- \" to separate them from options or\n \trefnames.\n \n+Common diff options\n+~~~~~~~~~~~~~~~~~~~\n+\n+:git-log: 1\n+include::diff-options.txt[]\n \n include::rev-list-options.txt[]\n \n-- \n1.7.1\n"}]}