Documentation/git-commit.txt

Documentation/git-commit.txt

[Junio C Hamano]

I attempted to rewrite the git-commit documentation.

I think I went overboard and ended up not using the word
"index", but eradicating the word was not my intention.  I think
we should hint how the index is used to implement the semantics
somewhere near the end where it is not distracting to ordinary
users but is accessbile by people who are interested in the
plumbing-Porcelain interface. 

---

  The following patch will _not_ apply as is, as I sprinkled a lot
  of annotations in it, but you should be able to run

          sed -e '/^|/d'

  on it to make it apply if you want.

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 517a86b..50e8fd0 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -14,25 +14,111 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Updates the index file for given paths, or all modified files if
-'-a' is specified, and makes a commit object.  The command specified
-by either the VISUAL or EDITOR environment variables are used to edit
-the commit log message.
|
| General idea; (1) we do not have to say "index" in Porcelain-ish
| documentation.  (2) we should have a separate ENVIRONMENT section
| at the end as all UNIX manpage does.
|
+Records a tree state as a new commit object.  The command is
+used for both recording your own changes and recording the
+result of manual resolution of a conflicted merge.
+
+When recoring your own work, the contents of modified files in
+your working tree are staged with gitlink:git-add[1].  Removal
+of a file are staged with gitlink:git-rm[1].  After building the
+state to be committed incrementally with these commands, `git
+commit` (without any pathname parameter) is used to record what
+has been staged so far.  This is the most basic form of the
+command.  An example:
|
| Give examples early and abundance of them.  Mention add and rm
| as staging commands; technically mv is also a staging command but
| this manpage is not about various ways to stage things, but
| making a commit out of staged state, so omit it.
|
+
+------------
+$ edit hello.c
+$ git rm goodbye.c
+$ git add hello.c
+$ git commit
+------------
+
+////////////
+We should fix 'git rm' to remove goodbye.c from both index and
+working tree for the above example.
+////////////
+
+Instead of staging files after each individual change, you can
+tell `git commit` to notice the changes to the tracked files in
+your working tree and do corresponding `git add` and `git rm`
+for you.  That is, this example does the same as the earlier
+example if there is no other change in your working tree:
+
+------------
+$ edit hello.c
+$ rm goodbye.c
+$ git commit -a
+------------
+
+The command `git commit -a` first looks at your working tree,
+notices that you have modified hello.c and removed goodbye.c,
+and performs necessary `git add` and `git rm` for you.
+
+After staging changes to many files, you can alter the order the
+changes are recorded in, by giving pathnames to `git commit`.
+When pathnames are given, the command makes a commit that
+only records the changes made to the named paths:
+
+------------
+$ edit hello.c hello.h
+$ git add hello.c hello.h
+$ edit Makefile
+$ git commit Makefile
+------------
+
+This makes a commit that records the modification to `Makefile`.
+The changes staged for `hello.c` and `hello.h` are not included
+in the resulting commit.  However, their changes are not lost --
+they are still staged and merely held back.  After the above
+sequence, if you do:
+
+------------
+$ git commit
+------------
+
+this second commit would record the changes to `hello.c` and
+`hello.h` as expected.
+
+
+After a merge (initiated by either gitlink:git-merge[1] or
+gitlink:git-pull[1]) stops because of conflicts, cleanly merged
+paths are already staged to be committed for you, and paths that
+conflicted are left in unmerged state.  You would have to first
+check which paths are conflicting with gitlink:git-ls-files[1]
+and after fixing them manually in your working tree, you would
+stage the result as usual with gitlink:git-add[1]:
+
+------------
+$ git ls-files -u
+100644 c87c61af00c6d2cd7212240e26089e24b90bbe05 1	hello.c
+100644 646b6e73318e04cfff7b20abd5d06be424bce503 2	hello.c
+100644 44b1ce4c6b56348e1661b60fc923cb80cb44d4ff 3	hello.c
+$ edit hello.c
+$ git add hello.c
+------------
|
| Obviously 'ls-files -u' is a plumbing so we might want to give an
| equivalent Porcelain.  We could say 'git status' and have the
| reader look for "unmerged:", which might be better.  I dunno.
|
+
+After resolving conflicts and staging the result, `git ls-files -u`
+would stop mentioning the conflicted path.  When you are done,
+run `git commit` to finally record the merge:
+
+------------
+$ git commit
+------------
+
+As with the case to record your own changes, you can use `-a`
+option to save typing.  One difference is that during a merge
+resolution, you cannot use `git commit` with pathnames to
+alter the order the changes are committed, because the merge
+should be recorded as a single commit.  In fact, the command
+refuses to run when given pathnames (but see `-i` option).
|
| "con paths" form is really about 'alter the order of things
| that are committed', in other words 'you may have started 
| staging but we let you split what is staged'.  Once the reader
| understands it, it should be natural why we cannot use "paths"
| during a merge resolution.
|
 
-Several environment variable are used during commits.  They are
-documented in gitlink:git-commit-tree[1].
-
-
-This command can run `commit-msg`, `pre-commit`, and
-`post-commit` hooks.  See link:hooks.html[hooks] for more
-information.
|
| In addition to ENVIRONMENT, many Porcelain-ish can invoke
| hooks, and we should have HOOKS section at the same location
| across manpages so people can expect where to find them.
| I just chose them to be at the end.
|

 
 OPTIONS
 -------
 -a|--all::
-	Update all paths in the index file.  This flag notices
-	files that have been modified and deleted, but new files
-	you have not told git about are not affected.
+	Tell the command to automatically stage files that have
+	been modified and deleted, but new files you have not
+	told git about are not affected.
|
| No need to say "index", although I do not think we should
| avoid the word.
|
 
 -c or -C <commit>::
 	Take existing commit object, and reuse the log message
@@ -55,16 +141,13 @@ OPTIONS
 -s|--signoff::
 	Add Signed-off-by line at the end of the commit message.
 
--v|--verify::
-	Look for suspicious lines the commit introduces, and
-	abort committing if there is one.  The definition of
-	'suspicious lines' is currently the lines that has
-	trailing whitespaces, and the lines whose indentation
-	has a SP character immediately followed by a TAB
-	character.  This is the default.
-
--n|--no-verify::
-	The opposite of `--verify`.
+--no-verify::
+	By default, the command looks for suspicious lines the
+	commit introduces, and aborts committing if there is one.
+	The definition of 'suspicious lines' is currently the
+	lines that has trailing whitespaces, and the lines whose
+	indentation has a SP character immediately followed by a
+	TAB character.  This option turns off the check.
|
| The --verify option does not exist anymore.  This is an independent fix.
| We do not yet describe --verbose (and real '-v') in the
| current page, which is quite BAD.  It shows the diff between HEAD
| and what is being committed.
|
 
 -e|--edit::
 	The message taken from file with `-F`, command line with
@@ -95,16 +177,16 @@ but can be used to amend a merge commit.
 --
 
 -i|--include::
-	Instead of committing only the files specified on the
-	command line, update them in the index file and then
-	commit the whole index.  This is the traditional
-	behavior.
+	Before making a commit out of staged contents so far,
+	stage the contents of paths given on the command line
+	as well.  This is usually not what you want unless you
+	are concluding a conflicted merge.
 
 -o|--only::
-	Commit only the files specified on the command line.
-	This format cannot be used during a merge, nor when the
-	index and the latest commit does not match on the
-	specified paths to avoid confusion.
+	Commit only the files specified on the command line;
+	this is the default when pathnames are given on the
+	command line, so you usually do not have to give this
+	option.  This format cannot be used during a merge.
 
 \--::
 	Do not interpret any more arguments as options.
