Re: erratic behavior commit --allow-empty

[Angelo Borsotti <angelo.borsotti@gmail.com>]

Hi Phil,

> Perhaps the confusion arises from the the meaning of "the safety".  In
> this case, the safety mechanism in place is to prevent you from
> creating a child commit which has the same "tree" contents (working
> directory) as the parent commit.  It will not be the same commit
> because it has different parent(s) than its parent commit; but the
> tree (working directory) is the same and git normally prevents you
> from doing this because normally this is an accident, a mistake.
>
> --allow-empty tells git you intend to do this and so it should bypass
> this "no changed files" safety mechanism.  It is not a safety to
> prevent you creating a new commit with the exact same sha1; the safety
> is concerned only with the exact same "working directory" file
> contents.
>
> Can you suggest a rewrite of this description which would make it more clear?

Instead of:

"Usually recording a commit that has the exact same tree as its sole
parent commit is a mistake, and the command prevents you from making
such a commit. This option bypasses the safety, and is primarily for
use by foreign SCM interface scripts."

I would suggest:

"Usually recording a commit that has the exact same tree as its sole
parent commit is not allowed, and the command prevents you from making
such a commit. This option allows to disregard this condition, thereby
making a commit even when the trees are the same. Note that when the
tree, author, parents, message and date (with the precision of one
second) are the same as those of an existing commit object, no new
commit object is created, and the identity of the existing one is
returned."
>
> Phil