From b277b737d987b272487f95a6e2afb22edd203553 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 17 Sep 2020 00:44:06 -0700 Subject: git-diff-index.txt: make --cached description a proper sentence Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/git-diff-index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index f4bd8155c0..25fe165f00 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -27,7 +27,7 @@ include::diff-options.txt[] The id of a tree object to diff against. --cached:: - do not consider the on-disk file at all + Do not consider the on-disk file at all. -m:: By default, files recorded in the index but not checked -- cgit v1.2.3 From a8fa6a08f4ff3ab99f99dd7ae989bd825071def3 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Thu, 17 Sep 2020 00:44:07 -0700 Subject: git-diff.txt: backtick quote command text The modern way to quote commands in the documentation is to use backticks instead of double-quotes as this renders the text with the code style. Convert double-quoted command text to backtick-quoted commands. While we're at it, quote one instance of `^@`. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/git-diff.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 727f24d16e..8f7b4ed3ca 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -68,13 +68,13 @@ files on disk. This form is to view the results of a merge commit. The first listed must be the merge itself; the remaining two or more commits should be its parents. A convenient way to produce - the desired set of revisions is to use the {caret}@ suffix. + the desired set of revisions is to use the `^@` suffix. For instance, if `master` names a merge commit, `git diff master master^@` gives the same combined diff as `git show master`. 'git diff' [] .. [--] [...]:: - This is synonymous to the earlier form (without the "..") for + This is synonymous to the earlier form (without the `..`) for viewing the changes between two arbitrary . If on one side is omitted, it will have the same effect as using HEAD instead. @@ -83,20 +83,20 @@ files on disk. This form is to view the changes on the branch containing and up to the second , starting at a common ancestor - of both . "git diff A\...B" is equivalent to - "git diff $(git merge-base A B) B". You can omit any one + of both . `git diff A...B` is equivalent to + `git diff $(git merge-base A B) B`. You can omit any one of , which has the same effect as using HEAD instead. Just in case you are doing something exotic, it should be noted that all of the in the above description, except -in the last two forms that use ".." notations, can be any +in the last two forms that use `..` notations, can be any . For a more complete list of ways to spell , see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. However, "diff" is about comparing two _endpoints_, not ranges, -and the range notations (".." and -"\...") do not mean a range as defined in the +and the range notations (`..` and +`...`) do not mean a range as defined in the "SPECIFYING RANGES" section in linkgit:gitrevisions[7]. 'git diff' [] :: @@ -144,9 +144,9 @@ $ git diff HEAD <3> + <1> Changes in the working tree not yet staged for the next commit. <2> Changes between the index and your last commit; what you - would be committing if you run "git commit" without "-a" option. + would be committing if you run `git commit` without `-a` option. <3> Changes in the working tree since your last commit; what you - would be committing if you run "git commit -a" + would be committing if you run `git commit -a` Comparing with arbitrary commits:: + -- cgit v1.2.3 From 0f5a1d449b9538c2765de9d6683abbb83a7fb4e2 Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Sun, 20 Sep 2020 04:22:25 -0700 Subject: 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 --- Documentation/git-diff-index.txt | 7 ++++++- Documentation/git-diff.txt | 12 ++++++++---- 2 files changed, 14 insertions(+), 5 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 25fe165f00..27acb31cbf 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 SYNOPSIS -------- [verse] -'git diff-index' [-m] [--cached] [] [...] +'git diff-index' [-m] [--cached] [--merge-base] [] [...] DESCRIPTION ----------- @@ -29,6 +29,11 @@ include::diff-options.txt[] --cached:: Do not consider the on-disk file at all. +--merge-base:: + Instead of comparing directly, use the merge base + between and HEAD instead. must be a + commit. + -m:: 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 8f7b4ed3ca..762ee6d074 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git diff' [] [] [--] [...] -'git diff' [] --cached [] [--] [...] +'git diff' [] --cached [--merge-base] [] [--] [...] 'git diff' [] [...] [--] [...] 'git diff' [] ... [--] [...] 'git diff' [] @@ -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' [] --cached [] [--] [...]:: +'git diff' [] --cached [--merge-base] [] [--] [...]:: This form is to view the changes you staged for the next commit relative to the named . Typically you @@ -49,6 +49,10 @@ files on disk. If HEAD does not exist (e.g. unborn branches) and is not given, it shows all staged changes. --staged is a synonym of --cached. ++ +If --merge-base is given, instead of using , use the merge base +of and HEAD. `git diff --merge-base A` is equivalent to +`git diff $(git merge-base A HEAD)`. 'git diff' [] [--] [...]:: @@ -89,8 +93,8 @@ files on disk. Just in case you are doing something exotic, it should be noted that all of the 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 . For a more complete list of ways to spell , see "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7]. -- cgit v1.2.3 From 3d09c22869a7bd47f1683031937af0ed93b2fa3b Mon Sep 17 00:00:00 2001 From: Denton Liu Date: Mon, 14 Sep 2020 11:36:52 -0700 Subject: builtin/diff-tree: learn --merge-base The previous commit introduced ---merge-base a way to take the diff between the working tree or index and the merge base between an arbitrary commit and HEAD. It makes sense to extend this option to support the case where two commits are given too and behave in a manner identical to `git diff A...B`. Introduce the --merge-base flag as an alternative to triple-dot notation. Thus, we would be able to write the above as `git diff --merge-base A B`. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano --- Documentation/git-diff-tree.txt | 7 ++++++- Documentation/git-diff.txt | 8 ++++++-- 2 files changed, 12 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 5c8a2a5e97..2fc24c542f 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] - [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] + [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base] [] [] [...] DESCRIPTION @@ -43,6 +43,11 @@ include::diff-options.txt[] When `--root` is specified the initial commit will be shown as a big creation event. This is equivalent to a diff against the NULL tree. +--merge-base:: + Instead of comparing the s directly, use the merge + base between the two s as the "before" side. There + must be two s given and they must both be commits. + --stdin:: When `--stdin` is specified, the command does not take arguments from the command line. Instead, it diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 762ee6d074..7f4c8a8ce7 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -11,7 +11,7 @@ SYNOPSIS [verse] 'git diff' [] [] [--] [...] 'git diff' [] --cached [--merge-base] [] [--] [...] -'git diff' [] [...] [--] [...] +'git diff' [] [--merge-base] [...] [--] [...] 'git diff' [] ... [--] [...] 'git diff' [] 'git diff' [] --no-index [--] @@ -62,10 +62,14 @@ of and HEAD. `git diff --merge-base A` is equivalent to branch name to compare with the tip of a different branch. -'git diff' [] [--] [...]:: +'git diff' [] [--merge-base] [--] [...]:: This is to view the changes between two arbitrary . ++ +If --merge-base is given, use the merge base of the two commits for the +"before" side. `git diff --merge-base A B` is equivalent to +`git diff $(git merge-base A B) B`. 'git diff' [] ... [--] [...]:: -- cgit v1.2.3