* [PATCH] git-diff: fix missing --merge-base docs
@ 2021-07-10 9:28 Denton Liu
2021-07-12 20:52 ` Junio C Hamano
0 siblings, 1 reply; 2+ messages in thread
From: Denton Liu @ 2021-07-10 9:28 UTC (permalink / raw)
To: Git Mailing List
When `git diff --merge-base` was introduced, the documentation included
a few errors.
In the example given for `git diff --cached --merge-base`, the
`--cached` flag was omitted for the `--merge-base` example. Add the
missing flag.
In the `git diff <commit>` case, we failed to mention that
`--merge-base` is an available option. Give the usage of `--merge-base`
as an option there.
Finally, there are two errors in the usage of `git diff`. Firstly, we do
not mention `--merge-base` in the `git diff --cached` case. Mention it
so that it's consistent with the documentation. Secondly, we put the
`[--merge-base]` in between `<commit>` and `[<commit>...]`. Move the
`[--merge-base]` so that it's beside `[<options>]` which is a more
logical grouping.
Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
Documentation/git-diff.txt | 10 +++++++---
builtin/diff.c | 4 ++--
2 files changed, 9 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 7f4c8a8ce7..6236c75c9b 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -51,16 +51,20 @@ files on disk.
--staged is a synonym of --cached.
+
If --merge-base is given, instead of using <commit>, use the merge base
-of <commit> and HEAD. `git diff --merge-base A` is equivalent to
-`git diff $(git merge-base A HEAD)`.
+of <commit> and HEAD. `git diff --cached --merge-base A` is equivalent to
+`git diff --cached $(git merge-base A HEAD)`.
-'git diff' [<options>] <commit> [--] [<path>...]::
+'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::
This form is to view the changes you have in your
working tree relative to the named <commit>. You can
use HEAD to compare it with the latest commit, or a
branch name to compare with the tip of a different
branch.
++
+If --merge-base is given, instead of using <commit>, use the merge base
+of <commit> and HEAD. `git diff --merge-base A` is equivalent to
+`git diff $(git merge-base A HEAD)`.
'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::
diff --git a/builtin/diff.c b/builtin/diff.c
index 2d87c37a17..dd8ce688ba 100644
--- a/builtin/diff.c
+++ b/builtin/diff.c
@@ -26,8 +26,8 @@
static const char builtin_diff_usage[] =
"git diff [<options>] [<commit>] [--] [<path>...]\n"
-" or: git diff [<options>] --cached [<commit>] [--] [<path>...]\n"
-" or: git diff [<options>] <commit> [--merge-base] [<commit>...] <commit> [--] [<path>...]\n"
+" or: git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n"
+" or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
" or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\n"
" or: git diff [<options>] <blob> <blob>]\n"
" or: git diff [<options>] --no-index [--] <path> <path>]\n"
--
2.32.0.rc1.186.g3cb6fa43cd
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] git-diff: fix missing --merge-base docs
2021-07-10 9:28 [PATCH] git-diff: fix missing --merge-base docs Denton Liu
@ 2021-07-12 20:52 ` Junio C Hamano
0 siblings, 0 replies; 2+ messages in thread
From: Junio C Hamano @ 2021-07-12 20:52 UTC (permalink / raw)
To: Denton Liu; +Cc: Git Mailing List
Denton Liu <liu.denton@gmail.com> writes:
> When `git diff --merge-base` was introduced, the documentation included
> a few errors.
>
> In the example given for `git diff --cached --merge-base`, the
> `--cached` flag was omitted for the `--merge-base` example. Add the
> missing flag.
>
> In the `git diff <commit>` case, we failed to mention that
> `--merge-base` is an available option. Give the usage of `--merge-base`
> as an option there.
>
> Finally, there are two errors in the usage of `git diff`. Firstly, we do
> not mention `--merge-base` in the `git diff --cached` case. Mention it
> so that it's consistent with the documentation. Secondly, we put the
> `[--merge-base]` in between `<commit>` and `[<commit>...]`. Move the
> `[--merge-base]` so that it's beside `[<options>]` which is a more
> logical grouping.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
> Documentation/git-diff.txt | 10 +++++++---
> builtin/diff.c | 4 ++--
> 2 files changed, 9 insertions(+), 5 deletions(-)
Thanks. Both hunks look sensible.
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 7f4c8a8ce7..6236c75c9b 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -51,16 +51,20 @@ files on disk.
> --staged is a synonym of --cached.
> +
> If --merge-base is given, instead of using <commit>, use the merge base
> -of <commit> and HEAD. `git diff --merge-base A` is equivalent to
> -`git diff $(git merge-base A HEAD)`.
> +of <commit> and HEAD. `git diff --cached --merge-base A` is equivalent to
> +`git diff --cached $(git merge-base A HEAD)`.
>
> -'git diff' [<options>] <commit> [--] [<path>...]::
> +'git diff' [<options>] [--merge-base] <commit> [--] [<path>...]::
>
> This form is to view the changes you have in your
> working tree relative to the named <commit>. You can
> use HEAD to compare it with the latest commit, or a
> branch name to compare with the tip of a different
> branch.
> ++
> +If --merge-base is given, instead of using <commit>, use the merge base
> +of <commit> and HEAD. `git diff --merge-base A` is equivalent to
> +`git diff $(git merge-base A HEAD)`.
>
> 'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]::
>
> diff --git a/builtin/diff.c b/builtin/diff.c
> index 2d87c37a17..dd8ce688ba 100644
> --- a/builtin/diff.c
> +++ b/builtin/diff.c
> @@ -26,8 +26,8 @@
>
> static const char builtin_diff_usage[] =
> "git diff [<options>] [<commit>] [--] [<path>...]\n"
> -" or: git diff [<options>] --cached [<commit>] [--] [<path>...]\n"
> -" or: git diff [<options>] <commit> [--merge-base] [<commit>...] <commit> [--] [<path>...]\n"
> +" or: git diff [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]\n"
> +" or: git diff [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]\n"
> " or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\n"
> " or: git diff [<options>] <blob> <blob>]\n"
> " or: git diff [<options>] --no-index [--] <path> <path>]\n"
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2021-07-12 20:52 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-07-10 9:28 [PATCH] git-diff: fix missing --merge-base docs Denton Liu
2021-07-12 20:52 ` Junio C Hamano
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).