Port section 2.2 (Getting started) from mercurial to git

[hgbook-git] / tour.mdwn

diff --git a/tour.mdwn b/tour.mdwn
index 1d8435be1b6626b051cd5ed87e901b4afc06243b..e6429f24592acec073ac8df11b235f311b307a83 100644 (file)
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -1,10 +1,12 @@
 ## Chapter 2  
 ## Chapter 2  

-A tour of Mercurial: the basics
+A tour of git: the basics

 
 ### 2.0 Copyright
 
 
 ### 2.0 Copyright
 

-Distributed revision control with Mercurial
-Bryan O’Sullivan
+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
+<http://hgbook.red-bean.com/>.

 
 Copyright © 2006, 2007 Bryan O’Sullivan.
 
 
 Copyright © 2006, 2007 Bryan O’Sullivan.
 


@@ -12,122 +14,116 @@ This material may be distributed only subject to the terms and
 conditions set forth in version 1.0 of the Open Publication
 License. Please refer to Appendix D for the license text.
 
 conditions set forth in version 1.0 of the Open Publication
 License. Please refer to Appendix D for the license text.
 

-### 2.1  Installing Mercurial on your system
+As this is a modified version, the name of Bryan O'Sullivan is used
+only to properly credit him with the original text. The appearance of
+his name here explicitly does not assert or imply his endorsement of
+this modified document.

 
 

-Prebuilt binary packages of Mercurial are available for every popular
-operating system. These make it easy to start using Mercurial on your
+Portions Copyright © 2007 Carl Worth.
+
+Changes made by Carl include the following:
+
+  * 2007-09-27:
+    * Convert from HTML to markdown source syntax
+    * Eliminate all content except Chapter 2 and Appendix D
+    * Eliminate line numbers from examples
+    * Modified to describe git instead of mercurial
+
+### 2.1  Installing git on your system
+
+Prebuilt binary packages of git are available for many popular
+operating systems. These make it easy to start using git on your

 computer immediately.
 
 #### 2.1.1  Linux
 
 Because each Linux distribution has its own packaging tools, policies,
 and rate of development, it’s difficult to give a comprehensive set of
 computer immediately.
 
 #### 2.1.1  Linux
 
 Because each Linux distribution has its own packaging tools, policies,
 and rate of development, it’s difficult to give a comprehensive set of

-instructions on how to install Mercurial binaries. The version of
-Mercurial that you will end up with can vary depending on how active
+instructions on how to install git binaries. The version of
+git that you will end up with can vary depending on how active

 the person is who maintains the package for your distribution.
 
 the person is who maintains the package for your distribution.
 

-To keep things simple, I will focus on installing Mercurial from the
+To keep things simple, I will focus on installing git from the

 command line under the most popular Linux distributions. Most of these
 distributions provide graphical package managers that will let you
 command line under the most popular Linux distributions. Most of these
 distributions provide graphical package managers that will let you

-install Mercurial with a single click; the package name to look for is
-mercurial.
+install git with a single click. The package name to look for is
+often git, but is sometimes git-core, (due to an unfortunate name
+with git, meaning GNU Interactive Tools).

 
   * Debian 
 
 
   * Debian 
 

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

 
   * Fedora Core 
 
 
   * Fedora Core 
 

-       yum install mercurial
+       yum install git

 
   * Gentoo 
 
 
   * Gentoo 
 

-       emerge mercurial
+       emerge git

 
   * OpenSUSE 
 
 
   * OpenSUSE 
 

-       yum install mercurial
-
-  * Ubuntu Ubuntu’s Mercurial package is based on Debian’s. To install
-it, run the following command.
+       yum install git

 
 

-       apt-get install mercurial
+  * Ubuntu 

 
 

-The Ubuntu package for Mercurial tends to lag behind the Debian
-version by a considerable time margin (at the time of writing, seven
-months), which in some cases will mean that on Ubuntu, you may run
-into problems that have since been fixed in the Debian package.
+       apt-get install git

 
 

-#### 2.1.2  Solaris
+#### 2.1.2  Mac OS X

 
 

