[PATCH v2] Documentation: clarify effects of -- <path> arguments

[Thomas Rast <trast@student.ethz.ch>]

'git log -- <path>' does not "show commits that affect the specified
paths" in a literal sense unless --full-history is given (for example,
a file that only existed on a side branch will turn up no commits at
all!).

Reword it to specify the actual intent of the filtering, and point to
the "History Simplification" section.

The first new sentence was suggested by Junio.

Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---

Junio C Hamano wrote:
> Thomas Rast <trast@student.ethz.ch> writes:
> 
> > 'git log -- <path>' does not "show commits that affect the specified
> > paths" in a literal sense unless --full-history is given (for example,
> > a file that only existed on a side branch will turn up no commits at
> > all!).
> >
> > Point the user to the "History Simplification" section to avoid
> > surprises.
> 
> Hmm, or perhaps replace it with a brief explanation instead of redirecting
> the readers to a separate section without telling them anything here?
> 
>     Show only commits that are enough to explain how the files that match
>     the specified paths came to be.
> 
> (this is my attempt to paraphrase $gmane/90659)

Or both?  I really like your version; I tried to come up with a
concise wording and couldn't.  But the user may still want to read
about it in detail.


 Documentation/git-log.txt |   11 +++++++----
 1 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 6c93466..249fc87 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -69,10 +69,13 @@ produced by --stat etc.
 	its size is not included.
 
 [\--] <path>...::
-	Show only commits that affect any of the specified paths. To
-	prevent confusion with options and branch names, paths may need
-	to be prefixed with "\-- " to separate them from options or
-	refnames.
+	Show only commits that are enough to explain how the files
+	that match the specified paths came to be.  See "History
+	Simplification" below for details and other simplification
+	modes.
++
+To prevent confusion with options and branch names, paths may need to
+be prefixed with "\-- " to separate them from options or refnames.
 
 include::rev-list-options.txt[]
 
-- 
1.7.7.rc0.370.gdcae57