git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v4 00/10] builtin/diff: learn --merge-base

From
Denton Liu <liu.denton@gmail.com>
Date
Sep 20, 2020, 11:22 UTC
Message-ID
<cover.1600600823.git.liu.denton@gmail.com>
In-Reply-To
<cover.1600328335.git.liu.denton@gmail.com>

The range-notation in `git diff` has been cited as a mistake since diff compares two endpoints, not whole ranges.[0] In fact, the ranges seem to take on the opposite meanings when compared to range notation in `git log`.

In an effort to reduce the use of range notation as much as possible, introduce the `--merge-base` flag, slightly modified from a suggestion by Jonathan Nieder.[1] This flag allows us to replace the first commit given on the command-line with its merge base between the first and second commits.

One additional bonus is that this flag allows the "after" side to be not just constrained to a commit (like with `...` notation). It can now be the working tree or the index as well.

The `--merge-base` name isn't very satisfying. If anyone has any better suggestions, please let me know.

Changes since v1:
* Implement Junio's documentation suggestions
* Update git diff's usage to include this option
Changes since v2:
* Teach diff-index and diff-tree the --merge-base option as well
Changes since v3:
* Don't use bitfields directly; extract them to an intermediate variable
* Use explicit literals in diff_get_merge_base() for clarity
* Fix xstrdup() leak
* I misunderstood and thought we wanted to deprecate `...` notation;
  this is not the case so remove all references to "gentle deprecation"
  and don't remove usage text that references it

[0]: https://lore.kernel.org/git/xmqqy2v26hu0.fsf@gitster-ct.c.googlers.com/ [1]: https://lore.kernel.org/git/20191223215928.GB38316@google.com/

Denton Liu (10):
  t4068: remove unnecessary >tmp
  git-diff-index.txt: make --cached description a proper sentence
  git-diff.txt: backtick quote command text
  contrib/completion: extract common diff/difftool options
  diff-lib: accept option flags in run_diff_index()
  diff-lib: define diff_get_merge_base()
  t4068: add --merge-base tests
  builtin/diff-index: learn --merge-base
  builtin/diff-tree: learn --merge-base
  contrib/completion: complete `git diff --merge-base`
 Documentation/git-diff-index.txt       |   9 +-
 Documentation/git-diff-tree.txt        |   7 +-
 Documentation/git-diff.txt             |  36 +++--
 builtin/diff-index.c                   |  10 +-
 builtin/diff-tree.c                    |  18 +++
 builtin/diff.c                         |  49 +++++--
 contrib/completion/git-completion.bash |  15 +-
 diff-lib.c                             |  63 +++++++-
 diff.h                                 |   7 +-
 t/t4068-diff-symmetric-merge-base.sh   | 193 +++++++++++++++++++++++++
 t/t4068-diff-symmetric.sh              |  91 ------------
 11 files changed, 358 insertions(+), 140 deletions(-)
 create mode 100755 t/t4068-diff-symmetric-merge-base.sh
 delete mode 100755 t/t4068-diff-symmetric.sh
