Re: [PATCH] Pay attention to GIT_DIR when searching the git directory

On Mon, 5. May 2008, Jörg Sommer wrote:

Hi Jakub,

Jakub Narebski schrieb am Mon 05. May, 07:10 (-0700):

quoted

Jörg Sommer [off-list ref] writes:

quoted

Johannes Schindelin schrieb am Mon 05. May, 12:36 (+0100):

quoted

quoted

If you do not say _what_ is affected by the change, you only confuse
the readers.

Do you want something like “initialization: Pay attention to GIT_DIR when
searching the git directory”?

I think the idea was to use
  "contrib/hooks/setgitperms: Use GIT_DIR if set"
or something like that.

Well, if this is the prefered form, I'll use it. But I don't like it,
because the affected file is a piece of information that's already in the
commit object. 

First, it is "subsystem", not the affected file. 'git-svn', 'gitweb',
'bash', 'completion'; in this case perhaps 'contrib/hooks', i.e.
  "contrib/hooks: Use GIT_DIR in setgitperms hook, if set"
or something like that.  IMVHO if a patch affest specific subsystem
only, and not the core part of git, you should always use subsystem
prefix, unless the name of subsystem can be put / is put in the commit
subject (first line of commit message).

Second, commit message should be written in such way that it is easy to
understand what the commit does from the first line (the commit summary),
and easy to understand the whats and whys of change from the full commit
message.  In "git log" output you don't see files affected by a commit.

And it makes the :/ syntax useless, because in a series of 
commits all commits start with the same string: the filename.

Commits affecting core don't need to start with a filename, dirname,
or subsystem name.  I gave an example _without_ prefix, didn't I?

[...]

quoted

quoted

Is there a document with guidelines for commit messages, e.g. write the
first letter upper or lower case?

There are a few unwritten conventions.

Are there any plans to write them down?

I think it is true for every project that to send good commit you have
to lurk a little, and examine existing commit messages when writting
one.  Linus Torvalds usually writes good commit messages here.

-- 
Jakub Narebski
Poland