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

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

[Matthieu Moy]

"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.
---
I'm actually resurecting a new thread :

http://thread.gmane.org/gmane.comp.version-control.git/68647/focus=68823

where a user was not understanding why custom diff drivers were not
used by "commit" to tell whether the tree had changed ("I keep doing
git diff's and it says there is no difference, but then git commit
keeps telling me there is").

 Documentation/git-commit.txt |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

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
 
 SYNOPSIS
 --------
-- 
1.6.2.2.449.g92961.dirty

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

[Nanako Shiraishi]

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

> "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/