| Message ID | f0e7ef2433e2836fed579f2765654c5f97d5d778.1625909286.git.liu.denton@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 013d013bcf00511a1fb4eaf128833765a6037750 |
| Headers | show |
| Series | git-diff: fix missing --merge-base docs | expand |
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"
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"
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(-)