git diff -h help is succinct, but perhaps too much so.

The symmetric-diff syntax, git diff A...B, is defined by the documentation
to compare the merge base of A and B to commit B. It does so just fine when
there is a merge base. It compares A and B directly if there is no merge
base, and it is overly forgiving of bad arguments after which it can produce
nonsensical diffs. It also behaves badly with other odd/incorrect usages,
such as git diff A...B C..D.

The first patch simply adjusts a test that will fail if the second patch is
accepted. The second patch adds special handling for the symmetric and range
diff syntax so that the option parsing works, plus a small test suite. The
third patch updates the documentation, including adding a section for
combined commits, and makes the help output more verbose (to match the
SYNOPSIS and provide common diff options like git-diff-files, for instance).

Changes since v3:

 * correct > / >= goof
 * fix test nit per Philip Oakley

Chris Torek (3):
  t/t3430: avoid undefined git diff behavior
  git diff: improve range handling
  Documentation: usage for diff combined commits

 Documentation/git-diff.txt |  20 ++++--
 builtin/diff.c             | 132 +++++++++++++++++++++++++++++++++----
 t/t3430-rebase-merges.sh   |   2 +-
 t/t4068-diff-symmetric.sh  |  91 +++++++++++++++++++++++++
 4 files changed, 226 insertions(+), 19 deletions(-)
 create mode 100755 t/t4068-diff-symmetric.sh

base-commit: 20514004ddf1a3528de8933bc32f284e175e1012

Submitted-As: https://lore.kernel.org/git/pull.804.v4.git.git.1591978801.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.804.git.git.1591661021.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.804.v2.git.git.1591729224.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.804.v3.git.git.1591888511.gitgitgadget@gmail.com