Re: Using "git log" to find the files patched at the same time as a named file

[Junio C Hamano <gitster@pobox.com>]

Zack Brown <zacharyb@gmail.com> writes:

> ... What about something like this:
>
> "Without this flag, "git log -p <path>..." shows commits that touch
> the specified paths, but it only includes the diffs from those commits

I would say "s/but/and/", because it is more natural that you get the
"limited" view after you explicitly stated that you are "only interested
in these things" by giving pathspecs.

> that affected those specified paths, regardless of whether other paths
> were changed in those same commits. With "git log --full-diff -p
> <path>...", git still only reports commits that touch the specified
> path, but now it also includes the diffs that affected any other paths
> changed in those same commits."

And "but" on the second line from the bottom makes sense---by giving the
option, you are telling it to work differently.

> Would that be an improvement?

Surely.  I would suspect that people would go even further.  "-p" is not
very special (notice I used --name-status in my example).

Also I think the description should start with what it _does_, not with
what happens without it.

So how about this?

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 0e39bb6..5dd1c0c 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -49,11 +49,14 @@ include::diff-options.txt[]
 	commit was reached.
 
 --full-diff::
-	Without this flag, "git log -p <path>..." shows commits that
-	touch the specified paths, and diffs about the same specified
-	paths.  With this, the full diff is shown for commits that touch
-	the specified paths; this means that "<path>..." limits only
-	commits, and doesn't limit diff for those commits.
+	Show all changes, even outside the given pathspecs.
++
+Pathspecs <path>... given to "git log [<options>] <path>..."  limit the
+output to the commits that touch the specified paths.  When options to
+show changes introduced by these commits (e.g. "-p", "--name-only") are
+given, the output of the changes are also limited to the specified paths.
+This option lifts the latter limit and tells "git log" to include all
+changes, even the ones outside of the given pathspecs.
 
 --follow::
 	Continue listing the history of a file beyond renames.