From: Jonathan Nieder <jrnieder@gmail.com>
Date: Wed, 01 May 2013 18:54:14 GMT
Subject: Re: [PATCH 3/5] sha1_name.c: simplify @-parsing in get_sha1_basic()
Message-ID: <20130501185414.GN24467@google.com>
In-Reply-To: <CALkWK0nTSMYvh8VMgQ6Q0EoPMmRa2vyodz+tDmpPp1d6KYmq8w@mail.gmail.com>

Ramkumar Ramachandra wrote:

> [1]: https://www.ohloh.net/p/git/factoids#FactoidCommentsLow

Since this has been coming up from time to time:

I have nothing against including helpful comments where appropriate.
But one aspect which that factoid misses is that git has some very
detailed, very dense documentation available in its commit log.  Tools
like "git gui blame" and "git log -S" can show detailed historical
information about the purpose of every line of code.  A nice feature
of such documentation is that it is in a context where it cannot fall
out of date.

So for example I can do

	$ git log -S'if (len && ambiguous_path(str, len))' -- sha1_name.c
	commit 11cf8801
	Author: Nicolas Pitre <nico@cam.org>
	Date:   Thu Feb 1 17:29:33 2007 -0500

	    provide a nice @{...} syntax to always mean the current branch reflog

	    This is shorter than HEAD@{...} and being nameless it has no semantic
	    issues.

	    Signed-off-by: Nicolas Pitre <nico@cam.org>
	    Signed-off-by: Junio C Hamano <junkio@cox.net>

and then "git show 11cf8801" will show me exactly what change prompted
that "len" test.

The same is true of the Linux kernel, too.

Hope that helps,
Jonathan