[PATCH] Documentation: point to "History Simplification" from -- <path>

[PATCH] Documentation: point to "History Simplification" from -- <path>

[Thomas Rast]

'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.

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

Sparked by an IRC discussion minutes ago, where I got the paragraph
quoted back to me verbatim to "prove" it shows *all* commits affecting
a file.


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

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 6c93466..437f06e 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -69,10 +69,12 @@ 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 affect any of the specified paths.
+	See "History Simplification" below for a precise definition of
+	the filtering applied.
++
+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

Re: [PATCH] Documentation: point to "History Simplification" from -- <path>

[Junio C Hamano]

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)

>  [\--] <path>...::
> +	Show only commits that affect any of the specified paths.
> +	See "History Simplification" below for a precise definition of
> +	the filtering applied.

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

[Thomas Rast]

'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

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

[Junio C Hamano]

Thomas Rast <trast@student.ethz.ch> writes:

> Or both?

Certainly; I didn't mean to reject the "see also". It just didn't look
right not to update the original sentence that seemed to have caused
confusion to new people.

Applied.