-XXX. 
+A git-core package is available through
+[macports](http://macports.org). Once macports is enabled, the command
+to install git is:

 
 

-#### 2.1.3  Mac OS X
+       port install git-core

 
 

-Lee Cantey publishes an installer of Mercurial for Mac OS X at
-[http://mercurial.berkwood.com][6]. This package works on both
-Intel- and Power-based Macs. Before you can use it, you must install a
-compatible version of Universal MacPython [[BI][7]]. This is easy to
-do; simply follow the instructions on Lee’s site.
+#### 2.1.3  Windows

 
 

-#### 2.1.4  Windows
-
-Lee Cantey also publishes an installer of Mercurial for Windows at
-[http://mercurial.berkwood.com][6]. This package has no external
-dependencies; it “just works”.
-
-Note: The Windows version of Mercurial does not automatically convert
-line endings between Windows and Unix styles. If you want to share
-work with Unix users, you must do a little additional configuration
-work. XXX Flesh this out.
+Git has long been available as part of cygwin, and works reasonably
+well in that environment. Some people find cygwin a particularly
+inelegant approach to running git and would prefer a "native"
+solution. To this end, the [msysgit
+project](http://code.google.com/p/msysgit/) is rapidly putting
+together a solution including various packages with full
+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).

 
 ### 2.2  Getting started
 
 
 ### 2.2  Getting started
 

-To begin, we’ll use the “hg version” command to find out whether
-Mercurial is actually installed properly. The actual version
-information that it prints isn’t so important; it’s whether it prints
-anything at all that we care about.
+To begin, we’ll use the “git version” command to find out whether git
+is actually installed properly. Versions 1.5 and newer of git are much
+more friendly to new users than versions 1.4 and older. If you aren't
+yet running version 1.5 or newer, it's highly recommended that you
+upgrade.

 
 

-       $ hg version   
-       Mercurial Distributed SCM (version 2937d0dbfab0)   
-       
-       Copyright (C) 2005, 2006 Matt Mackall <mpm@selenic.com>   
-       This is free software; see the source for copying conditions. There is NO   
-       warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+       $ git version   
+       git version 1.5.3.2

 
 #### 2.2.1  Built-in help
 
 
 #### 2.2.1  Built-in help
 

-Mercurial provides a built-in help system. This is invaluable for
-those times when you find yourself stuck trying to remember how to run
-a command. If you are completely stuck, simply run “hg help”; it will
-print a brief list of commands, along with a description of what each
-does. If you ask for help on a specific command (as below), it prints
-more detailed information.
-
-       $ hg help init   
-       hg init [-e CMD] [--remotecmd CMD] [DEST]   
-       
-       create a new repository in the given directory   
-       
-       Initialize a new repository in the given directory.  If the given   
-       directory does not exist, it is created.   
-       
-       If no directory is given, the current directory is used.   
-       
-       It is possible to specify an ssh:// URL as the destination.   
-       Look at the help text for the pull command for important details   
-       about ssh:// URLs.   
-       
-       options:   
-       
-       -e --ssh        specify ssh command to use   
-       --remotecmd  specify hg command to run on the remote side   
-       
-       use "hg -v help init" to show global options
-
-For a more impressive level of detail (which you won’t usually need)
-run “hg help -v”. The -v option is short for --verbose, and tells
-Mercurial to print more information than it usually would.
+Git provides a built-in help system. This is invaluable for those
+times when you find yourself stuck trying to remember how to run a
+command. If you are completely stuck, simply run “git help”; it will
+print a brief list of commonly-used commands, along with a description
+of what each does. If you ask for help on a specific command (such as
+"git help init"), it prints more detailed information. [XXX: Does "git
+help <foo>" work universally as a built-in or does it expect man to be
+present and just call out to "man git-<foo>"?]
+
+       [XXX: The original hgbook includes the complete output of "hg
+       help init" at this point. I'm not including the corresponding
+       "git help init" output as it would be excessively long. The
+       description alone is quite reasonable, (other than a
+       not-too-helpful aside about the obsolete git-init-db command),
+       but it only comes after a full screen's worth of options
+       details. Might it make sense to have a more summarized help
+       output for "git help <foo>" than all of the documentation
+       available for git-<foo>? And perhaps alos provide a "git -v
+       help" similar to "hg -v help" for more?]

 
 ### 2.3  Working with a repository
 
 
 ### 2.3  Working with a repository