Justify 'git commit -a' by comparing it to 'git add <files>'

This is better than comparing it to 'git add <files>; git commit'
which forces potentially unfamiliar index notions on the poor
user.

diff --git a/tour.mdwn b/tour.mdwn
index e302d61775e31d7decf5101179386ad1f154b91c..19b00613c3850b505220dd68845eba46fe0bef46 100644 (file)
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -724,12 +724,18 @@ after we’ve finished committing.
 
        $ git commit -a
 
-Note: The -a on the command-line instructs git to commit all changes
-to tracked files. Without this, "git commit" will only commit changes
-that have been previously staged for committing with "git add
-file". The most common usage is to commit with "git commit -a" and
-only use "git add file; git commit" when there is a need to commit
-only some subset of changes that have been made.
+Note: The -a on the command-line instructs git to commit the new
+content of *all* tracked files that have been modified. This is a
+convenience over explicitly listing filenames to be committed on the
+"git commit" command line. It is useful to use "git commit <files>"
+when there is a need to commit only some subset of the files that have
+been modified.
+
+If new files need to be committed for the first time, just use "git
+add <file>" before "git commit -a". If a file needs to be removed,
+just remove it as normal before committing and "git commit -a" will
+notice that---it does not need to be explicitly told about the
+removal.
 
 The editor that the “git commit” command drops us into will contain an
 empty line, followed by a number of lines starting with “#”.