Range-diff against v3:
 1:  80e9066a59 =  1:  80e9066a59 t4068: remove unnecessary >tmp
 2:  21b20281e6 =  2:  21b20281e6 git-diff-index.txt: make --cached description a proper sentence
 3:  ca9568c2ea =  3:  ca9568c2ea git-diff.txt: backtick quote command text
 4:  1ac8459541 =  4:  1ac8459541 contrib/completion: extract common diff/difftool options
 5:  496908ac10 !  5:  99d8b51585 diff-lib: accept option flags in run_diff_index()
    @@ diff-lib.c: static int diff_cache(struct rev_info *revs,
     +int run_diff_index(struct rev_info *revs, unsigned int option)
      {
      	struct object_array_entry *ent;
    ++	int cached = !!(option & DIFF_INDEX_CACHED);
      
    -@@ diff-lib.c: int run_diff_index(struct rev_info *revs, int cached)
    - 
    - 	trace_performance_enter();
    - 	ent = revs->pending.objects;
    --	if (diff_cache(revs, &ent->item->oid, ent->name, cached))
    -+	if (diff_cache(revs, &ent->item->oid, ent->name, !!(option & DIFF_INDEX_CACHED)))
    - 		exit(128);
    - 
    --	diff_set_mnemonic_prefix(&revs->diffopt, "c/", cached ? "i/" : "w/");
    -+	diff_set_mnemonic_prefix(&revs->diffopt, "c/", (option & DIFF_INDEX_CACHED) ? "i/" : "w/");
    - 	diffcore_fix_diff_index();
    - 	diffcore_std(&revs->diffopt);
    - 	diff_flush(&revs->diffopt);
    + 	if (revs->pending.nr != 1)
    + 		BUG("run_diff_index must be passed exactly one tree");
     
      ## diff.h ##
     @@ diff.h: const char *diff_aligned_abbrev(const struct object_id *sha1, int);
    @@ diff.h: const char *diff_aligned_abbrev(const struct object_id *sha1, int);
      #define DIFF_RACY_IS_MODIFIED 02
      int run_diff_files(struct rev_info *revs, unsigned int option);
     -int run_diff_index(struct rev_info *revs, int cached);
    ++
     +#define DIFF_INDEX_CACHED 01
     +int run_diff_index(struct rev_info *revs, unsigned int option);
      
 6:  6aac57ca02 !  6:  3287e649f1 diff-lib: define diff_get_merge_base()
    @@ diff-lib.c: static int diff_cache(struct rev_info *revs,
     +	 * ranges produce three pending commits, resulting in a
     +	 * misleading error message.
     +	 */
    -+	if (revs->pending.nr > ARRAY_SIZE(mb_child))
    -+		die(_("--merge-base does not work with more than two commits"));
    ++	if (revs->pending.nr < 1 || revs->pending.nr > 2)
    ++		BUG("unexpected revs->pending.nr: %d", revs->pending.nr);
     +
     +	for (i = 0; i < revs->pending.nr; i++)
     +		mb_child[i] = lookup_commit_reference(the_repository, &revs->pending.objects[i].item->oid);
    -+	if (revs->pending.nr < ARRAY_SIZE(mb_child)) {
    ++	if (revs->pending.nr == 1) {
     +		struct object_id oid;
     +
    -+		if (revs->pending.nr != 1)
    -+			BUG("unexpected revs->pending.nr: %d", revs->pending.nr);
    -+
     +		if (get_oid("HEAD", &oid))
     +			die(_("unable to get HEAD"));
     +
 7:  c9225a0440 =  7:  27930d4476 t4068: add --merge-base tests
 8:  1e4f805e57 !  8:  f54baa4ecd builtin/diff-index: learn --merge-base
    @@ builtin/diff.c: static int builtin_diff_index(struct rev_info *revs,
      		argv++; argc--;
     
      ## diff-lib.c ##
    -@@ diff-lib.c: void diff_get_merge_base(const struct rev_info *revs, struct object_id *mb)
    - int run_diff_index(struct rev_info *revs, unsigned int option)
    +@@ diff-lib.c: int run_diff_index(struct rev_info *revs, unsigned int option)
      {
      	struct object_array_entry *ent;
    + 	int cached = !!(option & DIFF_INDEX_CACHED);
    ++	int merge_base = !!(option & DIFF_INDEX_MERGE_BASE);
     +	struct object_id oid;
     +	const char *name;
    ++	char merge_base_hex[GIT_MAX_HEXSZ + 1];
      
      	if (revs->pending.nr != 1)
      		BUG("run_diff_index must be passed exactly one tree");
      
      	trace_performance_enter();
      	ent = revs->pending.objects;
    --	if (diff_cache(revs, &ent->item->oid, ent->name, !!(option & DIFF_INDEX_CACHED)))
    +-	if (diff_cache(revs, &ent->item->oid, ent->name, cached))
     +
    -+	if (option & DIFF_INDEX_MERGE_BASE) {
    ++	if (merge_base) {
     +		diff_get_merge_base(revs, &oid);
    -+		name = xstrdup(oid_to_hex(&oid));
    ++		name = oid_to_hex_r(merge_base_hex, &oid);
     +	} else {
     +		oidcpy(&oid, &ent->item->oid);
     +		name = ent->name;
     +	}
     +
    -+	if (diff_cache(revs, &oid, name, !!(option & DIFF_INDEX_CACHED)))
    ++	if (diff_cache(revs, &oid, name, cached))
      		exit(128);
      
    - 	diff_set_mnemonic_prefix(&revs->diffopt, "c/", (option & DIFF_INDEX_CACHED) ? "i/" : "w/");
    + 	diff_set_mnemonic_prefix(&revs->diffopt, "c/", cached ? "i/" : "w/");
     
      ## diff.h ##
     @@ diff.h: void diff_get_merge_base(const struct rev_info *revs, struct object_id *mb);
    - #define DIFF_RACY_IS_MODIFIED 02
      int run_diff_files(struct rev_info *revs, unsigned int option);
    + 
      #define DIFF_INDEX_CACHED 01
     +#define DIFF_INDEX_MERGE_BASE 02
      int run_diff_index(struct rev_info *revs, unsigned int option);
 9:  c0d27b125e !  9:  4880d21119 builtin/diff-tree: learn --merge-base
    @@ Metadata
      ## Commit message ##
         builtin/diff-tree: learn --merge-base
     
    -    In order to get the diff between a commit and its merge base, the
    -    currently preferred method is to use `git diff A...B`. However, the
    -    range-notation with diff has, time and time again, been noted as a point
    -    of confusion and thus, it should be avoided. Although we have a
    -    substitute for the double-dot notation, we don't have any replacement
    -    for the triple-dot notation.
    +    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 a replacement for triple-dot
    +    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`, allowing us to gently deprecate
    -    range-notation completely.
    +    `git diff --merge-base A B`.
     
      ## Documentation/git-diff-tree.txt ##
     @@ Documentation/git-diff-tree.txt: SYNOPSIS
    @@ Documentation/git-diff.txt: SYNOPSIS
      'git diff' [<options>] [<commit>] [--] [<path>...]
      'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]
     -'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
    --'git diff' [<options>] <commit>...<commit> [--] [<path>...]
     +'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...]
    + 'git diff' [<options>] <commit>...<commit> [--] [<path>...]
      'git diff' [<options>] <blob> <blob>
      'git diff' [<options>] --no-index [--] <path> <path>
    - 
     @@ Documentation/git-diff.txt: of <commit> and HEAD.  `git diff --merge-base A` is equivalent to
      	branch name to compare with the tip of a different
      	branch.
    @@ builtin/diff.c
      "git diff [<options>] [<commit>] [--] [<path>...]\n"
      "   or: git diff [<options>] --cached [<commit>] [--] [<path>...]\n"
     -"   or: git diff [<options>] <commit> [<commit>...] <commit> [--] [<path>...]\n"
    --"   or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\n"
     +"   or: git diff [<options>] <commit> [--merge-base] [<commit>...] <commit> [--] [<path>...]\n"
    + "   or: git diff [<options>] <commit>...<commit>] [--] [<path>...]\n"
      "   or: git diff [<options>] <blob> <blob>]\n"
      "   or: git diff [<options>] --no-index [--] <path> <path>]\n"
    - COMMON_DIFF_OPTIONS_HELP;
     @@ builtin/diff.c: static int builtin_diff_tree(struct rev_info *revs,
      			     struct object_array_entry *ent1)
      {
10:  42a8c9b665 = 10:  32e3e52b5f contrib/completion: complete `git diff --merge-base`
-- 
2.28.0.760.g8d73e04208
Previous: Denton LiuNext: Denton Liu
Message 47 of 58 in “builtin/diff: learn --merge-base”
  1. 0/4 builtin/diff: learn --merge-baseDenton Liu, Sep 5, 2020
  2. 1/4 t4068: remove unnecessary >tmpDenton Liu, Sep 5, 2020
  3. 3/4 builtin/diff: parse --no-index using parse_options()Denton Liu, Sep 5, 2020
  4. 2/4 git-diff.txt: backtick quote command textDenton Liu, Sep 5, 2020
  5. 4/4 builtin/diff: learn --merge-baseDenton Liu, Sep 5, 2020
  6. Junio C HamanoSep 6, 2020
  7. 0/4 builtin/diff: learn --merge-baseDenton Liu, Sep 10, 2020
  8. 1/4 t4068: remove unnecessary >tmpDenton Liu, Sep 10, 2020
  9. 2/4 git-diff.txt: backtick quote command textDenton Liu, Sep 10, 2020
  10. 3/4 builtin/diff: parse --no-index using parse_options()Denton Liu, Sep 10, 2020
  11. Junio C HamanoSep 10, 2020
  12. Denton LiuSep 13, 2020
  13. Junio C HamanoSep 13, 2020
  14. 4/4 builtin/diff: learn --merge-baseDenton Liu, Sep 10, 2020
  15. 00/10 builtin/diff: learn --merge-baseDenton Liu, Sep 17, 2020
  16. 01/10 t4068: remove unnecessary >tmpDenton Liu, Sep 17, 2020
  17. 02/10 git-diff-index.txt: make --cached description a proper sentenceDenton Liu, Sep 17, 2020
  18. 10/10 contrib/completion: complete `git diff --merge-base`Denton Liu, Sep 17, 2020
  19. 09/10 builtin/diff-tree: learn --merge-baseDenton Liu, Sep 17, 2020
  20. Junio C HamanoSep 17, 2020
  21. Denton LiuSep 18, 2020
  22. Junio C HamanoSep 18, 2020
  23. Denton LiuSep 20, 2020
  24. Junio C HamanoSep 21, 2020
  25. Denton LiuSep 21, 2020
  26. Junio C HamanoSep 21, 2020
  27. Junio C HamanoSep 21, 2020
  28. Denton LiuSep 21, 2020
  29. Junio C HamanoSep 21, 2020
  30. Denton LiuSep 23, 2020
  31. Junio C HamanoSep 25, 2020
  32. Denton LiuSep 26, 2020
  33. 08/10 builtin/diff-index: learn --merge-baseDenton Liu, Sep 17, 2020
  34. Junio C HamanoSep 17, 2020
  35. Jeff KingSep 17, 2020
  36. Junio C HamanoSep 18, 2020
  37. Jeff KingSep 18, 2020
  38. 05/10 diff-lib: accept option flags in run_diff_index()Denton Liu, Sep 17, 2020
  39. Junio C HamanoSep 17, 2020
  40. 04/10 contrib/completion: extract common diff/difftool optionsDenton Liu, Sep 17, 2020
  41. 06/10 diff-lib: define diff_get_merge_base()Denton Liu, Sep 17, 2020
  42. Junio C HamanoSep 17, 2020
  43. Denton LiuSep 18, 2020
  44. Junio C HamanoSep 19, 2020
  45. 03/10 git-diff.txt: backtick quote command textDenton Liu, Sep 17, 2020
  46. 07/10 t4068: add --merge-base testsDenton Liu, Sep 17, 2020
  47. 00/10 builtin/diff: learn --merge-baseDenton Liu, Sep 20, 2020
  48. 01/10 t4068: remove unnecessary >tmpDenton Liu, Sep 20, 2020
  49. 02/10 git-diff-index.txt: make --cached description a proper sentenceDenton Liu, Sep 20, 2020
  50. 06/10 diff-lib: define diff_get_merge_base()Denton Liu, Sep 20, 2020
  51. 05/10 diff-lib: accept option flags in run_diff_index()Denton Liu, Sep 20, 2020
  52. 03/10 git-diff.txt: backtick quote command textDenton Liu, Sep 20, 2020
  53. 07/10 t4068: add --merge-base testsDenton Liu, Sep 20, 2020
  54. 08/10 builtin/diff-index: learn --merge-baseDenton Liu, Sep 20, 2020
  55. Martin ÅgrenSep 29, 2020
  56. 04/10 contrib/completion: extract common diff/difftool optionsDenton Liu, Sep 20, 2020
  57. 09/10 builtin/diff-tree: learn --merge-baseDenton Liu, Sep 20, 2020
  58. 10/10 contrib/completion: complete `git diff --merge-base`Denton Liu, Sep 20, 2020

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.