-## Chapter 2
+## Chapter 2
A tour of git: the basics
### 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.
* 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
often git, but is sometimes git-core, (due to an unfortunate name
with git, meaning GNU Interactive Tools).
- * Debian
+ * Debian
apt-get install git-core
- * Fedora Core
+ * Fedora Core
yum install git
- * Gentoo
+ * Gentoo
emerge git
- * OpenSUSE
+ * OpenSUSE
yum install git
- * Ubuntu
+ * Ubuntu
- apt-get install git
+ apt-get install git-core
#### 2.1.2 Mac OS X
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
yet running version 1.5 or newer, it's highly recommended that you
upgrade.
- $ git version
+ $ git version
git version 1.5.3.2
#### 2.2.1 Built-in help
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/
change to the project that was recorded. In git terminology, we
call each of these recorded events a commit.
-The fields in a record of output from “git log” are as follows.
+The fields in a record of output from “git log” are as follows.
* commit This field consists of a string of 40 hexadecimal characters.
This is a unique identifier for referring to particular commits.
The default output printed by “git log” is purely a summary; it is
missing a lot of detail.
-Figure [2.1][8] provides a graphical representation of the history of
-the hello repository, to make it a little easier to see which
-direction history is “flowing” in. We’ll be returning to this figure
-several times in this chapter and the chapter that follows.
-
-* * *
-
-![PIC][9]
-
-Figure 2.1:
-Graphical history of the hello repository
-
-* * *
-
#### 2.4.1 Commits, revisions, and talking to other people
As English is a notoriously sloppy language, and computer science has
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
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
you probably won’t want to use sed; simply use your preferred text
editor to do the same thing.)
- $ sed -i '/printf/a\\tprintf("hello again!\\n");' hello.c
+ $ sed -i '/printf/a\\tprintf("hello again!\\n");' hello.c
The “git status” command will tell us what git knows about the files
in the repository.
then it will be there already). The initial contents of your
.gitconfig should look like this.
- # This is a git configuration file.
+ # This is a git configuration file.
[user]
name = Your Name
email = you@example.com
$ 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 “#”.
and "git merge"; we can run those separately to examine the changes
before applying them locally. First we do the fetch:
- $ cd hello-pull
+ $ cd hello-pull
$ git fetch ../my-hello
remote: Generating pack...
Unpacking 3 objects...
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
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:
same fashion over a network connection; simply pass in a URL or an ssh
host:/path/name specification instead of a local path.
-## Appendix D
+## Appendix D
Open Publication License
Version 1.0, 8 June 1999