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

Matthieu Moy· Apr 16, 2009, 16:59 UTC · lore

"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(-)

Show changes to Documentation/git-commit.txt +1 −1

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

Nanako Shiraishi· Apr 18, 2009, 10:11 UTC · re: Matthieu Moy · lore

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

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/

patchgit-commit.txt: Reword the description of git commit.