git/Documentation/git-diff.txt, branch gitk-resize-error

git-diff: fix missing --merge-base docs

2021-07-12T20:55:29Z

When `git diff --merge-base` was introduced at around Git 2.30, 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 ` 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 `` and `[...]`. Move the `[--merge-base]` so that it's beside `[]` which is a more logical grouping. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano

builtin/diff-tree: learn --merge-base

2020-09-21T20:37:03Z

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

builtin/diff-index: learn --merge-base

2020-09-21T04:30:26Z

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

git-diff.txt: backtick quote command text

2020-09-17T16:38:47Z

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

git-diff.txt: reorder possible usages

2020-07-13T19:47:38Z

The description of `git diff` goes through several different invocations (numbering added by me): 1. git diff [] [--] [...] 2. git diff [] --no-index [--] 3. git diff [] --cached [] [--] [...] 4. git diff [] [--] [...] 5. git diff [] [--] [...] 6. git diff [] .. [--] [...] 7. git diff [] ... [--] [...] 8. git diff [] ... [--] [...] It then goes on to say that "all of the in the above description, except in the last two forms that use '..' notations, can be any ". The "last two" actually refers to 6 and 8. This got out of sync in commit b7e10b2ca2 ("Documentation: usage for diff combined commits", 2020-06-12) which added item 7 to the mix. As a further complication, after b7e10b2ca2 we also have some potential confusion around "the '..' notation". The "..[.]" in items 6 and 8 are part of the rev notation, whereas the "..." in item 7 is manpage language for "one or more". Move item 6 down, i.e., to between 7 and 8, to restore the ordering. Because 6 refers to 5 ("synonymous to the previous form") we need to tweak the language a bit. An added bonus of this commit is that we're trying to steer users away from `git diff ..` and moving it further down probably doesn't hurt. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

git-diff.txt: don't mark required argument as optional

2020-07-13T19:47:36Z

Commit b7e10b2ca2 ("Documentation: usage for diff combined commits", 2020-06-12) modified the synopsis by adding an optional "[...]" to 'git diff' [] [--] [...] to effectively add 'git diff' [] ... [--] [...] as another valid invocation. Which makes sense. Further down, in the description, it left the existing entry for 'git diff' [] [--] [...] intact and added a new entry on 'git diff' [] [...] [--] [...] where it says that "[t]his form is to view the results of a merge commit" and details how "the first listed commit must be the merge itself". But one possible instantiation of this form is `git diff ` for which the added text doesn't really apply. Remove the brackets so that we lose this overlap between the two descriptions. We can still use the more compact representation in the synopsis. Signed-off-by: Martin Ågren Signed-off-by: Junio C Hamano

Documentation: usage for diff combined commits

2020-06-12T17:53:44Z

Document the usage for producing combined commits with "git diff". This includes updating the synopsis section. While here, add the three-dot notation to the synopsis. Make "git diff -h" print the same usage summary as the manual page synopsis, minus the "A..B" form, which is now discouraged. Signed-off-by: Chris Torek Signed-off-by: Junio C Hamano

git-diff.txt: document return code of `--no-index`

2019-11-02T04:16:41Z

Within diff_no_index(), we have the following: revs->diffopt.flags.exit_with_status = 1; ... /* * The return code for --no-index imitates diff(1): * 0 = no changes, 1 = changes, else error */ return diff_result_code(&revs->diffopt, 0); Which means when `git diff` is run in `--no-index` mode, `--exit-code` is implied. However, the documentation for this is missing in git-diff.txt. Add a note about how `--exit-code` is implied in the `--no-index` documentation to cover this documentation blindspot. Signed-off-by: Denton Liu Signed-off-by: Junio C Hamano

doc: tidy asciidoc style

2019-01-23T19:37:29Z

This mainly refers to enforcing indentation on additional lines of items of lists. Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano

doc: fix a typo and clarify a sentence

2018-10-11T00:39:15Z

I noticed that git-merge-base was unlikely to actually be a git command, and tried it in my shell. Seeing that it doesn't work, I cleaned up two places in the docs where it appears. Signed-off-by: Mihir Mehta Signed-off-by: Junio C Hamano