and can be [browsed online](http://git.cworth.org/git/hgbook-git)
-### 2.1 Installing git on your system
+### 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
+#### 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
apt-get install git-core
-#### 2.1.2 Mac OS X
+#### 2.1.2 Mac OS X
A git-core package is available through
[macports](http://macports.org). Once macports is enabled, the command
port install git-core
-#### 2.1.3 Windows
+#### 2.1.3 Windows
Git has long been available as part of cygwin, and works reasonably
well in that environment. Some people find cygwin a particularly
without the development environment, (still in Alpha as of September
2007).
-### 2.2 Getting started
+### 2.2 Getting started
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
$ git version
git version 1.5.3.2
-#### 2.2.1 Built-in help
+#### 2.2.1 Built-in help
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
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
In git, everything happens inside a repository. The repository
for a project contains all of the files that “belong to” that project,
special. You can rename or delete a repository any time you like,
using either the command line or your file browser.
-#### 2.3.1 Creating a local copy of a remote repository
+#### 2.3.1 Creating a local copy of a remote 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, safe in the knowledge that it’s a private “sandbox” that
won’t affect anyone else.
-#### 2.3.2 What’s in a 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 .git. This is where git keeps all
project, while the working directory contains a snapshot of your
project at a particular point in history.
-### 2.4 A tour through history
+### 2.4 A tour through history
One of the first things we might want to do with a new, unfamiliar
repository is understand its history. The “git log” command gives us a
The default output printed by “git log” is purely a summary; it is
missing a lot of detail.
-#### 2.4.1 Commits, revisions, and talking to other people
+#### 2.4.1 Commits, revisions, and talking to other people
As English is a notoriously sloppy language, and computer science has
a hallowed history of terminological confusion (why use one term when
commits. So "origin..master" specifies everything that has been
committed to master since it diverged from origin.
-#### 2.4.3 Viewing specific revisions
+#### 2.4.3 Viewing specific revisions
You can use "git log" to explore the range syntax just introduced. For
example, to see a list of the most recent 3 revisions you can use
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
$ git log --since="2 weeks ago" --until="yesterday"
+ [XXX: By default, "git log" displays author dates as "Date"
+ but then uses commit dates when given a --since option. That
+ seems like broken defaults to me. Why the inconsistency?]
+
Another useful option is -n or --max-count which, unsurprisingly,
limits the maximum number of commits to be displayed.
-#### 2.4.5 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
return 0;
}
-### 2.5 All about command options
+### 2.5 All about command options
Let’s take a brief break from exploring git commands to discuss
a pattern in the way that they work; you may find this useful to keep
Many commands that print output of some kind can be made more quiet by
passing the -q or --quiet options.
-### 2.6 Making and reviewing changes
+### 2.6 Making and reviewing changes
Now that we have a grasp of viewing history in git, let’s take a
look at making some changes and examining them.
return 0;
}
-### 2.7 Recording changes in a new commit
+### 2.7 Recording changes in a new commit
We can modify files, build and test our changes, and use “git status”
and “git diff” to review our changes, until we’re satisfied with what
The “git commit” command lets us create a new changeset; we’ll usually
refer to this as “making a commit” or “committing”.
-#### 2.7.1 Setting up a username
+#### 2.7.1 Setting up a username
When you try to run “git commit” for the first time, it might not do
exactly what you want. Git records your name and address with each
useful to be reminded which machine was used to create particular
commits.
-#### 2.7.2 Writing a commit message
+#### 2.7.2 Writing a commit message
When we commit a change, git drops us into a text editor to
enter a message that will describe the modifications we’ve made in
$ 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 “#”.
to tell us which files it’s recording changes to. Modifying or
deleting these lines has no effect.
-#### 2.7.3 Writing a good commit message
+#### 2.7.3 Writing a good commit message
A good commit message will generally have a single line that
summarizes the commit, a blank line, and then one or more pargraphs
that tell me something that I can’t figure out with a quick glance at
the output of “git log -p".
-#### 2.7.4 Aborting a commit
+#### 2.7.4 Aborting a commit
If you decide that you don’t want to commit while in the middle of
editing a commit message, simply exit from your editor without saving
the file that it’s editing. This will cause nothing to happen to
either the repository or the working directory.
-#### 2.7.5 Admiring our new handiwork
+#### 2.7.5 Admiring our new handiwork
Once we’ve finished the commit, we can use the “git show” command to
display the commit we just created. As discussed previously, this
All this bad-habit stuff was introduced by me, and was not present in
Bryan's original chapter. -Carl]
-### 2.8 Sharing changes
+### 2.8 Sharing changes
We mentioned earlier that repositories in git are
self-contained. This means that the commit we just created exists
only in our my-hello repository. Let’s look at a few ways that we can
propagate this change into other repositories.
-#### 2.8.1 Pulling changes from another repository
+#### 2.8.1 Pulling changes from another repository
To get started, let’s clone our original hello repository, which does
not contain the change we just committed. We’ll call our temporary
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
+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:
Previous HEAD position was 0a633bf... Create a makefile
Switched to branch "master"
-#### 2.8.3 Pushing changes to another repository
+#### 2.8.3 Pushing changes to another repository
Git lets us push changes to another repository, from the repository
we’re currently visiting. As with previous examples, above, we’ll
$ git push ../hello-push
Everything up-to-date
-#### 2.8.4 Sharing changes over a network
+#### 2.8.4 Sharing changes over a network
The commands we have covered in the previous few sections are not
limited to working with local repositories. Each works in exactly the
Version 1.0, 8 June 1999
-### D.1 Requirements on both unmodified and modified versions
+### D.1 Requirements on both unmodified and modified versions
The Open Publication works may be reproduced and distributed in whole
or in part, in any medium physical or electronic, provided that the
large as the title of the work and cited as possessive with respect to
the title.
-### D.2 Copyright
+### D.2 Copyright
The copyright to each Open Publication is owned by its author(s) or
designee.
-### D.3 Scope of license
+### D.3 Scope of license
The following license terms apply to all Open Publication works,
unless otherwise explicitly stated in the document.
limited to, the implied warranties of merchantability and fitness for
a particular purpose or a warranty of non-infringement.
-### D.4 Requirements on modified works
+### D.4 Requirements on modified works
All modified versions of documents covered by this license, including
translations, anthologies, compilations and partial documents, must
assert or imply endorsement of the resulting document without the
original author’s (or authors’) permission.
-### D.5 Good-practice recommendations
+### D.5 Good-practice recommendations
In addition to the requirements of this license, it is requested from
and strongly recommended of redistributors that:
CD-ROM expression of an Open Publication-licensed work to its
author(s).
-### D.6 License options
+### D.6 License options
The author(s) and/or publisher of an Open Publication-licensed
document may elect certain options by appending language to the
projects / hgbook-git / blobdiff