Re: [PATCH] new tutorial

From: J. Bruce Fields <bfields@fieldses.org>
Date: Jan 16, 2006, 03:57 UTC
Message-ID: <20060116035731.GA14849@fieldses.org>
In-Reply-To: <7v64olysw2.fsf@assigned-by-dhcp.cox.net>

On Sun, Jan 15, 2006 at 03:26:53PM -0800, Junio C Hamano wrote:

> We may want to mention that the canonical commit log message
> format is a single line "summary phrase", an empty line, and the
> body of the message.

Sounds reasonable.  After the second mention of "commit -a" I've added:

	A note on commit messages: though not required, it's a good idea
	to begin the commit message with a single short (less than 50
	character) line summarizing the change, followed by a blank line
	and then a more thorough description.  Tools that turn commits
	into email, for example, use the first line on the Subject line
	and the rest of the commit in the body.

(Alternatively, if we had more of this sort of thing we could collect them into a "best practices" document to reference at the end.)

> A bit narrower fill-column settings, please.

Does 70 characters work for you?

And thanks for the rest of the comments; I'll work through them and then send an update. (May be a few days.) I'll assume you want a replacement unless you tell me you'd prefer an incremental diff.

This caught my eye:

> Empirically the first 7 hexdigits are enough (even 5 for small
> projects such as git itself).  In fact, in the linux-2.6
> repository itself, it appears 5 hexdigits are enough to identify
> all 171902 objects (not just commits) uniquely currently

Five hex digits is only 20 bits, and 171902/2^20 > 1/10, so each additional object has a better than 1-in-10 chance of colliding with an existing object. The chances there hasn't been a collision in the first 5 digits by now must be practically zero. Maybe you're thinking bytes, not hex digits? Unless my math is wrong.

But for these purposes we're just worried about the chance of a particular string having a collision, which should be more like (number of objects) / 2^(4*number of digits), so yeah, 16 digits is overkill, good point.

> BTW, I do not see the CC'ed copy on list archives and am wondering why
> even though I see CC: header in the copy I received...

Maybe the list software didn't like the big patch?

Show 5 quoted lines

> BTW^2, it might be interesting to do
> 
> 	$ git format-patch -C origin..master
> 
> the next time around.

Oh, I see, it catches the rename then.  Neat.

--b.