{"thread":{"id":"56087","subject":"[PATCH] git-diff: fix missing --merge-base docs","startedAt":"2021-07-10T09:28:40Z","lastAt":"2021-07-12T20:52:21Z","messageCount":2,"participants":["Denton Liu","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"429605","messageId":"f0e7ef2433e2836fed579f2765654c5f97d5d778.1625909286.git.liu.denton@gmail.com","threadId":"56087","inReplyTo":null,"subject":"[PATCH] git-diff: fix missing --merge-base docs","fromName":"Denton Liu","fromEmail":"liu.denton@gmail.com","sentAt":"2021-07-10T09:28:31Z","receivedAt":"2021-07-10T09:28:40Z","isPatch":true,"sender":{"key":"liu.denton@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9620836?v=4"},"body":"When `git diff --merge-base` was introduced, the documentation included\na few errors.\n\nIn the example given for `git diff --cached --merge-base`, the\n`--cached` flag was omitted for the `--merge-base` example. Add the\nmissing flag.\n\nIn the `git diff <commit>` case, we failed to mention that\n`--merge-base` is an available option. Give the usage of `--merge-base`\nas an option there.\n\nFinally, there are two errors in the usage of `git diff`. Firstly, we do\nnot mention `--merge-base` in the `git diff --cached` case. Mention it\nso that it's consistent with the documentation. Secondly, we put the\n`[--merge-base]` in between `<commit>` and `[<commit>...]`. Move the\n`[--merge-base]` so that it's beside `[<options>]` which is a more\nlogical grouping.\n\nSigned-off-by: Denton Liu <liu.denton@gmail.com>\n---\n Documentation/git-diff.txt | 10 +++++++---\n builtin/diff.c             |  4 ++--\n 2 files changed, 9 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 7f4c8a8ce7..6236c75c9b 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -51,16 +51,20 @@ files on disk.\n \t--staged is a synonym of --cached.\n +\n If --merge-base is given, instead of using <commit>, use the merge base\n-of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n-`git diff $(git merge-base A HEAD)`.\n+of <commit> and HEAD.  `git diff --cached --merge-base A` is equivalent to\n+`git diff --cached $(git merge-base A HEAD)`.\n \n-'git diff' [<options>] <commit> [--] [<path>...]::\n+'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n \n \tThis form is to view the changes you have in your\n \tworking tree relative to the named <commit>.  You can\n \tuse HEAD to compare it with the latest commit, or a\n \tbranch name to compare with the tip of a different\n \tbranch.\n++\n+If --merge-base is given, instead of using <commit>, use the merge base\n+of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n+`git diff $(git merge-base A HEAD)`.\n \n 'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n \ndiff --git a/builtin/diff.c b/builtin/diff.c\nindex 2d87c37a17..dd8ce688ba 100644\n--- a/builtin/diff.c\n+++ b/builtin/diff.c\n@@ -26,8 +26,8 @@\n \n static const char builtin_diff_usage[] =\n \"git diff [<options>] [<commit>] [--] [<path>...]\\n\"\n-\"   or: git diff [<options>] --cached [<commit>] [--] [<path>...]\\n\"\n-\"   or: git diff [<options>] <commit> [--merge-base] [<commit>...] <commit> [--] [<path>...]\\n\"\n+\"   or: git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\\n\"\n+\"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\\n\"\n \"   or: git diff [<options>] <blob> <blob>]\\n\"\n \"   or: git diff [<options>] --no-index [--] <path> <path>]\\n\"\n-- \n2.32.0.rc1.186.g3cb6fa43cd\n\n"},{"id":"429834","messageId":"xmqqlf6b2r24.fsf@gitster.g","threadId":"56087","inReplyTo":"f0e7ef2433e2836fed579f2765654c5f97d5d778.1625909286.git.liu.denton@gmail.com","subject":"Re: [PATCH] git-diff: fix missing --merge-base docs","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-07-12T20:52:19Z","receivedAt":"2021-07-12T20:52:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Denton Liu <liu.denton@gmail.com> writes:\n\n> When `git diff --merge-base` was introduced, the documentation included\n> a few errors.\n>\n> In the example given for `git diff --cached --merge-base`, the\n> `--cached` flag was omitted for the `--merge-base` example. Add the\n> missing flag.\n>\n> In the `git diff <commit>` case, we failed to mention that\n> `--merge-base` is an available option. Give the usage of `--merge-base`\n> as an option there.\n>\n> Finally, there are two errors in the usage of `git diff`. Firstly, we do\n> not mention `--merge-base` in the `git diff --cached` case. Mention it\n> so that it's consistent with the documentation. Secondly, we put the\n> `[--merge-base]` in between `<commit>` and `[<commit>...]`. Move the\n> `[--merge-base]` so that it's beside `[<options>]` which is a more\n> logical grouping.\n>\n> Signed-off-by: Denton Liu <liu.denton@gmail.com>\n> ---\n>  Documentation/git-diff.txt | 10 +++++++---\n>  builtin/diff.c             |  4 ++--\n>  2 files changed, 9 insertions(+), 5 deletions(-)\n\nThanks.  Both hunks look sensible.\n\n>\n> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\n> index 7f4c8a8ce7..6236c75c9b 100644\n> --- a/Documentation/git-diff.txt\n> +++ b/Documentation/git-diff.txt\n> @@ -51,16 +51,20 @@ files on disk.\n>  \t--staged is a synonym of --cached.\n>  +\n>  If --merge-base is given, instead of using <commit>, use the merge base\n> -of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n> -`git diff $(git merge-base A HEAD)`.\n> +of <commit> and HEAD.  `git diff --cached --merge-base A` is equivalent to\n> +`git diff --cached $(git merge-base A HEAD)`.\n>  \n> -'git diff' [<options>] <commit> [--] [<path>...]::\n> +'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::\n>  \n>  \tThis form is to view the changes you have in your\n>  \tworking tree relative to the named <commit>.  You can\n>  \tuse HEAD to compare it with the latest commit, or a\n>  \tbranch name to compare with the tip of a different\n>  \tbranch.\n> ++\n> +If --merge-base is given, instead of using <commit>, use the merge base\n> +of <commit> and HEAD.  `git diff --merge-base A` is equivalent to\n> +`git diff $(git merge-base A HEAD)`.\n>  \n>  'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::\n>  \n> diff --git a/builtin/diff.c b/builtin/diff.c\n> index 2d87c37a17..dd8ce688ba 100644\n> --- a/builtin/diff.c\n> +++ b/builtin/diff.c\n> @@ -26,8 +26,8 @@\n>  \n>  static const char builtin_diff_usage[] =\n>  \"git diff [<options>] [<commit>] [--] [<path>...]\\n\"\n> -\"   or: git diff [<options>] --cached [<commit>] [--] [<path>...]\\n\"\n> -\"   or: git diff [<options>] <commit> [--merge-base] [<commit>...] <commit> [--] [<path>...]\\n\"\n> +\"   or: git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\\n\"\n> +\"   or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\\n\"\n>  \"   or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\\n\"\n>  \"   or: git diff [<options>] <blob> <blob>]\\n\"\n>  \"   or: git diff [<options>] --no-index [--] <path> <path>]\\n\"\n"}]}