git/Documentation/git-diff.txt, branch v2.29.2

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

Use proper syntax for replaceables in command docs

2018-05-25T08:16:47Z

The standard for command documentation synopses appears to be: [...] means optional <...> means replaceable [<...>] means both optional and replaceable So fix a number of doc pages that use incorrect variations of the above. Signed-off-by: Robert P. J. Day Signed-off-by: Junio C Hamano

doc: normalize [--options] to [options] in git-diff

2018-05-06T09:38:43Z

SYNOPSIS and other manuals use [options] but DESCRIPTION used [--options]. Signed-off-by: Andreas Heiduk Signed-off-by: Junio C Hamano

doc: align 'diff --no-index' in text and synopsis

2018-05-06T09:38:43Z

Make the two '' parameters in DESCRIPTION mandatory and move the `--options` part to the same place where the other variants show them. And finally make `--no-index` in SYNOPSIS as mandatory as in DESCRIPTION. Signed-off-by: Andreas Heiduk Reviewed-by: Martin Ågren Signed-off-by: Junio C Hamano

diff-files: document --ours etc.

2017-04-13T23:15:25Z

git-diff understands "--ours", "--theirs" and "--base" for files with conflicts. But so far they were not documented for the central diff command but only for diff-files. Signed-off-by: Andreas Heiduk Signed-off-by: Junio C Hamano