[PATCH] Update documentation: git-commit is not a shell command

[PATCH] Update documentation: git-commit is not a shell command

[Ramkumar Ramachandra]

Reported by Osamu Aoki through http://bugs.debian.org/560795

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/gitcore-tutorial.txt |    9 +--------
 1 files changed, 1 insertions(+), 8 deletions(-)

diff --git a/Documentation/gitcore-tutorial.txt
b/Documentation/gitcore-tutorial.txt
index f762dca..ebc5d0b 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -454,14 +454,7 @@ will be pruned out, and the rest will be used as
the commit message for
 the change. If you decide you don't want to commit anything after all at
 this point (you can continue to edit things and update the index), you
 can just leave an empty message. Otherwise `git commit` will commit
-the change for you.
-
-You've now made your first real git commit. And if you're interested in
-looking at what `git commit` really does, feel free to investigate:
-it's a few very simple shell scripts to generate the helpful (?) commit
-message headers, and a few one-liners that actually do the
-commit itself ('git-commit').
-
+the change for you. You've now made your first real git commit.

 Inspecting Changes
 ------------------
-- 
1.6.5

Re: [PATCH] Update documentation: git-commit is not a shell command

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> diff --git a/Documentation/gitcore-tutorial.txt
> b/Documentation/gitcore-tutorial.txt
> index f762dca..ebc5d0b 100644
> --- a/Documentation/gitcore-tutorial.txt
> +++ b/Documentation/gitcore-tutorial.txt
> @@ -454,14 +454,7 @@ will be pruned out, and the rest will be used as
> the commit message for
>  the change. If you decide you don't want to commit anything after all at
>  this point (you can continue to edit things and update the index), you
>  can just leave an empty message. Otherwise `git commit` will commit
> -the change for you.
> -
> -You've now made your first real git commit. And if you're interested in
> -looking at what `git commit` really does, feel free to investigate:
> -it's a few very simple shell scripts to generate the helpful (?) commit
> -message headers, and a few one-liners that actually do the
> -commit itself ('git-commit').
> -
> +the change for you. You've now made your first real git commit.

While the issue you are addressing may be a valid one, removing the whole
paragraph and not doing anything else is not an improvement.  Read the
changed text in a larger context and you will notice that the tutorial
sequence around there does not make much sense anymore.

The point of the core tutorial is to introduce the reader to the low level
structure and plumbing, and a major reason for running "git commit" at
that point in the tutorial is to mention that what even a relatively high
level command "git commit" does can be scripted.  Up to that point, the
tutorial showed a much lower level tools to create a commit, and said
"... but you've done that once already, so let's just use the helpful
script this time:" (by the way, you forgot to change this "script").

So after "You've now made your first real git commit" (which is not true,
by the way---the reader has already done so with commit-tree), you would
need to mention that what git-commit does can be scripted, that it indeed
was a script before Git v1.5.4, that if you want to write a command that
makes a commit but in a different way then you can script it using the
same ingredients the scripted "git commit" used to use, and perhaps that
the scripted version is available as a reference in the git source tree in
contrib/examples.

Actually, I changed my mind.  There are many other Porcelain commands in
the core tutorial that are no longer scripted.  It is better to leave the
main text of the tutorial as-is.  In the initial part of the document,
mention that many Porcelain commands were scripts back when the document
was written, that the document uses them as examples of how plumbing are
fit together to form them, that some scripted Porcelain implementations
are found in contrib/examples/ directory of the source tree for reference
purposes, and that the description of what the plumbing layer commands do
in the document is still valid even though the Porcelain commands mentined
in the document are not implemented in terms of the plumbing commands in
shell scripts anymore.

Re: [PATCH] Update documentation: git-commit is not a shell command

[Ramkumar Ramachandra]

> Actually, I changed my mind.  There are many other Porcelain commands in
> the core tutorial that are no longer scripted.  It is better to leave the
> main text of the tutorial as-is.  In the initial part of the document,
> mention that many Porcelain commands were scripts back when the document
> was written, that the document uses them as examples of how plumbing are
> fit together to form them, that some scripted Porcelain implementations
> are found in contrib/examples/ directory of the source tree for reference
> purposes, and that the description of what the plumbing layer commands do
> in the document is still valid even though the Porcelain commands mentined
> in the document are not implemented in terms of the plumbing commands in
> shell scripts anymore.

Right. Thanks for pointing that out. Here's the patch fixing it:
http://permalink.gmane.org/gmane.comp.version-control.git/137242

-- Ram