X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=tour.mdwn;h=53f8f2ca8cc7e7fcec82c06c5a05a9eb1508c00c;hb=6c295b78cc0207247daba5594f62b6ead3dd94e8;hp=3ba6af94849ea8ce77cecf54b1a18b25ec8e5847;hpb=bb4386f58c87854098784df6e11b8aeaed23af99;p=hgbook-git
diff --git a/tour.mdwn b/tour.mdwn
index 3ba6af9..53f8f2c 100644
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -3,9 +3,9 @@ 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
.
Copyright © 2006, 2007 Bryan OâSullivan.
@@ -29,13 +29,23 @@ Changes made by Carl include the following:
* Eliminate line numbers from examples
* Modified to describe git instead of mercurial
-### 2.1 Installing git on your system
+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
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
@@ -68,9 +78,9 @@ with git, meaning GNU Interactive Tools).
* Ubuntu
- apt-get install git
+ 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
@@ -78,7 +88,7 @@ to install git is:
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
@@ -90,9 +100,9 @@ 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).
+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
@@ -103,7 +113,7 @@ upgrade.
$ 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
@@ -125,7 +135,7 @@ present and just call out to "man git-"?]
available for git-? 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,
@@ -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.
-#### 2.3.1 Making a local copy of a 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. 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).
-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.
+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/
@@ -195,7 +210,7 @@ What this means for now is that weâre free to experiment with our
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
@@ -216,7 +231,7 @@ distinction is that the repository contains the history of your
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
@@ -279,7 +294,7 @@ The fields in a record of output from âgit logâ are as follows.
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
@@ -329,9 +344,9 @@ 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
-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
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
@@ -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
-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
@@ -382,10 +397,14 @@ created:
$ 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.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
@@ -470,7 +489,7 @@ same output:
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
@@ -501,7 +520,7 @@ systems.
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.
@@ -591,7 +610,7 @@ this, we use the âgit diffâ command.
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
@@ -601,7 +620,7 @@ record our work in a new commit.
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
@@ -699,7 +718,7 @@ requirement that the email address actually be valid, and perhaps it's
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
@@ -709,12 +728,18 @@ after weâve finished committing.
$ 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 "
+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 " 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 â#â.
@@ -733,7 +758,7 @@ git ignores the lines that start with â#â; it uses them only
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
@@ -764,14 +789,14 @@ My personal preference is for short, but informative, commit messages
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
@@ -895,14 +920,14 @@ the --amend example to not teach bad habits like I did above. [Note:
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
@@ -1016,21 +1041,21 @@ 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).]
-#### 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
@@ -1045,6 +1070,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.
+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:
@@ -1052,7 +1081,7 @@ 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
@@ -1100,7 +1129,7 @@ repository already has those changes? Nothing too exciting.
$ 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
@@ -1112,7 +1141,7 @@ Open Publication License
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
@@ -1141,12 +1170,12 @@ outer surfaces of the book the original publisherâs name shall be as
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.
@@ -1166,7 +1195,7 @@ without warranty of any kind, express or implied, including, but not
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
@@ -1183,7 +1212,7 @@ meet the following requirements:
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:
@@ -1202,7 +1231,7 @@ 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