path: root/Documentation
diff options
authorDenton Liu <>2020-09-20 11:22:25 (GMT)
committerJunio C Hamano <>2020-09-21 04:30:26 (GMT)
commit0f5a1d449b9538c2765de9d6683abbb83a7fb4e2 (patch)
tree29cbd67c4138aed23542fb1030c3c718bba6ae9e /Documentation
parentdf7dbab881c1aa697f0826d8d00f73d43815acf5 (diff)
builtin/diff-index: learn --merge-base
There is currently no easy way to take the diff between the working tree or index and the merge base between an arbitrary commit and HEAD. Even diff's `...` notation doesn't allow this because it only works between commits. However, the ability to do this would be desirable to a user who would like to see all the changes they've made on a branch plus uncommitted changes without taking into account changes made in the upstream branch. Teach diff-index and diff (with one commit) the --merge-base option which allows a user to use the merge base of a commit and HEAD as the "before" side. Signed-off-by: Denton Liu <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation')
2 files changed, 14 insertions, 5 deletions
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 25fe165..27acb31 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index
-'git diff-index' [-m] [--cached] [<common diff options>] <tree-ish> [<path>...]
+'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...]
@@ -29,6 +29,11 @@ include::diff-options.txt[]
Do not consider the on-disk file at all.
+ Instead of comparing <tree-ish> directly, use the merge base
+ between <tree-ish> and HEAD instead. <tree-ish> must be a
+ commit.
By default, files recorded in the index but not checked
out are reported as deleted. This flag makes
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 8f7b4ed..762ee6d 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -10,7 +10,7 @@ SYNOPSIS
'git diff' [<options>] [<commit>] [--] [<path>...]
-'git diff' [<options>] --cached [<commit>] [--] [<path>...]
+'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
'git diff' [<options>] <commit>...<commit> [--] [<path>...]
'git diff' [<options>] <blob> <blob>
@@ -40,7 +40,7 @@ files on disk.
or when running the command outside a working tree
controlled by Git. This form implies `--exit-code`.
-'git diff' [<options>] --cached [<commit>] [--] [<path>...]::
+'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]::
This form is to view the changes you staged for the next
commit relative to the named <commit>. Typically you
@@ -49,6 +49,10 @@ files on disk.
If HEAD does not exist (e.g. unborn branches) and
<commit> is not given, it shows all staged changes.
--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)`.
'git diff' [<options>] <commit> [--] [<path>...]::
@@ -89,8 +93,8 @@ files on disk.
Just in case you are doing something exotic, it should be
noted that all of the <commit> in the above description, except
-in the last two forms that use `..` notations, can be any
+in the `--merge-base` case and in the last two forms that use `..`
+notations, can be any <tree>.
For a more complete list of ways to spell <commit>, see
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].