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

[hgbook-git] / tour.mdwn

diff --git a/tour.mdwn b/tour.mdwn
index 3ba6af94849ea8ce77cecf54b1a18b25ec8e5847..19b00613c3850b505220dd68845eba46fe0bef46 100644 (file)
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -3,9 +3,9 @@ A tour of git: the basics
 
 ### 2.0 Copyright
 
-This document is a modified version originally known as "Distributed
-revision control with Mercurial" and originally authored by Bryan
-O’Sullivan. The original document was obtained from
+This document is a modified version of a document originally titled
+"Distributed revision control with Mercurial" and originally authored
+by Bryan O’Sullivan. The original document was obtained from
 <http://hgbook.red-bean.com/>.
 
 Copyright © 2006, 2007 Bryan O’Sullivan.
@@ -29,6 +29,16 @@ Changes made by Carl include the following:
     * Eliminate line numbers from examples
     * Modified to describe git instead of mercurial
 
+The source of this modified version can be obtained via git:
+
+       git clone git://cworth.org/git/hgbook-git
+
+or
+
+       git clone http://cworth.org/git/hgbook-git
+
+and can be [browsed online](http://git.cworth.org/git/hgbook-git)
+
 ### 2.1  Installing git on your system
 
 Prebuilt binary packages of git are available for many popular
@@ -68,7 +78,7 @@ with git, meaning GNU Interactive Tools).
 
   * Ubuntu
 
-       apt-get install git
+       apt-get install git-core
 
 #### 2.1.2  Mac OS X
 
@@ -90,7 +100,7 @@ installers. These include GitMe, a package to install the entire
 development environment necessary to work on improving the msysgit
 port of git, and WinGit, a package for installing just git itself
 without the development environment, (still in Alpha as of September
-2008).
+2007).
 
 ### 2.2  Getting started
 
@@ -136,13 +146,18 @@ a directory tree in your filesystem that git treats as
 special. You can rename or delete a repository any time you like,
 using either the command line or your file browser.
 
-#### 2.3.1  Making a local copy of a repository
+#### 2.3.1  Creating a local copy of a remote repository
+
+As suggested, a repository can be copied through normal file-copying
+commands. But git also provides a "git clone" tool for copying a
+repository. This provides a means of copying a repository over the
+network, and is also useful with a local repository since it is much
+more efficient than creating a normal copy, (creating a local clones
+is blazingly fast).
 
-Copying a repository is just a little bit special. While you could use
-a normal file copying command to make a copy of a repository, it’s
-best to use a built-in command that git provides. This command
-is called “git clone”, because it creates an identical copy of an
-existing repository.
+We've assembled a simple repository that will be used in the examples
+throughout this chapter. Go ahead and clone this repository now so
+that you will be able to follow along:
 
        $ git clone git://cworth.org/git/hello
        Initialized empty Git repository in /tmp/hello/.git/
@@ -329,7 +344,7 @@ in the current branch, "HEAD~", refers to the previous commit, and
 
 Another useful syntax is .. which can be used to specify a range of
 commits. So "origin..master" specifies everything that has been
-committed to master since it derived from origin.
+committed to master since it diverged from origin.
 
 #### 2.4.3  Viewing specific revisions
 
@@ -385,7 +400,7 @@ created:
 Another useful option is -n or --max-count which, unsurprisingly,
 limits the maximum number of commits to be displayed.
 
-#### 2.4.3  More detailed information
+#### 2.4.5  More detailed information
 
 While the default information printed by “git log” is useful if you
 already know what you’re looking for, you may need to see more details
@@ -709,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 “#”.