From 6f2e02aeb004a2ecd6aec1732f4abeaf88fba4b9 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 29 Jul 2020 16:11:16 -0400 Subject: doc/git-log: move "Diff Formatting" from rev-list-options Our rev-list-options.txt include has a "Diff Formatting" section, but it is ifndef'd out for all manpages except git-log. And a few bits of the text are rather out of date. We say "some of these options are specific to git-rev-list". That's obviously silly since we (even before this patch) show the content only for git-log. But moreover, it's not true; each of the listed options is meaningful for other diff commands. We also say "...however other diff options may be given. See git-diff-files for more options." But there's no need to do so; git-log already has a "Common Diff Options" section which includes diff-options.txt. So let's move these options over to git-log and put them with the other diff options, giving a single "diff" section for the git-log documentation. We'll call it "Diff Formatting" but use the all-caps top-level header to match its sibling sections. And we'll rewrite the section intro to remove the useless bits and give a more generic overview of the section which can be later extended. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-log.txt | 42 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 40 insertions(+), 2 deletions(-) (limited to 'Documentation/git-log.txt') diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 20e6d21a74..fb3998d8e0 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -111,8 +111,46 @@ include::rev-list-options.txt[] include::pretty-formats.txt[] -COMMON DIFF OPTIONS -------------------- +DIFF FORMATTING +--------------- + +By default, `git log` does not generate any diff output. The options +below can be used to show the changes made by each commit. + +-c:: + With this option, diff output for a merge commit + shows the differences from each of the parents to the merge result + simultaneously instead of showing pairwise diff between a parent + and the result one at a time. Furthermore, it lists only files + which were modified from all parents. + +--cc:: + This flag implies the `-c` option and further compresses the + patch output by omitting uninteresting hunks whose contents in + the parents have only two variants and the merge result picks + one of them without modification. + +--combined-all-paths:: + This flag causes combined diffs (used for merge commits) to + list the name of the file from all parents. It thus only has + effect when -c or --cc are specified, and is likely only + useful if filename changes are detected (i.e. when either + rename or copy detection have been requested). + +-m:: +--diff-merges:: + This flag makes the merge commits show the full diff like + regular commits; for each merge parent, a separate log entry + and diff is generated. An exception is that only diff against + the first parent is shown when `--first-parent` option is given; + in that case, the output represents the changes the merge + brought _into_ the then-current branch. + +-r:: + Show recursive diffs. + +-t:: + Show the tree objects in the diff output. This implies `-r`. :git-log: 1 include::diff-options.txt[] -- cgit v1.2.3 From 6cea104b2c0266d61fbce7e9ba485dc6d13c0c8f Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 29 Jul 2020 16:11:27 -0400 Subject: doc/git-log: drop "-r" diff option This has been the default since 170c04383b (Porcelain level "log" family should recurse when diffing., 2007-08-27). There's not even a way to turn it off, so you'd never even want "-r" to override that. It's not the default for plumbing like diff-tree, of course, but the option is documented separately there. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-log.txt | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'Documentation/git-log.txt') diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index fb3998d8e0..2cbe636b2b 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -146,11 +146,8 @@ below can be used to show the changes made by each commit. in that case, the output represents the changes the merge brought _into_ the then-current branch. --r:: - Show recursive diffs. - -t:: - Show the tree objects in the diff output. This implies `-r`. + Show the tree objects in the diff output. :git-log: 1 include::diff-options.txt[] -- cgit v1.2.3 From 9a6d515fc38abc36a94228f2b96813e1b07c0059 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 29 Jul 2020 16:12:10 -0400 Subject: doc/git-log: move "-t" into diff-options list The "-t" option is infrequently used; it doesn't deserve a spot near the top of the options list. Let's push it down into the diff-options include, near the definition of --raw. We'll protect it with a git-log ifdef, since it doesn't make any sense for non-tree diff commands. Note that this means it also shows up in git-show, but that's a good thing; it applies equally well there. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-log.txt | 3 --- 1 file changed, 3 deletions(-) (limited to 'Documentation/git-log.txt') diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 2cbe636b2b..0a4c99e5f8 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -146,9 +146,6 @@ below can be used to show the changes made by each commit. in that case, the output represents the changes the merge brought _into_ the then-current branch. --t:: - Show the tree objects in the diff output. - :git-log: 1 include::diff-options.txt[] -- cgit v1.2.3 From 5fbb4bc1910f76b344fcb88df2544701b6030435 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 29 Jul 2020 16:12:20 -0400 Subject: doc/git-log: clarify handling of merge commit diffs It can be surprising that git-log doesn't show any diff for merge commits by default. Arguably "--cc" would be a reasonable default, but it's very expensive (which is why we turn it on for "git show" but not for "git log"). Let's at least document the current behavior, including the recent "--first-parent implies -m" case Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/git-log.txt | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'Documentation/git-log.txt') diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 0a4c99e5f8..9ccba65469 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -117,6 +117,13 @@ DIFF FORMATTING By default, `git log` does not generate any diff output. The options below can be used to show the changes made by each commit. +Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits +will never show a diff, even if a diff format like `--patch` is +selected, nor will they match search options like `-S`. The exception is +when `--first-parent` is in use, in which merges are treated like normal +single-parent commits (this can be overridden by providing a +combined-diff option or with `--no-diff-merges`). + -c:: With this option, diff output for a merge commit shows the differences from each of the parents to the merge result -- cgit v1.2.3