## Chapter 2
-A tour of Mercurial: the basics
+A tour of git: the basics
### 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.
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
-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.
-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
-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
- apt-get install mercurial
+ apt-get install git-core
* Fedora Core
- yum install mercurial
+ yum install git
* Gentoo
- emerge mercurial
+ emerge git
* OpenSUSE
- yum install mercurial
-
- * Ubuntu Ubuntu’s Mercurial package is based on Debian’s. To install
-it, run the following command.
-
- apt-get install mercurial
+ yum install git
-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.
+ * Ubuntu
-#### 2.1.2 Solaris
+ apt-get install git
-XXX.
+#### 2.1.2 Mac OS X
-#### 2.1.3 Mac OS X
+A git-core package is available through
+[macports](http://macports.org). Once macports is enabled, the command
+to install git is:
-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.
+ port install git-core
-#### 2.1.4 Windows
+#### 2.1.3 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
-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
-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
-In Mercurial, everything happens inside a repository. The repository
+In git, everything happens inside a repository. The repository
for a project contains all of the files that “belong to” that project,
along with a historical record of the project’s files.
There’s nothing particularly magical about a repository; it is simply
-a directory tree in your filesystem that Mercurial treats as
+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.
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 Mercurial provides. This command
-is called “hg clone”, because it creates an identical copy of an
+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.
- $ hg clone http://hg.serpentine.com/tutorial/hello
- destination directory: hello
- requesting all changes
- adding changesets
- adding manifests
- adding file changes
- added 5 changesets with 5 changes to 2 files
- 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+ $ git clone git://cworth.org/git/hello
+ Initialized empty Git repository in /tmp/hello/.git/
+ remote: Generating pack...
+ remote: Done counting 15 objects.
+ remote: Deltifying 15 objects...
+ remote: 100% (15/15) done
+ remote: Total 15 (delta 2), reused 0 (delta 0)
+ Indexing 15 objects...
+ 100% (15/15) done
+ Resolving 2 deltas...
+ 100% (2/2) done
+
+If for some reason you are prevented from talking on the git: port,
+then there is also the capability to clone a repository (less
+efficiently) over http:
+
+ $ git clone http://cworth.org/git/hello
+ Initialized empty Git repository in /tmp/hello/.git/
+ got 8e5536eaf0c9313cfcfd3bb915c7ebb63d6f7a91
+ walk 8e5536eaf0c9313cfcfd3bb915c7ebb63d6f7a91
+ got e4c1447f272c0f90e0a80e55f495ec377863f6f5
+ got d884386a016f03bdd6c2c72ceba5621568cc0329
+ got 350a36688de4ee9dfeba52f09bf02385cb967bb2
+ walk d884386a016f03bdd6c2c72ceba5621568cc0329
+ got 9a3ff79a7c30a4b990d49fe7c9095d6bd2eab6c0
+ got ab82c5460482579faae7841e8da3b98fbb34a41c
+ got e19aeb100a31497481bba401cea42a39fac230ae
+ walk e19aeb100a31497481bba401cea42a39fac230ae
+ got 80b260cae9cec3cd52d27c46741ff59c321b852c
+ got 23f952d3dccd5524c3c1b48b3558a5b7393286c2
+ got 9fa6a8464b692252de9a3a20c9e579700d613b17
+ walk 9fa6a8464b692252de9a3a20c9e579700d613b17
+ got b8937ca165a312157658a67e7d413dd59e6ad377
+ got b3f85f210ff86d334575f64cb01c5bf49895b63e
+ got 556e69f96b04bff82857ddd7f7c08b2f3231d664
+ walk 556e69f96b04bff82857ddd7f7c08b2f3231d664
+ got ed55ec04ebc1736a91997a6ce7d7091010647c3d
+ got 43d727f2f3f2f7cb3b098ddad1d7038464a4cee2
If our clone succeeded, we should now have a local directory called
hello. This directory will contain some files.
- $ ls -l
- total 4
- drwxrwxr-x 3 bos bos 4096 Jun 17 18:05 hello
- $ ls hello
- Makefile hello.c
+ $ ls -l
+ total 4
+ drwxr-xr-x 3 cworth cworth 4096 2007-09-27 16:40 hello
+ $ ls hello
+ hello.c Makefile
These files have the same contents and history in our repository as
they do in the repository we cloned.
-Every Mercurial repository is complete, self-contained, and
+Every git repository is complete, self-contained, and
independent. It contains its own private copy of a project’s files and
history. A cloned repository remembers the location of the repository
it was cloned from, but it does not communicate with that repository,
#### 2.3.2 What’s in a repository?
When we take a more detailed look inside a repository, we can see that
-it contains a directory named .hg. This is where Mercurial keeps all
+it contains a directory named .git. This is where git keeps all
of its metadata for the repository.
- $ cd hello
- $ ls -a
- . .. .hg Makefile hello.c
+ $ cd hello
+ $ ls -a
+ . .. .git hello.c Makefile
-The contents of the .hg directory and its subdirectories are private
-to Mercurial. Every other file and directory in the repository is
+The contents of the .git directory and its subdirectories are private
+to git. Every other file and directory in the repository is
yours to do with as you please.
-To introduce a little terminology, the .hg directory is the “real”
+To introduce a little terminology, the .git directory is the “real”
repository, and all of the files and directories that coexist with it
are said to live in the working directory. An easy way to remember the
distinction is that the repository contains the history of your
By default, this command prints a brief paragraph of output for each
-change to the project that was recorded. In Mercurial terminology, we
+change to the project that was recorded. In git terminology, we
call each of these recorded events a changeset, because it can contain
a record of changes to several files.
projects / hgbook-git / blobdiff