X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=tour.mdwn;h=fdaa9a5577f2e07308f4cbca2c27080f80b4a3fe;hb=5a25922d84fe47eef6b9d6cd3c59e1d1aeed451e;hp=ac6935269f93725256f6fbf065242895028dd703;hpb=1f3c9252faba1f5cc0ebe90f6b6de37b46c4b83d;p=hgbook-git
diff --git a/tour.mdwn b/tour.mdwn
index ac69352..fdaa9a5 100644
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -1,11 +1,11 @@
-## 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
.
Copyright © 2006, 2007 Bryan OâSullivan.
@@ -29,6 +29,16 @@ Changes made by Carl include the following:
* 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
@@ -50,25 +60,25 @@ 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 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
@@ -90,7 +100,7 @@ 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
@@ -100,7 +110,7 @@ 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.
- $ git version
+ $ git version
git version 1.5.3.2
#### 2.2.1 Built-in help
@@ -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
-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/
@@ -257,7 +272,7 @@ By default, this command prints a brief paragraph of output for each
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.
@@ -279,20 +294,6 @@ 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.
-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
@@ -343,7 +344,7 @@ 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
@@ -375,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
@@ -399,7 +400,7 @@ created:
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
@@ -564,7 +565,7 @@ scripted example this way. Since youâre not under the same constraint,
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.
@@ -683,7 +684,7 @@ the files directly. Use your favorite editor to create a file called
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
@@ -723,12 +724,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 â#â.
@@ -934,7 +941,7 @@ command is coneptually the combination of two commands, "git fetch"
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...
@@ -1014,21 +1021,37 @@ the common case for the upstream-tracking scenario), then "git pull"
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
+ ../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
@@ -1043,6 +1066,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:
@@ -1105,7 +1132,7 @@ limited to working with local repositories. Each works in exactly the
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