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

docs: AUTO_MERGE is not that special

2023-12-15T22:08:28Z

A handful of manual pages called AUTO_MERGE a "special ref", but there is nothing special about it. It merely is yet another pseudoref. Signed-off-by: Junio C Hamano

Documentation: document AUTO_MERGE

2023-05-23T08:21:47Z

Since 5291828df8 (merge-ort: write $GIT_DIR/AUTO_MERGE whenever we hit a conflict, 2021-03-20), when using the 'ort' merge strategy, the special ref AUTO_MERGE is written when a merge operation results in conflicts. This ref points to a tree recording the conflicted state of the working tree and is very useful during conflict resolution. However, this ref is not documented. Add some documentation for AUTO_MERGE in git-diff(1), git-merge(1), gitrevisions(7) and in the user manual. In git-diff(1), mention it at the end of the description section, when we mention that the command also accepts trees instead of commits, and also add an invocation to the "Various ways to check your working tree" example. In git-merge(1), add a step to the list of things that happen "when it is not obvious how to reconcile the changes", under the "True merge" section. Also mention AUTO_MERGE in the "How to resolve conflicts" section, when mentioning 'git diff'. In gitrevisions(7), add a mention of AUTO_MERGE along with the other special refs. In the user manual, add a paragraph describing AUTO_MERGE to the "Getting conflict-resolution help during a merge" section, and include an example of a 'git diff AUTO_MERGE' invocation for the example conflict used in that section. Note that for uniformity we do not use backticks around AUTO_MERGE here since the rest of the document does not typeset special refs differently. Closes: https://github.com/gitgitgadget/git/issues/1471 Signed-off-by: Philippe Blain Signed-off-by: Junio C Hamano

Merge branch 'rs/diff-caret-bang-with-parents'

2022-10-26T00:11:43Z

"git diff rev^!" did not show combined diff to go to the rev from its parents. * rs/diff-caret-bang-with-parents: diff: support ^! for merges revisions.txt: unspecify order of resolved parts of ^! revision: use strtol_i() for exclude_parent

diff: support ^! for merges

2022-10-01T22:58:38Z

revision.c::handle_revision_arg_1() resolves ^! by first adding the negated parents and then itself. builtin_diff_combined() expects the first tree to be the merge and the remaining ones to be the parents, though. This mismatch results in bogus diff output. Remember the first tree that doesn't belong to a parent and use it instead of blindly picking the first one. This makes "git diff ^!" consistent with "git show ^!". Reported-by: Tim Jaacks Suggested-by: Junio C Hamano Signed-off-by: René Scharfe Signed-off-by: Junio C Hamano

docs: add CONFIGURATION sections that fuzzy map to built-ins

2022-09-07T16:46:07Z

Add a CONFIGURATION section to the documentation of various built-ins, for those cases where the relevant config/NAME.txt doesn't map only to one git-NAME.txt. In particular: * config/blame.txt: used by git-{blame,annotate}.txt. Since the git-annotate(1) documentation refers to git-blame(1) don't add a "CONFIGURATION" section to git-annotate(1), only to git-blame(1). * config/checkout.txt: maps to both git-checkout.txt and git-switch.txt (but nothing else). * config/init.txt: should be included in git-init(1) and git-clone(1). * config/column.txt: We should ideally mention the relevant subset of this in git-{branch,clean,status,tag}.txt, but let's punt on it for now. We will when we eventually split these sort of files into e.g. config/column.txt and config/column/{branch,clean,status,tag}.txt, with the former including the latter set. Things that are being left out, and why: * config/{remote,remotes,credential}.txt: Configuration that affects how we talk to remote repositories is harder to untangle. We'll need to include some of this in git-{fetch,remote,push,ls-remote}.txt etc., but some of those only use a small subset of these options. Let's leave this for now. Signed-off-by: Ævar Arnfjörð Bjarmason Reviewed-by: Matheus Tavares Signed-off-by: Junio C Hamano

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