Fix typo: wihch -> which

[hgbook-git] / tour.mdwn

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


@@ -361,7 +376,7 @@ case):
 
 Besides filtering by commit identifiers, git allows you to easily
 filter the log output according to which files (or directories) are
 
 Besides filtering by commit identifiers, git allows you to easily
 filter the log output according to which files (or directories) are

-modified by listing them after "--" wihch is necessary to distinguish
+modified by listing them after "--" which is necessary to distinguish

 commit names from file names:
 
        $ git log -- Makefile
 commit names from file names:
 
        $ git log -- Makefile


@@ -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,21 +1021,37 @@ 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.
 

-#### 2.8.2  Checking out previous revisions
+[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).]
+
+Note: Mercurial users who are reading this might wonder if there's a
+need for the equivalent of "hg update" after doing a "git pull". And
+the answer is no. Unlike mercurial, "git pull" and "git merge" will
+automatically update the workind-directory files as necessary.

 
 

-If any users of mercurial are reading this, they might wonder if
-there's a need for the equivalent of "hg update" after doing a "git
-pull". And the answer is no. Unlike mercurial, "git pull" and "git
-merge" will automatically update the workind-directory files as
-necessary.
+#### 2.8.2  Checking out previous revisions

 
 

-But there's another function provided by "hg update" which is to
-update the working-directory files to a particular revision. In git,
-this functionality is provided by the "git checkout" command. To
-checkout a particular branch, tag, or an arbitrary revions, simply
-give the appropriate name to the "git checkout" command. For example,
-to examine the files as they existed before the original typo
-introduction, we could do:
+It's often useful to examine the working-tree state of some specific
+revision other than the tip of some branch. For example, maybe you
+would like to build a particular tagged version, or maybe you'd like
+to test the behavior of the code before a particular change was
+introduced. To do this, use "git checkout" and pass it the name of any
+revision, (with a branch name, a tag name, or any other commit
+identifier). For example, to examine our project before the original
+typo was introduced:

 
        $ git checkout 0a633bf5
        Note: moving to "0a633bf5" which isn't a local branch
 
        $ git checkout 0a633bf5
        Note: moving to "0a633bf5" which isn't a local branch


@@ -1029,6 +1066,10 @@ history, but if we actually wanted to use this revision as the basis
 for new commits, we would first have to create a new branch name as it
 describes.
 
 for new commits, we would first have to create a new branch name as it
 describes.
 

+If we were to use "git checkout" with a branch name, then that would
+change the current branch, (meaning that any new commits would advance
+that branch pointer).
+

 For now, let's return back to the tip of the master branch by just
 checking it out again:
 
 For now, let's return back to the tip of the master branch by just
 checking it out again: