Make it more clear that the git-clone example is intended to actually be performed

[hgbook-git] / tour.mdwn

diff --git a/tour.mdwn b/tour.mdwn
index b5bbe6e71fc4be16b57e06b422da2b64d883043c..e302d61775e31d7decf5101179386ad1f154b91c 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

 
 

-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.
+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).
+
+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


@@ -1000,6 +1015,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