threads / patch / 28256

patchDocumentation: point to "History Simplification" from -- <path>

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

## tl;dr

4 messages between Aug 29, 2011 and Aug 30, 2011. Diffs are folded; open one to read it.

replies: 3people: 2as markdown or json

Thomas Rast· Aug 29, 2011, 23:18 UTC · lore

'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(-)

Show changes to Documentation/git-log.txt +6 −4

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

Junio C Hamano· Aug 29, 2011, 23:50 UTC · re: Thomas Rast · lore

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

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

Show 7 quoted lines

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

Thomas Rast· Aug 30, 2011, 09:21 UTC · re: Junio C Hamano · lore

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

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:

Show 17 quoted lines

> 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(-)

Show changes to Documentation/git-log.txt +7 −4

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

Junio C Hamano· Aug 30, 2011, 18:03 UTC · re: Thomas Rast · lore

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

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.