@@ -118,46 +200,16 @@ If you make a commit and then found a mistake immediately after
 that, you can recover from it with gitlink:git-reset[1].
 
 
-Discussion
-----------
-
-`git commit` without _any_ parameter commits the tree structure
-recorded by the current index file.  This is a whole-tree commit
-even the command is invoked from a subdirectory.
-
-`git commit --include paths...` is equivalent to
-
-	git update-index --remove paths...
-	git commit
-
-That is, update the specified paths to the index and then commit
-the whole tree.
-
-`git commit paths...` largely bypasses the index file and
-commits only the changes made to the specified paths.  It has
-however several safety valves to prevent confusion.
-
-. It refuses to run during a merge (i.e. when
-  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
-  that the traditional semantics now needs -i flag.
-
-. It refuses to run if named `paths...` are different in HEAD
-  and the index (ditto about reminding).  Added paths are OK.
-  This is because an earlier `git diff` (not `git diff HEAD`)
-  would have shown the differences since the last `git
-  update-index paths...` to the user, and an inexperienced user
-  may mistakenly think that the changes between the index and
-  the HEAD (i.e. earlier changes made before the last `git
-  update-index paths...` was done) are not being committed.
-
-. It reads HEAD commit into a temporary index file, updates the
-  specified `paths...` and makes a commit.  At the same time,
-  the real index file is also updated with the same `paths...`.
-
-`git commit --all` updates the index file with _all_ changes to
-the working tree, and makes a whole-tree commit, regardless of
-which subdirectory the command is invoked in.
|
| Lose this section that only talks about implementation detail
| and expect the readers to understand the behaviour from it.
| The audience when the page was originally written were well
| versed in plumbing and the above technical description
| conveyed what we wanted to say in very precise terms, but that
| was only because git was very young.
|

+ENVIRONMENT VARIABLES
+---------------------
+The command specified by either the VISUAL or EDITOR environment
+variables are used to edit the commit log message.
 
+HOOKS
+-----
+This command can run `commit-msg`, `pre-commit`, and
+`post-commit` hooks.  See link:hooks.html[hooks] for more
+information.
 
 Author
 ------

Re: Documentation/git-commit.txt

[Salikh Zakirov]

Junio Hamano wrote:
> +Instead of staging files after each individual change, you can
> +tell `git commit` to notice the changes to the tracked files in
> +your working tree and do corresponding `git add` and `git rm`
> +for you.  

This part is confusing as hell to anyone having any experience
with either CVS, SVN, Hg or Monotone, as doing "corresponding `git add`
and `git rm`" commands automatically will be interpreted as adding
untracked files automatically, which is not the case here.

Re: Documentation/git-commit.txt

[Junio C Hamano]

Salikh Zakirov <Salikh.Zakirov@Intel.com> writes:

> Junio Hamano wrote:
>> +Instead of staging files after each individual change, you can
>> +tell `git commit` to notice the changes to the tracked files in
>> +your working tree and do corresponding `git add` and `git rm`
>> +for you.  
>
> This part is confusing as hell to anyone having any experience
> with either CVS, SVN, Hg or Monotone, as doing "corresponding `git add`
> and `git rm`" commands automatically will be interpreted as adding
> untracked files automatically, which is not the case here.

Well, that's why the description says 'the changes to the
tracked files' above to make it clear.  An obvious alternative
is not to talk about staging in terms of `git add` and `git rm`
but instead mention `git update-index` in that part of the
documentation, but I think that is going backwards.  I think the
conclusion of recent discussions is not to paper over the
differences from new people (nor making git closer to other
systems by castrating git), but make things easier to learn for
them.  My attempt to update git-commit documentation is a part
of this effort.

Better rewording is very much appreciated.

But you are right.  Prior experiences with other systems would
make it harder to learn git here, because 'git add', especially
with Nico's enhancement in 'next', is different from 'cvs add'.

The problem is that these systems do not have the concept of
tracking 'contents' (they instead track paths), and 'add' to
them mean 'add the named paths to the set of tracked paths'.

On the other hand, git fundamentally tracks contents.  We do
have the concept of 'the set of tracked paths', but that is a
side effect of tracking contents.  In other words, you do not
'add' a path without 'add'ing its contents.

By the way, I have been wondering if the --only variant of the
command should also add untracked files to the index.  That is:

	$ git commit foo.c '*.h'

currently barfs if foo.c is not tracked, and/or there is no
tracked header files.  We could instead run git-update-index
--add on them.

Incidentally, this would make this sequence possible:

	$ tar xf /var/tmp/foo.tar ;# extract tarball here.
        $ git init-db
        $ git commit -m 'initial import' .

Re: Documentation/git-commit.txt

[Nicolas Pitre]

On Fri, 8 Dec 2006, Junio C Hamano wrote:

> By the way, I have been wondering if the --only variant of the
> command should also add untracked files to the index.  That is:
> 
> 	$ git commit foo.c '*.h'
> 
> currently barfs if foo.c is not tracked, and/or there is no
> tracked header files.  We could instead run git-update-index
> --add on them.

That would be a good thing indeed.

> Incidentally, this would make this sequence possible:
> 
> 	$ tar xf /var/tmp/foo.tar ;# extract tarball here.
>         $ git init-db
>         $ git commit -m 'initial import' .

... making the UI even more consistent.

Re: Documentation/git-commit.txt

[Alan Chandler]

On Friday 08 December 2006 11:55, Salikh Zakirov wrote:
> Junio Hamano wrote:
> > +Instead of staging files after each individual change, you can
> > +tell `git commit` to notice the changes to the tracked files in
> > +your working tree and do corresponding `git add` and `git rm`
> > +for you.
>
> This part is confusing as hell to anyone having any experience
> with either CVS, SVN, Hg or Monotone, as doing "corresponding `git
> add` and `git rm`" commands automatically will be interpreted as
> adding untracked files automatically, which is not the case here.

I thought the wording here was a little weird too.  I think this stems 
from the mistake of saying "tracked files" instead of "tracked content" 
which then leads to you falling back to the git add and git rm 
commands..

How about the following wording here

Instead of staging the content of each file immediately after changing 
it, you can wait until you have completed all the changes you want to 
make and then use the `-a` option to tell `git commit` to look for all 
changes to the content it is tracking and commit it automatically. That 
is, this example ...


  

-- 
Alan Chandler

Re: Documentation/git-commit.txt

[Nicolas Pitre]

On Fri, 8 Dec 2006, Junio C Hamano wrote:

> I attempted to rewrite the git-commit documentation.
> 
> I think I went overboard and ended up not using the word
> "index", but eradicating the word was not my intention.  I think
> we should hint how the index is used to implement the semantics
> somewhere near the end where it is not distracting to ordinary
> users but is accessbile by people who are interested in the
> plumbing-Porcelain interface. 
[...]

Frankly I feel unconfortable with this.

1) too many examples.

Yes, examples are good, but somehow there is something in the current 
text that make me feel they are not providing the clarification they 
should.  Dunno... I think I'd still push them after option list.

2) explanation of how to resolve and commit a conflicting merge should 
   really be found in git-merge.txt not in git-commit.txt.

It feels a bit awkward to suddenly start talking about git ls-files and 
merge here.  It would be much clearer to simply say "when done just 
commit your changes as usual" in the merge doc than bringing in merge 
concepts in the commit doc.

[...]

I started to insert my comments inline, but at some point it became too 
messy.  So I decided to give it a try of my own instead.  Here what I 
think would be a better direction for improving the commit man page 
(would need a few examples inserted towards the end like usual, and the 
env vars too):

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 517a86b..6a9cec9 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -14,25 +14,43 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Updates the index file for given paths, or all modified files if
-'-a' is specified, and makes a commit object.  The command specified
-by either the VISUAL or EDITOR environment variables are used to edit
-the commit log message.
+Use 'git commit' when you want to record your changes into the repository
+along with a log message describing what the commit is about. All changes
+to be committed must be explicitly identified using one of the following
+methods:
 
-Several environment variable are used during commits.  They are
-documented in gitlink:git-commit-tree[1].
+1) by using gitlink:git-add[1] to incrementally "add" changes to the
+   next commit before using the 'commit' command (Note: even modified
+   files must be "added");
 
+2) by using gitlink:git-rm[1] to identify content removal for the next
+   commit, again before using the 'commit' command;
+
+3) by directly listing files containing changes to be committed as arguments
+   to the 'commit' command, in which cases only those files alone will be
+   considered for the commit;
+
+4) by using the -a switch with the 'commit' command to automatically "add"
+   changes from all known files i.e. files that have already been committed
+   before, and perform the actual commit.
+
+The 'git status' command can be used to obtain a summary of what is included
+by (1) and (2) for the next commit.
+
+If you make a commit and then found a mistake immediately after
+that, you can recover from it with gitlink:git-reset[1].
 
 This command can run `commit-msg`, `pre-commit`, and
 `post-commit` hooks.  See link:hooks.html[hooks] for more
 information.
 
+
 OPTIONS
 -------
 -a|--all::
-	Update all paths in the index file.  This flag notices
-	files that have been modified and deleted, but new files
-	you have not told git about are not affected.
+	Tell the command to automatically stage files that have
+	been modified and deleted, but new files you have not
+	told git about are not affected.
 
 -c or -C <commit>::
 	Take existing commit object, and reuse the log message
@@ -95,68 +113,18 @@ but can be used to amend a merge commit.
 --
 
 -i|--include::
-	Instead of committing only the files specified on the
-	command line, update them in the index file and then
-	commit the whole index.  This is the traditional
-	behavior.
-
--o|--only::
-	Commit only the files specified on the command line.
-	This format cannot be used during a merge, nor when the
-	index and the latest commit does not match on the
-	specified paths to avoid confusion.
+	Before making a commit out of staged contents so far,
+	stage the contents of paths given on the command line
+	as well.  This is usually not what you want unless you
+	are concluding a conflicted merge.
 
 \--::
 	Do not interpret any more arguments as options.
 
 <file>...::
-	Files to be committed.  The meaning of these is
-	different between `--include` and `--only`.  Without
-	either, it defaults `--only` semantics.
-
-If you make a commit and then found a mistake immediately after
-that, you can recover from it with gitlink:git-reset[1].
-
-
-Discussion
-----------
-
-`git commit` without _any_ parameter commits the tree structure
-recorded by the current index file.  This is a whole-tree commit
-even the command is invoked from a subdirectory.
-
-`git commit --include paths...` is equivalent to
-
-	git update-index --remove paths...
-	git commit
-
-That is, update the specified paths to the index and then commit
-the whole tree.
-
-`git commit paths...` largely bypasses the index file and
-commits only the changes made to the specified paths.  It has
-however several safety valves to prevent confusion.
-
-. It refuses to run during a merge (i.e. when
-  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
-  that the traditional semantics now needs -i flag.
-
-. It refuses to run if named `paths...` are different in HEAD
-  and the index (ditto about reminding).  Added paths are OK.
-  This is because an earlier `git diff` (not `git diff HEAD`)
-  would have shown the differences since the last `git
-  update-index paths...` to the user, and an inexperienced user
-  may mistakenly think that the changes between the index and
-  the HEAD (i.e. earlier changes made before the last `git
-  update-index paths...` was done) are not being committed.
-
-. It reads HEAD commit into a temporary index file, updates the
-  specified `paths...` and makes a commit.  At the same time,
-  the real index file is also updated with the same `paths...`.
-
-`git commit --all` updates the index file with _all_ changes to
-the working tree, and makes a whole-tree commit, regardless of
-which subdirectory the command is invoked in.
+	Files to be committed.  If provided, only those files are
+	considered FOR COMMIT.  If `-i` or `--include` is also provided
+	then the staged content is included as well.
 
 

Re: Documentation/git-commit.txt

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

> Frankly I feel unconfortable with this.
>
> 1) too many examples.
>
> Yes, examples are good, but somehow there is something in the current 
> text that make me feel they are not providing the clarification they 
> should.  Dunno... I think I'd still push them after option list.

Hmmm.  I was merely trying to respond with recent requests on
the list (might have been #git log) to make common usage
examples more prominent.  While I feel that following the UNIXy
manpage tradition to push examples down is the right thing to
do, you and I are not the primary audience of Porcelain
manpages, so...

> 2) explanation of how to resolve and commit a conflicting merge should 
>    really be found in git-merge.txt not in git-commit.txt.
>
> It feels a bit awkward to suddenly start talking about git ls-files and 
> merge here.

I agree that it looks a bit out of place; the primary reason I
talked about the merge was to make it clear that a conflicted
merge will still stage the changes for cleanly auto-resolved
paths.  In other words, it makes me feel uneasy that there is no
mention of it in the list in your version that follows this
sentence:

> +... All changes
> +to be committed must be explicitly identified using one of the following
> +methods:

It would make me happier if you had, at the end of enumeration,
something like:

	Note that the contents of the paths that resolved
        cleanly by a conflicted merge are automatically staged
        for the next commit; you still need to explicitly
        identify what you want in the resulting commit using one
        of the above methods before concluding the merge.

Another reason I described the merge workflow is it would become
much less clear why --only is useless in merge situation if the
reader does not know that a conflicted merge stages the
auto-resolved changes.

Re: Documentation/git-commit.txt

[J. Bruce Fields]

On Fri, Dec 08, 2006 at 03:20:32AM -0800, Junio C Hamano wrote:
> I think I went overboard and ended up not using the word
> "index", but eradicating the word was not my intention.

Yeah, "index" is a perfectly OK word, and it's already used all over the
documentation.

I think what you want to avoid is a huge digression into blobs, trees,
SHA1's, and the structure of the index file when you could just slip it
in there without a lot of fanfare, maybe like:

> +When recoring your own work, the contents of modified files in
> +your working tree are staged with gitlink:git-add[1].
		       ^^^
...are temporarily stored to a staging area called the "index" with...

(though maybe that's a little cumbersome).

Also, I don't think there's anything wrong with the verb "stage", but I
think it may be a little less commonly used (in this meaning) than the
term "staging area", so people might catch on faster if we started with
"staging area".

Re: Documentation/git-commit.txt

[J. Bruce Fields]

On Fri, Dec 08, 2006 at 08:25:24PM -0800, Junio C Hamano wrote:
> Hmmm.  I was merely trying to respond with recent requests on
> the list (might have been #git log) to make common usage
> examples more prominent.  While I feel that following the UNIXy
> manpage tradition to push examples down is the right thing to
> do, you and I are not the primary audience of Porcelain
> manpages, so...

I think manpages are primarily reference documents, so it's more
important to be able to get to the list of options without paging down
too far....

We could always say "see EXAMPLES below for more detail", or "see the
chapter 3 of the tutorial/user manual/whatever".

[PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Junio C Hamano]

Signed-off-by: Junio C Hamano <junkio@cox.net>
---

 * So how about this?

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

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 517a86b..8fe42cb 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -14,25 +14,47 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Updates the index file for given paths, or all modified files if
-'-a' is specified, and makes a commit object.  The command specified
-by either the VISUAL or EDITOR environment variables are used to edit
-the commit log message.
+Use 'git commit' when you want to record your changes into the repository
+along with a log message describing what the commit is about. All changes
+to be committed must be explicitly identified using one of the following
+methods:
 
-Several environment variable are used during commits.  They are
-documented in gitlink:git-commit-tree[1].
+1. by using gitlink:git-add[1] to incrementally "add" changes to the
+   next commit before using the 'commit' command (Note: even modified
+   files must be "added");
 
+2. by using gitlink:git-rm[1] to identify content removal for the next
+   commit, again before using the 'commit' command;
+
+3. by directly listing files containing changes to be committed as arguments
+   to the 'commit' command, in which cases only those files alone will be
+   considered for the commit;
+
+4. by using the -a switch with the 'commit' command to automatically "add"
+   changes from all known files i.e. files that have already been committed
+   before, and perform the actual commit.
+
+Note that the contents of the paths that resolved cleanly by a
+conflicted merge are automatically staged for the next commit;
+you still need to explicitly identify what you want in the
+resulting commit using one of the above methods before
+recording the merge commit.
+
+The gitlink:git-status[1] command can be used to obtain a
+summary of what is included by any of the above for the next
+commit by giving the same set of parameters you would give to
+this command.
+
+If you make a commit and then found a mistake immediately after
+that, you can recover from it with gitlink:git-reset[1].
 
-This command can run `commit-msg`, `pre-commit`, and
-`post-commit` hooks.  See link:hooks.html[hooks] for more
-information.
 
 OPTIONS
 -------
 -a|--all::
-	Update all paths in the index file.  This flag notices
-	files that have been modified and deleted, but new files
-	you have not told git about are not affected.
+	Tell the command to automatically stage files that have
+	been modified and deleted, but new files you have not
+	told git about are not affected.
 
 -c or -C <commit>::
 	Take existing commit object, and reuse the log message
@@ -55,16 +77,13 @@ OPTIONS
 -s|--signoff::
 	Add Signed-off-by line at the end of the commit message.
 
--v|--verify::
-	Look for suspicious lines the commit introduces, and
-	abort committing if there is one.  The definition of
-	'suspicious lines' is currently the lines that has
-	trailing whitespaces, and the lines whose indentation
-	has a SP character immediately followed by a TAB
-	character.  This is the default.
-
--n|--no-verify::
-	The opposite of `--verify`.
+--no-verify::
+	By default, the command looks for suspicious lines the
+	commit introduces, and aborts committing if there is one.
+	The definition of 'suspicious lines' is currently the
+	lines that has trailing whitespaces, and the lines whose
+	indentation has a SP character immediately followed by a
+	TAB character.  This option turns off the check.
 
 -e|--edit::
 	The message taken from file with `-F`, command line with
@@ -95,16 +114,16 @@ but can be used to amend a merge commit.
 --
 
 -i|--include::
-	Instead of committing only the files specified on the
-	command line, update them in the index file and then
-	commit the whole index.  This is the traditional
-	behavior.
+	Before making a commit out of staged contents so far,
+	stage the contents of paths given on the command line
+	as well.  This is usually not what you want unless you
+	are concluding a conflicted merge.
 
 -o|--only::
-	Commit only the files specified on the command line.
-	This format cannot be used during a merge, nor when the
-	index and the latest commit does not match on the
-	specified paths to avoid confusion.
+	Commit only the files specified on the command line;
+	this is the default when pathnames are given on the
+	command line, so you usually do not have to give this
+	option.  This format cannot be used during a merge.
 
 \--::
 	Do not interpret any more arguments as options.
@@ -114,50 +133,112 @@ but can be used to amend a merge commit.
 	different between `--include` and `--only`.  Without
 	either, it defaults `--only` semantics.
 
-If you make a commit and then found a mistake immediately after
-that, you can recover from it with gitlink:git-reset[1].
-
-
-Discussion
-----------
-
-`git commit` without _any_ parameter commits the tree structure
-recorded by the current index file.  This is a whole-tree commit
-even the command is invoked from a subdirectory.
-
-`git commit --include paths...` is equivalent to
-
-	git update-index --remove paths...
-	git commit
-
-That is, update the specified paths to the index and then commit
-the whole tree.
-
-`git commit paths...` largely bypasses the index file and
-commits only the changes made to the specified paths.  It has
-however several safety valves to prevent confusion.
-
-. It refuses to run during a merge (i.e. when
-  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
-  that the traditional semantics now needs -i flag.
-
-. It refuses to run if named `paths...` are different in HEAD
-  and the index (ditto about reminding).  Added paths are OK.
-  This is because an earlier `git diff` (not `git diff HEAD`)
-  would have shown the differences since the last `git
-  update-index paths...` to the user, and an inexperienced user
-  may mistakenly think that the changes between the index and
-  the HEAD (i.e. earlier changes made before the last `git
-  update-index paths...` was done) are not being committed.
-
-. It reads HEAD commit into a temporary index file, updates the
-  specified `paths...` and makes a commit.  At the same time,
-  the real index file is also updated with the same `paths...`.
-
-`git commit --all` updates the index file with _all_ changes to
-the working tree, and makes a whole-tree commit, regardless of
-which subdirectory the command is invoked in.
 
+EXAMPLES
+--------
+When recording your own work, the contents of modified files in
+your working tree are temporarily stored to a staging area
+called the "index" with gitlink:git-add[1].  Removal
+of a file is staged with gitlink:git-rm[1].  After building the
+state to be committed incrementally with these commands, `git
+commit` (without any pathname parameter) is used to record what
+has been staged so far.  This is the most basic form of the
+command.  An example:
+
+------------
+$ edit hello.c
+$ git rm goodbye.c
+$ git add hello.c
+$ git commit
+------------
+
+////////////
+We should fix 'git rm' to remove goodbye.c from both index and
+working tree for the above example.
+////////////
+
+Instead of staging files after each individual change, you can
+tell `git commit` to notice the changes to the tracked files in
+your working tree and do corresponding `git add` and `git rm`
+for you.  That is, this example does the same as the earlier
+example if there is no other change in your working tree:
+
+------------
+$ edit hello.c
+$ rm goodbye.c
+$ git commit -a
+------------
+
+The command `git commit -a` first looks at your working tree,
+notices that you have modified hello.c and removed goodbye.c,
+and performs necessary `git add` and `git rm` for you.
+
+After staging changes to many files, you can alter the order the
+changes are recorded in, by giving pathnames to `git commit`.
+When pathnames are given, the command makes a commit that
+only records the changes made to the named paths:
+
+------------
+$ edit hello.c hello.h
+$ git add hello.c hello.h
+$ edit Makefile
+$ git commit Makefile
+------------
+
+This makes a commit that records the modification to `Makefile`.
+The changes staged for `hello.c` and `hello.h` are not included
+in the resulting commit.  However, their changes are not lost --
+they are still staged and merely held back.  After the above
+sequence, if you do:
+
+------------
+$ git commit
+------------
+
+this second commit would record the changes to `hello.c` and
+`hello.h` as expected.
+
+After a merge (initiated by either gitlink:git-merge[1] or
+gitlink:git-pull[1]) stops because of conflicts, cleanly merged
+paths are already staged to be committed for you, and paths that
+conflicted are left in unmerged state.  You would have to first
+check which paths are conflicting with gitlink:git-status[1]
+and after fixing them manually in your working tree, you would
+stage the result as usual with gitlink:git-add[1]:
+
+------------
+$ git status | grep unmerged
+unmerged: hello.c
+$ edit hello.c
+$ git add hello.c
+------------
+
+After resolving conflicts and staging the result, `git ls-files -u`
+would stop mentioning the conflicted path.  When you are done,
+run `git commit` to finally record the merge:
+
+------------
+$ git commit
+------------
+
+As with the case to record your own changes, you can use `-a`
+option to save typing.  One difference is that during a merge
+resolution, you cannot use `git commit` with pathnames to
+alter the order the changes are committed, because the merge
+should be recorded as a single commit.  In fact, the command
+refuses to run when given pathnames (but see `-i` option).
+
+
+ENVIRONMENT VARIABLES
+---------------------
+The command specified by either the VISUAL or EDITOR environment
+variables is used to edit the commit log message.
+
+HOOKS
+-----
+This command can run `commit-msg`, `pre-commit`, and
+`post-commit` hooks.  See link:hooks.html[hooks] for more
+information.
 
 Author
 ------
-- 
1.4.4.2.g7d2d-dirty

Re: Documentation/git-commit.txt

[Nicolas Pitre]

On Fri, 8 Dec 2006, Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:
> 
> > Frankly I feel unconfortable with this.
> >
> > 1) too many examples.
> >
> > Yes, examples are good, but somehow there is something in the current 
> > text that make me feel they are not providing the clarification they 
> > should.  Dunno... I think I'd still push them after option list.
> 
> Hmmm.  I was merely trying to respond with recent requests on
> the list (might have been #git log) to make common usage
> examples more prominent.  While I feel that following the UNIXy
> manpage tradition to push examples down is the right thing to
> do, you and I are not the primary audience of Porcelain
> manpages, so...

Sure, but sometimes too much is just as bad as not enough.  And given 
the amount of text in your version I feel the essence of the information 
gets dilluted too much.

> > 2) explanation of how to resolve and commit a conflicting merge should 
> >    really be found in git-merge.txt not in git-commit.txt.
> >
> > It feels a bit awkward to suddenly start talking about git ls-files and 
> > merge here.
> 
> I agree that it looks a bit out of place; the primary reason I
> talked about the merge was to make it clear that a conflicted
> merge will still stage the changes for cleanly auto-resolved
> paths.  In other words, it makes me feel uneasy that there is no
> mention of it in the list in your version that follows this
> sentence:
> 
> > +... All changes
> > +to be committed must be explicitly identified using one of the following
> > +methods:
> 
> It would make me happier if you had, at the end of enumeration,
> something like:
> 
> 	Note that the contents of the paths that resolved
>         cleanly by a conflicted merge are automatically staged
>         for the next commit; you still need to explicitly
>         identify what you want in the resulting commit using one
>         of the above methods before concluding the merge.

But why couldn't this be in the git-merge man page instead?  That is 
precisely the sort of addition that makes me feel like we're trying to 
say too much at the same time.  When in the context of learning how 
"commit" works, it is certainly not necessary to talk about how "merge" 
works.  That should really be mentioned in the "merging" documentation 
(with a link to git-commit for more options on commit).

> Another reason I described the merge workflow is it would become
> much less clear why --only is useless in merge situation if the
> reader does not know that a conflicted merge stages the
> auto-resolved changes.

Sure, but the whole merge concept might still not make any sense at the 
moment the user is learning about commit.  In other words, the "commit" 
documentation must not depend on the "merge" concept.  It should rather 
be the other way around, i.e. the "merge" documentation can easily 
depend on the "commit" documentation.

Just like I carefully avoided talking about "commit -a" in the git-add 
man page to avoid circular conceptual dependencies.  But obviously the 
git-commit man page must talk about the "add" concept.

This way you get a progressive knowledge base with git-add which pretty 
much stands on its own, then you move to git-commit that depends on 
git-add, then you move to merging and resolving conflicts that depend on 
git-commit.  And so without being distracted by concepts you don't need 
to know just yet along the way.

Re: Documentation/git-commit.txt

[Jakub Narebski]

Nicolas Pitre wrote:

> On Fri, 8 Dec 2006, Junio C Hamano wrote:
[...]
>> Another reason I described the merge workflow is it would become
>> much less clear why --only is useless in merge situation if the
>> reader does not know that a conflicted merge stages the
>> auto-resolved changes.
> 
> Sure, but the whole merge concept might still not make any sense at the 
> moment the user is learning about commit.  In other words, the "commit" 
> documentation must not depend on the "merge" concept.  It should rather 
> be the other way around, i.e. the "merge" documentation can easily 
> depend on the "commit" documentation.
> 
> Just like I carefully avoided talking about "commit -a" in the git-add 
> man page to avoid circular conceptual dependencies.  But obviously the 
> git-commit man page must talk about the "add" concept.
> 
> This way you get a progressive knowledge base with git-add which pretty 
> much stands on its own, then you move to git-commit that depends on 
> git-add, then you move to merging and resolving conflicts that depend on 
> git-commit.  And so without being distracted by concepts you don't need 
> to know just yet along the way.

IMVHO for reference documentation (and manpages for commands are such
documentation) it is more important to be complete, than to be
self-contained and without circular conceptual dependencies. The latter
(and defining things before using it) is more important for things like
tutorial or quickstart.

If one is not doing merge then one can skip the talk about merges. If one
git-commit complains about using --only (because of merge), one would
rather search for information in git-commit(1), not git-merge(1) or
git-pull(1); well, the merge might be result of git-checkout -m.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Nicolas Pitre]

On Fri, 8 Dec 2006, Junio C Hamano wrote:

> 
> Signed-off-by: Junio C Hamano <junkio@cox.net>
> ---
> 
>  * So how about this?

Much better.  Comments below.

> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 517a86b..8fe42cb 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -14,25 +14,47 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Updates the index file for given paths, or all modified files if
> -'-a' is specified, and makes a commit object.  The command specified
> -by either the VISUAL or EDITOR environment variables are used to edit
> -the commit log message.
> +Use 'git commit' when you want to record your changes into the repository
> +along with a log message describing what the commit is about. All changes
> +to be committed must be explicitly identified using one of the following
> +methods:
>  
> -Several environment variable are used during commits.  They are
> -documented in gitlink:git-commit-tree[1].
> +1. by using gitlink:git-add[1] to incrementally "add" changes to the
> +   next commit before using the 'commit' command (Note: even modified
> +   files must be "added");
>  
> +2. by using gitlink:git-rm[1] to identify content removal for the next
> +   commit, again before using the 'commit' command;
> +
> +3. by directly listing files containing changes to be committed as arguments
> +   to the 'commit' command, in which cases only those files alone will be
> +   considered for the commit;
> +
> +4. by using the -a switch with the 'commit' command to automatically "add"
> +   changes from all known files i.e. files that have already been committed
> +   before, and perform the actual commit.
> +
> +Note that the contents of the paths that resolved cleanly by a
> +conflicted merge are automatically staged for the next commit;
> +you still need to explicitly identify what you want in the
> +resulting commit using one of the above methods before
> +recording the merge commit.

Like I said in another mail, I really think this formal paragraph 
belongs elsewhere. But if you insist for keeping it here, at least it 
should be moved after mention of git-reset below.  But IMHO the merge 
example included further down should be sufficient information wrt 
committing a merge.

> +
> +The gitlink:git-status[1] command can be used to obtain a
> +summary of what is included by any of the above for the next
> +commit by giving the same set of parameters you would give to
> +this command.
> +
> +If you make a commit and then found a mistake immediately after
> +that, you can recover from it with gitlink:git-reset[1].
>  
> -This command can run `commit-msg`, `pre-commit`, and
> -`post-commit` hooks.  See link:hooks.html[hooks] for more
> -information.
>  
>  OPTIONS
>  -------
>  -a|--all::
> -	Update all paths in the index file.  This flag notices
> -	files that have been modified and deleted, but new files
> -	you have not told git about are not affected.
> +	Tell the command to automatically stage files that have
> +	been modified and deleted, but new files you have not
> +	told git about are not affected.
>  
>  -c or -C <commit>::
>  	Take existing commit object, and reuse the log message
> @@ -55,16 +77,13 @@ OPTIONS
>  -s|--signoff::
>  	Add Signed-off-by line at the end of the commit message.
>  
> --v|--verify::
> -	Look for suspicious lines the commit introduces, and
> -	abort committing if there is one.  The definition of
> -	'suspicious lines' is currently the lines that has
> -	trailing whitespaces, and the lines whose indentation
> -	has a SP character immediately followed by a TAB
> -	character.  This is the default.
> -
> --n|--no-verify::
> -	The opposite of `--verify`.
> +--no-verify::
> +	By default, the command looks for suspicious lines the
> +	commit introduces, and aborts committing if there is one.
> +	The definition of 'suspicious lines' is currently the
> +	lines that has trailing whitespaces, and the lines whose
> +	indentation has a SP character immediately followed by a
> +	TAB character.  This option turns off the check.
>  
>  -e|--edit::
>  	The message taken from file with `-F`, command line with
> @@ -95,16 +114,16 @@ but can be used to amend a merge commit.
>  --
>  
>  -i|--include::
> -	Instead of committing only the files specified on the
> -	command line, update them in the index file and then
> -	commit the whole index.  This is the traditional
> -	behavior.
> +	Before making a commit out of staged contents so far,
> +	stage the contents of paths given on the command line
> +	as well.  This is usually not what you want unless you
> +	are concluding a conflicted merge.
>  
>  -o|--only::
> -	Commit only the files specified on the command line.
> -	This format cannot be used during a merge, nor when the
> -	index and the latest commit does not match on the
> -	specified paths to avoid confusion.
> +	Commit only the files specified on the command line;
> +	this is the default when pathnames are given on the
> +	command line, so you usually do not have to give this
> +	option.  This format cannot be used during a merge.

Is there some value in keeping this option documented?  What about 
removing it (the documentation not the option)?

>  \--::
>  	Do not interpret any more arguments as options.
> @@ -114,50 +133,112 @@ but can be used to amend a merge commit.
>  	different between `--include` and `--only`.  Without
>  	either, it defaults `--only` semantics.
>  
> -If you make a commit and then found a mistake immediately after
> -that, you can recover from it with gitlink:git-reset[1].
> -
> -
> -Discussion
> -----------
> -
> -`git commit` without _any_ parameter commits the tree structure
> -recorded by the current index file.  This is a whole-tree commit
> -even the command is invoked from a subdirectory.
> -
> -`git commit --include paths...` is equivalent to
> -
> -	git update-index --remove paths...
> -	git commit
> -
> -That is, update the specified paths to the index and then commit
> -the whole tree.
> -
> -`git commit paths...` largely bypasses the index file and
> -commits only the changes made to the specified paths.  It has
> -however several safety valves to prevent confusion.
> -
> -. It refuses to run during a merge (i.e. when
> -  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
> -  that the traditional semantics now needs -i flag.
> -
> -. It refuses to run if named `paths...` are different in HEAD
> -  and the index (ditto about reminding).  Added paths are OK.
> -  This is because an earlier `git diff` (not `git diff HEAD`)
> -  would have shown the differences since the last `git
> -  update-index paths...` to the user, and an inexperienced user
> -  may mistakenly think that the changes between the index and
> -  the HEAD (i.e. earlier changes made before the last `git
> -  update-index paths...` was done) are not being committed.
> -
> -. It reads HEAD commit into a temporary index file, updates the
> -  specified `paths...` and makes a commit.  At the same time,
> -  the real index file is also updated with the same `paths...`.
> -
> -`git commit --all` updates the index file with _all_ changes to
> -the working tree, and makes a whole-tree commit, regardless of
> -which subdirectory the command is invoked in.
>  
> +EXAMPLES
> +--------
> +When recording your own work, the contents of modified files in
> +your working tree are temporarily stored to a staging area
> +called the "index" with gitlink:git-add[1].  Removal

I like the way the index is introduced at this point.

> +of a file is staged with gitlink:git-rm[1].  After building the
> +state to be committed incrementally with these commands, `git
> +commit` (without any pathname parameter) is used to record what
> +has been staged so far.  This is the most basic form of the
> +command.  An example:
> +
> +------------
> +$ edit hello.c
> +$ git rm goodbye.c
> +$ git add hello.c
> +$ git commit
> +------------
> +
> +////////////
> +We should fix 'git rm' to remove goodbye.c from both index and
> +working tree for the above example.
> +////////////
> +
> +Instead of staging files after each individual change, you can
> +tell `git commit` to notice the changes to the tracked files in
> +your working tree and do corresponding `git add` and `git rm`
> +for you.  That is, this example does the same as the earlier
> +example if there is no other change in your working tree:
> +
> +------------
> +$ edit hello.c
> +$ rm goodbye.c
> +$ git commit -a
> +------------
> +
> +The command `git commit -a` first looks at your working tree,
> +notices that you have modified hello.c and removed goodbye.c,
> +and performs necessary `git add` and `git rm` for you.
> +
> +After staging changes to many files, you can alter the order the
> +changes are recorded in, by giving pathnames to `git commit`.
> +When pathnames are given, the command makes a commit that
> +only records the changes made to the named paths:
> +
> +------------
> +$ edit hello.c hello.h
> +$ git add hello.c hello.h
> +$ edit Makefile
> +$ git commit Makefile
> +------------
> +
> +This makes a commit that records the modification to `Makefile`.
> +The changes staged for `hello.c` and `hello.h` are not included
> +in the resulting commit.  However, their changes are not lost --
> +they are still staged and merely held back.  After the above
> +sequence, if you do:
> +
> +------------
> +$ git commit
> +------------
> +
> +this second commit would record the changes to `hello.c` and
> +`hello.h` as expected.
> +
> +After a merge (initiated by either gitlink:git-merge[1] or
> +gitlink:git-pull[1]) stops because of conflicts, cleanly merged
> +paths are already staged to be committed for you, and paths that
> +conflicted are left in unmerged state.  You would have to first
> +check which paths are conflicting with gitlink:git-status[1]
> +and after fixing them manually in your working tree, you would
> +stage the result as usual with gitlink:git-add[1]:
> +
> +------------
> +$ git status | grep unmerged
> +unmerged: hello.c
> +$ edit hello.c
> +$ git add hello.c
> +------------
> +
> +After resolving conflicts and staging the result, `git ls-files -u`
> +would stop mentioning the conflicted path.  When you are done,
> +run `git commit` to finally record the merge:
> +
> +------------
> +$ git commit
> +------------
> +
> +As with the case to record your own changes, you can use `-a`
> +option to save typing.  One difference is that during a merge
> +resolution, you cannot use `git commit` with pathnames to
> +alter the order the changes are committed, because the merge
> +should be recorded as a single commit.  In fact, the command
> +refuses to run when given pathnames (but see `-i` option).
> +
> +
> +ENVIRONMENT VARIABLES
> +---------------------
> +The command specified by either the VISUAL or EDITOR environment
> +variables is used to edit the commit log message.
> +
> +HOOKS
> +-----
> +This command can run `commit-msg`, `pre-commit`, and
> +`post-commit` hooks.  See link:hooks.html[hooks] for more
> +information.

I'd add (with links):

SEE ALSO
--------
git-add, git-rm, git-mv, git-merge, git-commit-tree

Otherwise very good.

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

>> +Note that the contents of the paths that resolved cleanly by a
>> +conflicted merge are automatically staged for the next commit;
>> +you still need to explicitly identify what you want in the
>> +resulting commit using one of the above methods before
>> +recording the merge commit.
>
> Like I said in another mail,...IMHO the merge 
> example included further down should be sufficient information wrt 
> committing a merge.

You are right --- removed.

>>  -o|--only::
>> -	Commit only the files specified on the command line.
>> -	This format cannot be used during a merge, nor when the
>> -	index and the latest commit does not match on the
>> -	specified paths to avoid confusion.
>> +	Commit only the files specified on the command line;
>> +	this is the default when pathnames are given on the
>> +	command line, so you usually do not have to give this
>> +	option.  This format cannot be used during a merge.
>
> Is there some value in keeping this option documented?  What about 
> removing it (the documentation not the option)?

True, although the description of <files>... need to be
clarified if we do this.

>> +When recording your own work, the contents of modified files in
>> +your working tree are temporarily stored to a staging area
>> +called the "index" with gitlink:git-add[1].  Removal
>
> I like the way the index is introduced at this point.

Credit owed to JBF.

> I'd add (with links):
>
> SEE ALSO
> --------
> git-add, git-rm, git-mv, git-merge, git-commit-tree

Done.

Attached is an incremental patch on top of what you commented
on.

-- >8 --

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 8fe42cb..20a2cb3 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -34,12 +34,6 @@ methods:
    changes from all known files i.e. files that have already been committed
    before, and perform the actual commit.
 
-Note that the contents of the paths that resolved cleanly by a
-conflicted merge are automatically staged for the next commit;
-you still need to explicitly identify what you want in the
-resulting commit using one of the above methods before
-recording the merge commit.
-
 The gitlink:git-status[1] command can be used to obtain a
 summary of what is included by any of the above for the next
 commit by giving the same set of parameters you would give to
@@ -119,19 +113,15 @@ but can be used to amend a merge commit.
 	as well.  This is usually not what you want unless you
 	are concluding a conflicted merge.
 
--o|--only::
-	Commit only the files specified on the command line;
-	this is the default when pathnames are given on the
-	command line, so you usually do not have to give this
-	option.  This format cannot be used during a merge.
-
 \--::
 	Do not interpret any more arguments as options.
 
 <file>...::
-	Files to be committed.  The meaning of these is
-	different between `--include` and `--only`.  Without
-	either, it defaults `--only` semantics.
+	When files are given on the command line, the command
+	commits the contents of the named files, without
+	recording the changes already staged.  The contents of
+	these files are also staged for the next commit on top
+	of what have been staged before.
 
 
 EXAMPLES
@@ -240,6 +230,15 @@ This command can run `commit-msg`, `pre-commit`, and
 `post-commit` hooks.  See link:hooks.html[hooks] for more
 information.
 
+
+SEE ALSO
+--------
+gitlink:git-add[1],
+gitlink:git-rm[1],
+gitlink:git-mv[1],
+gitlink:git-merge[1],
+gitlink:git-commit-tree[1]
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Jakub Narebski]

Junio C Hamano wrote:

> Nicolas Pitre <nico@cam.org> writes:

>>>  -o|--only::
>>> -   Commit only the files specified on the command line.
>>> -   This format cannot be used during a merge, nor when the
>>> -   index and the latest commit does not match on the
>>> -   specified paths to avoid confusion.
>>> +   Commit only the files specified on the command line;
>>> +   this is the default when pathnames are given on the
>>> +   command line, so you usually do not have to give this
>>> +   option.  This format cannot be used during a merge.
>>
>> Is there some value in keeping this option documented?  What about 
>> removing it (the documentation not the option)?
> 
> True, although the description of <files>... need to be
> clarified if we do this.

I'm a bit uncomfortable about removing documentation to existing
(if no-op) option. I'd rather it stay.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Linus Torvalds]

On Sat, 9 Dec 2006, Jakub Narebski wrote:
> 
> I'm a bit uncomfortable about removing documentation to existing
> (if no-op) option. I'd rather it stay.

How about mentioning it at the very end, under a "HYSTERICAL RAISINS" 
header. That way it's documented, and people still know to ignore it.

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Jakub Narebski]

Linus Torvalds wrote:
> 
> On Sat, 9 Dec 2006, Jakub Narebski wrote:
>> 
>> I'm a bit uncomfortable about removing documentation to existing
>> (if no-op) option. I'd rather it stay.
> 
> How about mentioning it at the very end, under a "HYSTERICAL RAISINS" 
> header. That way it's documented, and people still know to ignore it.

"HISTORICAL NOTES". Yes, that is good idea.

Although for git-commit the option --only helps to explain what 
"git commit <path>..." does. So perhaps it should stay where it was.
-- 
Jakub Narebski

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Nicolas Pitre]

On Sat, 9 Dec 2006, Junio C Hamano wrote:

> Attached is an incremental patch on top of what you commented
> on.
> 
[...]
>  <file>...::
> -	Files to be committed.  The meaning of these is
> -	different between `--include` and `--only`.  Without
> -	either, it defaults `--only` semantics.
> +	When files are given on the command line, the command
> +	commits the contents of the named files, without
> +	recording the changes already staged.  The contents of
> +	these files are also staged for the next commit on top
> +	of what have been staged before.

Might something like "When -i is provided however..." be missing in the 
above?  Otherwise it is rather confusing.

Besides that I'm really happy with the result.

Re: Documentation/git-commit.txt

[Horst H. von Brand]

Alan Chandler <alan@chandlerfamily.org.uk> wrote:

[...]

> How about the following wording here
> 
> Instead of staging the content of each file immediately after changing 
> it, you can wait until you have completed all the changes you want to 
> make and then use the `-a` option to tell `git commit` to look for all 
> changes to the content it is tracking and commit it automatically. That 
                 ^^^^^^^
                 files
                 (or "files whose contents")

> is, this example ...

[Yes, git tracks the contents of files, but it also has a list of files
 whose contents it is tracking]
-- 
Dr. Horst H. von Brand                   User #22616 counter.li.org
Departamento de Informatica                    Fono: +56 32 2654431
Universidad Tecnica Federico Santa Maria             +56 32 2654239

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Josef Weidendorfer]

Very nice.

On Saturday 09 December 2006 06:48, Junio C Hamano wrote:
>  DESCRIPTION
>  -----------
> -Updates the index file for given paths, or all modified files if
> -'-a' is specified, and makes a commit object.  The command specified
> -by either the VISUAL or EDITOR environment variables are used to edit
> -the commit log message.
> +Use 'git commit' when you want to record your changes into the repository
> +along with a log message describing what the commit is about. All changes
> +to be committed must be explicitly identified using one of the following

What about: "... must be explicitly identified (that is,
must be "staged") ..."

This way, it will be clear for the reader that "to explicitly identify" is the
same thing as "to stage", which is used quite often later.

> +methods:
>  
> -Several environment variable are used during commits.  They are
> -documented in gitlink:git-commit-tree[1].
> +1. by using gitlink:git-add[1] to incrementally "add" changes to the
> +   next commit before using the 'commit' command (Note: even modified
> +   files must be "added");

Regarding this note: Of course unmodified files do not have to be added ;-)

What about: "(Note: changes in files already known to git, and even new
changes done after a previous `git add` for a given file, still must
be staged again)" 

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Nicolas Pitre]

On Sun, 10 Dec 2006, Josef Weidendorfer wrote:

> Very nice.
> 
> On Saturday 09 December 2006 06:48, Junio C Hamano wrote:
> >  DESCRIPTION
> >  -----------
> > -Updates the index file for given paths, or all modified files if
> > -'-a' is specified, and makes a commit object.  The command specified
> > -by either the VISUAL or EDITOR environment variables are used to edit
> > -the commit log message.
> > +Use 'git commit' when you want to record your changes into the repository
> > +along with a log message describing what the commit is about. All changes
> > +to be committed must be explicitly identified using one of the following
> 
> What about: "... must be explicitly identified (that is,
> must be "staged") ..."
> 
> This way, it will be clear for the reader that "to explicitly identify" is the
> same thing as "to stage", which is used quite often later.

Hmmm, maybe, maybe not.  Although I don't have particular problem with 
"staging area", I'm still unconvinced about the verb "stage".

> > +methods:
> >  
> > -Several environment variable are used during commits.  They are
> > -documented in gitlink:git-commit-tree[1].
> > +1. by using gitlink:git-add[1] to incrementally "add" changes to the
> > +   next commit before using the 'commit' command (Note: even modified
> > +   files must be "added");
> 
> Regarding this note: Of course unmodified files do not have to be added ;-)
> 
> What about: "(Note: changes in files already known to git, and even new
> changes done after a previous `git add` for a given file, still must
> be staged again)" 

This is getting too long for what it is worth in this case IMHO.

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Alan Chandler]

On Saturday 09 December 2006 05:48, Junio C Hamano wrote:

>  OPTIONS
>  -------
>  -a|--all::
> -	Update all paths in the index file.  This flag notices
> -	files that have been modified and deleted, but new files
> -	you have not told git about are not affected.
> +	Tell the command to automatically stage files that have
> +	been modified and deleted, but new files you have not
> +	told git about are not affected.

The "but" in this sentence doesn't seem right to me, I would either 
use "although", or slightly better (IMHO) make it two sentences

Tell the command to automatically stage files that have been modified 
and deleted.  Note that files that you have not told git about are not 
included with this option.

-- 
Alan Chandler

Re: Documentation/git-commit.txt

[Alan Chandler]

On Sunday 10 December 2006 00:11, Horst H. von Brand wrote:
> Alan Chandler <alan@chandlerfamily.org.uk> wrote:
>
> [...]
>
> > How about the following wording here
> >
> > Instead of staging the content of each file immediately after
> > changing it, you can wait until you have completed all the changes
> > you want to make and then use the `-a` option to tell `git commit`
> > to look for all changes to the content it is tracking and commit it
> > automatically. That
>
>                  ^^^^^^^
>                  files
>                  (or "files whose contents")
>
> > is, this example ...
>
> [Yes, git tracks the contents of files, but it also has a list of
> files whose contents it is tracking]

regardless, I think "it" should become "them"

... it is tracking and commit them automatically. 



-- 
Alan Chandler

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[J. Bruce Fields]

On Sun, Dec 10, 2006 at 01:30:47AM +0100, Josef Weidendorfer wrote:
> On Saturday 09 December 2006 06:48, Junio C Hamano wrote:
> > +1. by using gitlink:git-add[1] to incrementally "add" changes to the
> > +   next commit before using the 'commit' command (Note: even modified
> > +   files must be "added");
> 
> Regarding this note: Of course unmodified files do not have to be added ;-)
> 
> What about: "(Note: changes in files already known to git, and even new
> changes done after a previous `git add` for a given file, still must
> be staged again)" 

Or maybe: "by using gitlink:git-add[1] to add new content (of either new
or newly modified files) to the next commit."

Man pages are reference documentation, so I figure it's OK to sacrifice
a little newbie-friendliness for accuracy and concision.

I dunno, I think basically the right content is there and Junio should
just commit it (after the git-rm change?), and then allow the rest of us
nitpickers to submit patches against the result to our heart's
content....

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Nicolas Pitre]

On Sun, 10 Dec 2006, J. Bruce Fields wrote:

> Or maybe: "by using gitlink:git-add[1] to add new content (of either new
> or newly modified files) to the next commit."
> 
> Man pages are reference documentation, so I figure it's OK to sacrifice
> a little newbie-friendliness for accuracy and concision.

I disagree.  Clarity should be the first goal.  And the fact that even 
modified files have to be specified is something worth enphasizing, 
especially since this is not something other systems do.

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[J. Bruce Fields]

On Sun, Dec 10, 2006 at 05:07:40PM -0500, Nicolas Pitre wrote:
> On Sun, 10 Dec 2006, J. Bruce Fields wrote:
> 
> > Or maybe: "by using gitlink:git-add[1] to add new content (of either new
> > or newly modified files) to the next commit."
> > 
> > Man pages are reference documentation, so I figure it's OK to sacrifice
> > a little newbie-friendliness for accuracy and concision.
> 
> I disagree.  Clarity should be the first goal.  And the fact that even 
> modified files have to be specified is something worth enphasizing, 
> especially since this is not something other systems do.

OK, OK.  Shortest I can manage then is:

	by using gitlink:git-add[1] to add new or modified files to the
	next commit.  This adds a file's current contents only; run
	gitlink:git-add[1] again to include any subsequent changes.

which may not be any improvement.

Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Junio C Hamano]

Nicolas Pitre <nico@cam.org> writes:

>> Man pages are reference documentation, so I figure it's OK to sacrifice
>> a little newbie-friendliness for accuracy and concision.
>
> I disagree.  Clarity should be the first goal.  And the fact that even 
> modified files have to be specified is something worth enphasizing, 
> especially since this is not something other systems do.

Let's keep plumbing documentation technical reference material,
but allow more newbie friendliness in Porcelain-ish
documentation.

Re: Documentation/git-commit.txt

[Andreas Ericsson]

Alan Chandler wrote:
> On Sunday 10 December 2006 00:11, Horst H. von Brand wrote:
>> Alan Chandler <alan@chandlerfamily.org.uk> wrote:
>>
>> [...]
>>
>>> How about the following wording here
>>>
>>> Instead of staging the content of each file immediately after
>>> changing it, you can wait until you have completed all the changes
>>> you want to make and then use the `-a` option to tell `git commit`
>>> to look for all changes to the content it is tracking and commit it
>>> automatically. That
>>                  ^^^^^^^
>>                  files
>>                  (or "files whose contents")
>>
>>> is, this example ...
>> [Yes, git tracks the contents of files, but it also has a list of
>> files whose contents it is tracking]
> 
> regardless, I think "it" should become "them"
> 
> ... it is tracking and commit them automatically. 
> 

Works wonderfully, as the syntactically anal will notice that "them" 
refers to "the changes" while newbies glossing over the docs will think 
of "them" as "the files" (which is technically incorrect but amounts to 
the same thing from that same newbies perspective).

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se