[PATCH] Documentation for git-log --follow

[PATCH] Documentation for git-log --follow

[Steven Walter]

After vainly searching the Documentation for how to follow renames, I
finally broke down and grepped the source.  It would appear that Linus
didn't add write and docs for this feature when he wrote it.  The
following patch rectifies that, hopefully sparing future users from
resorting to the source code.

Signed-off-by: Steven Walter <stevenrwalter@gmail.com>
---
 Documentation/git-log.txt |    9 +++++++++
 1 files changed, 9 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 7adcdef..63c1dbe 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -61,6 +61,9 @@ include::pretty-options.txt[]
 	the specified paths; this means that "<paths>..." limits only
 	commits, and doesn't limit diff for those commits.
 
+--follow::
+	Continue listing the history of a file beyond renames.
+
 <paths>...::
 	Show only commits that affect the specified paths.
 
@@ -91,6 +94,12 @@ git log -r --name-status release..test::
 	in the "release" branch, along with the list of paths
 	each commit modifies.
 
+git log --follow builtin-rev-list.c::
+
+	Shows the commits that changed builtin-rev-list.c, including
+	those commits that occurred before the file was given its
+	present name.
+
 Discussion
 ----------
 
-- 
1.5.3.rc0

Re: [PATCH] Documentation for git-log --follow

[Linus Torvalds]

On Thu, 12 Jul 2007, Steven Walter wrote:
>
> It would appear that Linus didn't add write and docs for this feature 
> when he wrote it.

I am shocked. *Shocked* I say.

Oh, actually, no I'm not. Par for the course for me. Sorry.

It might be worth documenting that unline all the other log commands, 
--follow requires exactly one pathname. Maybe it's obvious.

		Linus

Re: [PATCH] Documentation for git-log --follow

[Johannes Schindelin]

Hi,

On Thu, 12 Jul 2007, Steven Walter wrote:

> +--follow::
> +	Continue listing the history of a file beyond renames.
> +

Maybe say "Follow the history of a file beyond renames"?

> @@ -91,6 +94,12 @@ git log -r --name-status release..test::
>  	in the "release" branch, along with the list of paths
>  	each commit modifies.
>  
> +git log --follow builtin-rev-list.c::
> +
> +	Shows the commits that changed builtin-rev-list.c, including
> +	those commits that occurred before the file was given its
> +	present name.
> +

This is not particularly clear IMHO.  Probably it would be a good thing to 
contrast vs no-follow:

	The output of "git log builtin-rev-list.c" stops with commit 
	"v1.4.0-rc1~126", as if the file was created there.

	With "--follow", git will detect that this file was renamed 
	from "rev-list.c" and minimally modified in that commit.  After 
	this, it will continue with the log, using the file name 
	"rev-list.c".

Ciao,
Dscho