Add note about inconsitency of which dates git-log uses by default

[hgbook-git] / tour.mdwn

diff --git a/tour.mdwn b/tour.mdwn
index c511fab051c9e5d75d23316a5835dc749cfbcce9..53f8f2ca8cc7e7fcec82c06c5a05a9eb1508c00c 100644 (file)
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -39,13 +39,13 @@ or
 
 and can be [browsed online](http://git.cworth.org/git/hgbook-git)
 
 
 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.
 
 
 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
 
 Because each Linux distribution has its own packaging tools, policies,
 and rate of development, it’s difficult to give a comprehensive set of


@@ -80,7 +80,7 @@ with git, meaning GNU Interactive Tools).
 
        apt-get install git-core
 
 
        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
 
 A git-core package is available through
 [macports](http://macports.org). Once macports is enabled, the command


@@ -88,7 +88,7 @@ to install git is:
 
        port install git-core
 
 
        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
 
 Git has long been available as part of cygwin, and works reasonably
 well in that environment. Some people find cygwin a particularly


@@ -102,7 +102,7 @@ port of git, and WinGit, a package for installing just git itself
 without the development environment, (still in Alpha as of September
 2007).
 
 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
 
 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


@@ -113,7 +113,7 @@ upgrade.
        $ git version
        git version 1.5.3.2
 
        $ 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
 
 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


@@ -135,7 +135,7 @@ present and just call out to "man git-<foo>"?]
        available for git-<foo>? And perhaps alos provide a "git -v
        help" similar to "hg -v help" for more?]
 
        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,
 
 In git, everything happens inside a repository. The repository
 for a project contains all of the files that “belong to” that project,


@@ -146,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.
 
 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/
 
        $ git clone git://cworth.org/git/hello
        Initialized empty Git repository in /tmp/hello/.git/


@@ -205,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.
 
 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
 
 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


@@ -226,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.
 
 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
 
 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


@@ -289,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.
 
 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
 
 As English is a notoriously sloppy language, and computer science has
 a hallowed history of terminological confusion (why use one term when


@@ -339,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
 
 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
 
 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


@@ -371,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
 
 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
 commit names from file names:
 
        $ git log -- Makefile


@@ -392,10 +397,14 @@ created:
 
        $ git log --since="2 weeks ago" --until="yesterday"
 
 
        $ 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.
 
 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
 
 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


@@ -480,7 +489,7 @@ same output:
                return 0;
         }
 
                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
 
 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


@@ -511,7 +520,7 @@ systems.
 Many commands that print output of some kind can be made more quiet by
 passing the -q or --quiet options.
 
 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.
 
 Now that we have a grasp of viewing history in git, let’s take a
 look at making some changes and examining them.


@@ -601,7 +610,7 @@ this, we use the “git diff” command.
                return 0;
         }
 
                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
 
 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


@@ -611,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”.
 
 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
 
 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


@@ -709,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.
 
 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
 
 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


@@ -719,12 +728,18 @@ after we’ve finished committing.
 
        $ git commit -a
 
 
        $ 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 “#”.
 
 The editor that the “git commit” command drops us into will contain an
 empty line, followed by a number of lines starting with “#”.


@@ -743,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.
 
 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
 
 A good commit message will generally have a single line that
 summarizes the commit, a blank line, and then one or more pargraphs


@@ -774,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".
 
 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.
 
 
 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
 
 Once we’ve finished the commit, we can use the “git show” command to
 display the commit we just created. As discussed previously, this


@@ -905,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]
 
 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.
 
 
 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
 
 To get started, let’s clone our original hello repository, which does
 not contain the change we just committed. We’ll call our temporary


@@ -1026,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).]
 
 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
 
        $ git checkout 0a633bf5
        Note: moving to "0a633bf5" which isn't a local branch


@@ -1055,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.
 
 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:
 
 For now, let's return back to the tip of the master branch by just
 checking it out again:
 


@@ -1062,7 +1081,7 @@ checking it out again:
        Previous HEAD position was 0a633bf... Create a makefile
        Switched to branch "master"
 
        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 lets us push changes to another repository, from the repository
 we’re currently visiting. As with previous examples, above, we’ll


@@ -1110,7 +1129,7 @@ repository already has those changes? Nothing too exciting.
        $ git push ../hello-push
        Everything up-to-date
 
        $ 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
 
 The commands we have covered in the previous few sections are not
 limited to working with local repositories. Each works in exactly the


@@ -1122,7 +1141,7 @@ Open Publication License
 
 Version 1.0, 8 June 1999 
 
 
 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
 
 The Open Publication works may be reproduced and distributed in whole
 or in part, in any medium physical or electronic, provided that the


@@ -1151,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.
 
 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.
 
 
 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.
 
 The following license terms apply to all Open Publication works,
 unless otherwise explicitly stated in the document.


@@ -1176,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.
 
 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
 
 All modified versions of documents covered by this license, including
 translations, anthologies, compilations and partial documents, must


@@ -1193,7 +1212,7 @@ meet the following requirements:
      assert or imply endorsement of the resulting document without the
      original author’s (or authors’) permission.
 
      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:
 
 In addition to the requirements of this license, it is requested from
 and strongly recommended of redistributors that:


@@ -1212,7 +1231,7 @@ and strongly recommended of redistributors that:
      CD-ROM expression of an Open Publication-licensed work to its
      author(s).
 
      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
 
 The author(s) and/or publisher of an Open Publication-licensed
 document may elect certain options by appending language to the