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

[hgbook-git] / tour.mdwn

diff --git a/tour.mdwn b/tour.mdwn
index b5bbe6e71fc4be16b57e06b422da2b64d883043c..19b00613c3850b505220dd68845eba46fe0bef46 100644 (file)
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -3,9 +3,9 @@ A tour of git: the basics
 
 ### 2.0 Copyright
 
 
 ### 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.
 <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
 
     * 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
 ### 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
 
 
   * Ubuntu
 

-       apt-get install git
+       apt-get install git-core

 
 #### 2.1.2  Mac OS X
 
 
 #### 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
 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
 
 
 ### 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.
 
 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/
 
        $ 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
 
 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
 
 
 #### 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.
 
 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
 
 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
 
 
        $ 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 “#”.
 
 The editor that the “git commit” command drops us into will contain an
 empty line, followed by a number of lines starting with “#”.


@@ -1000,6 +1021,22 @@ the common case for the upstream-tracking scenario), then "git pull"
 with no explicit repository is suffcient, and it will default to
 pulling from the same repository as the original clone.
 
 with no explicit repository is suffcient, and it will default to
 pulling from the same repository as the original clone.
 

+[XXX: The structure of the preceding section follows that of the
+original hgbook. But an alternate structure that arranged to pull from
+the originally cloned repository (as would be common) would allow for
+more straightforward use of git's features. For example, instead of
+the silly FETCH_HEAD stuff it would allow for "git fetch" and "git log
+master..origin" to be a very nice replacement for "hg
+incoming". Similarly, below, "git log origin..master" would make a
+nice replacement for "hg outgoing" which is something I didn't offer
+at all. One could also use git's remotes with the myriad repositories
+as used here, but it would require doing things like "git remote add
+<some-name> ../hello-pull" and that seems like a bit much to introduce
+for a turorial of this level. If nothing else, if the above section
+seems a little intimidating, understand that it's because things are
+not presented in the most natural "git way", (and I'm a little too
+tired to fix it tonight).]
+

 #### 2.8.2  Checking out previous revisions
 
 If any users of mercurial are reading this, they might wonder if
 #### 2.8.2  Checking out previous revisions
 
 If any users of mercurial are reading this, they might wonder if