From 8e13f52070413da5f8f46c36f8d5a4e5e1d3e5a9 Mon Sep 17 00:00:00 2001
From: Carl Worth <cworth@cworth.org>
Date: Fri, 28 Sep 2007 09:11:25 -0700
Subject: [PATCH] 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.
---
 tour.mdwn | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/tour.mdwn b/tour.mdwn
index e302d61..19b0061 100644
--- 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 “#”.
-- 
2.45.2