Re: [PATCH] git-commit.txt: Reword the description of git commit.

From: Nanako Shiraishi <nanako3@lavabit.com>
Date: Apr 18, 2009, 10:11 UTC
Message-ID: <20090418191123.6117@nanako3.lavabit.com>
In-Reply-To: <1239901174-30072-1-git-send-email-Matthieu.Moy@imag.fr>

Quoting Matthieu Moy <Matthieu.Moy@imag.fr> writes:

Show 14 quoted lines

> "Record changes" insists on recording the _delta_ between the parent
> commit and the new revision, which can be mis-leading, since Git is
> really snapshot-oriented. The new wording may be less misleading.
> ...
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index b5d81be..c7f728f 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -3,7 +3,7 @@ git-commit(1)
>  
>  NAME
>  ----
> -git-commit - Record changes to the repository
> +git-commit - Record a new revision in the repository

I don't think this is a good change.

When new people who don't know git yet are looking at output from git-help command in order to find what command they want to try, the original text requires them to know what "repository" means, but the new description forces them to know also what a revision is.

I also think the original text is technically more correct. git-commit command does two things at the same time. It

1) creates a new commit object (a.k.a revision)
2) updates the HEAD pointer to the new commit object

Your new wording expresses only the first part. Because it updates the HEAD, the end user perceives the difference between the commit previously pointed by HEAD and the new commit as recorded.

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/