Port section 2.8 (sharing changes) from mercurial to git

diff --git a/tour.mdwn b/tour.mdwn
index 7ff65f635f2d5f665232672d5354f581ffa72f93..ac6935269f93725256f6fbf065242895028dd703 100644 (file)
--- a/tour.mdwn
+++ b/tour.mdwn
@@ -529,7 +529,7 @@ disk space in most cases, too.
 
        $ cd ..
        $ git clone hello my-hello
 
        $ cd ..
        $ git clone hello my-hello

-       Initialized empty Git repository in /home/cworth/src/hgbook-git/my-hello/.git/
+       Initialized empty Git repository in /tmp/my-hello/.git/

        0 blocks
 
        [XXX We say "empty" here, (presumably from the git-init part),
        0 blocks
 
        [XXX We say "empty" here, (presumably from the git-init part),


@@ -911,8 +911,8 @@ Bryan's original chapter. -Carl]
 
 ### 2.8  Sharing changes
 
 
 ### 2.8  Sharing changes
 

-We mentioned earlier that repositories in Mercurial are
-self-contained. This means that the changeset we just created exists
+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.
 
 only in our my-hello repository. Let’s look at a few ways that we can
 propagate this change into other repositories.
 


@@ -922,222 +922,188 @@ To get started, let’s clone our original hello repository, which does
 not contain the change we just committed. We’ll call our temporary
 repository hello-pull.
 
 not contain the change we just committed. We’ll call our temporary
 repository hello-pull.
 

-       $ cd ..   
-       $ hg clone hello hello-pull   
-       2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+       $ cd ..
+       $ git clone hello hello-pull
+       Initialized empty Git repository in /tmp/hello-pull/.git/
+       0 blocks

 
 

-We’ll use the “hg pull” command to bring changes from my-hello into
-hello-pull. However, blindly pulling unknown changes into a repository
-is a somewhat scary prospect. Mercurial provides the “hg incoming”
-command to tell us what changes the “hg pull” command would pull into
-the repository, without actually pulling the changes in.
+We could use the “git pull” command to apply changes from my-hello to
+our master branch in hello-pull. However, blindly pulling unknown
+changes into a repository is a somewhat scary prospect. The "git pull"
+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   

-       $ hg incoming ../my-hello   
-       comparing with ../my-hello   
-       searching for changes   
-       changeset:   5:fa1321bf0c80   
-       tag:         tip   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Sun Jun 17 18:05:50 2007 +0000   
-       summary:     Added an extra line of output   
-       
-
-(Of course, someone could cause more changesets to appear in the
-repository that we ran “hg incoming” in, before we get a chance to “hg
-pull” the changes, so that we could end up pulling changes that we
-didn’t expect.)
-
-Bringing changes into a repository is a simple matter of running the
-“hg pull” command, and telling it which repository to pull from.
-
-       $ hg tip   
-       changeset:   4:b57f9a090b62   
-       tag:         tip   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Tue Sep 06 15:43:07 2005 -0700   
-       summary:     Trim comments.   
-       
-       $ hg pull ../my-hello   
-       pulling from ../my-hello   
-       searching for changes   
-       adding changesets   
-       adding manifests   
-       adding file changes   
-       added 1 changesets with 1 changes to 1 files   
-       (run 'hg update' to get a working copy)   
-       $ hg tip   
-       changeset:   5:fa1321bf0c80   
-       tag:         tip   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Sun Jun 17 18:05:50 2007 +0000   
-       summary:     Added an extra line of output   
-       
-
-As you can see from the before-and-after output of “hg tip”, we have
-successfully pulled changes into our repository. There remains one
-step before we can see these changes in the working directory.
-
-#### 2.8.2  Updating the working directory
-
-We have so far glossed over the relationship between a repository and
-its working directory. The “hg pull” command that we ran in
-section [2.8.1][12] brought changes into the repository, but if we
-check, there’s no sign of those changes in the working directory. This
-is because “hg pull” does not (by default) touch the working
-directory. Instead, we use the “hg update” command to do this.
-
-       $ grep printf hello.c   
-       printf("hello, world!∖");   
-       $ hg update tip   
-       1 files updated, 0 files merged, 0 files removed, 0 files unresolved   
-       $ grep printf hello.c   
-       printf("hello, world!∖");   
-       printf("hello again!∖n");
-
-It might seem a bit strange that “hg pull” doesn’t update the working
-directory automatically. There’s actually a good reason for this: you
-can use “hg update” to update the working directory to the state it
-was in at any revision in the history of the repository. If you had
-the working directory updated to an old revision—to hunt down the
-origin of a bug, say—and ran a “hg pull” which automatically updated
-the working directory to a new revision, you might not be terribly
-happy.
-
-However, since pull-then-update is such a common thing to do,
-Mercurial lets you combine the two by passing the -u option to “hg
-pull”.
-
-       hg pull -u
-
-If you look back at the output of “hg pull” in section [2.8.1][12]
-when we ran it without -u, you can see that it printed a helpful
-reminder that we’d have to take an explicit step to update the working
-directory:
-
-       (run 'hg update' to get a working copy)
-
-To find out what revision the working directory is at, use the “hg
-parents” command.
-
-       $ hg parents   
-       changeset:   5:fa1321bf0c80   
-       tag:         tip   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Sun Jun 17 18:05:50 2007 +0000   
-       summary:     Added an extra line of output   
+       $ git fetch ../my-hello
+       remote: Generating pack...
+       Unpacking 3 objects...
+        100% (3/3) done
+       remote: Done counting 5 objects.
+       Result has 3 objects.
+       Deltifying 3 objects...
+        100% remote: (3/3) done
+       Total 3 (delta 1), reused 0 (delta 0)
+
+The fetched commits (or commit in this case) are available as the name
+FETCH_HEAD. [XXX: Shouldn't git-fetch print that name out to the user
+if the user didn't provide a specific branch name to fetch into.] And
+the difference between what we had before and what exists on
+FETCH_HEAD can easily be examined with the ..FETCH_HEAD range
+notation:
+
+       $ git log ..FETCH_HEAD
+       commit 839b58d021c618bd0e1d336d4d5878a0082672e6
+       Author: Carl Worth <cworth@cworth.org>
+       Date:   Thu Sep 27 23:55:00 2007 -0700

        
        

+           Added an extra line of output and fixed the typo bug.

 
 

-If you look back at figure [2.1][8], you’ll see arrows connecting each
-changeset. The node that the arrow leads from in each case is a
-parent, and the node that the arrow leads to is its child. The working
-directory has a parent in just the same way; this is the changeset
-that the working directory currently contains.
-
-To update the working directory to a particular revision, give a
-revision number or changeset ID to the “hg update” command.
-
-       $ hg update 2   
-       2 files updated, 0 files merged, 0 files removed, 0 files unresolved   
-       $ hg parents   
-       changeset:   2:057d3c2d823c   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Tue Sep 06 13:15:43 2005 -0700   
-       summary:     Introduce a typo into hello.c.   
-       
-       $ hg update   
-       2 files updated, 0 files merged, 0 files removed, 0 files unresolved
+Since these commits actually exist in the local repository now, we
+don't need to fetch or pull them from the remote repository again---we
+can now use "git merge" to apply the previously fetched commits. (A
+mercurial user might notice here that git does not have the race
+condition between "hg incoming" and "hg pull" that mercurial has since
+the commits are fetched only once.)
+
+       $ git merge FETCH_HEAD
+       Updating a1a0e8b..839b58d
+       Fast forward
+        hello.c |    3 ++-
+        1 files changed, 2 insertions(+), 1 deletions(-)
+
+Notice that "git merge" reports that our branch pointer has been
+updated from a1a0e8b to 839b58d. Also, this is a "fast forward"
+meaning that the new commits are a linear sequence on top of the
+commit we already hand. In other words, there wasn't any divergence
+between these two repositories so no actual "merge" commit was
+created.
+
+This separation of fetch and merge is useful when you need to
+carefully review some changes before applying them. But often you're
+in a situation where you know you trust the remote repository and you
+simply want to pull those changes as conveniently as possible, (no
+extra commands, no typing a magic name like FETCH_HEAD). This is the
+case when the tracking upstream development of a project with git. And
+in that case, the above steps are as simple as just executing "git
+pull". So let's repeat all that the simpler way:

 
 

-If you omit an explicit revision, “hg update” will update to the tip
-revision, as shown by the second call to “hg update” in the example
-above.
+       $ cd ..
+       $ git clone hello hello-tracking
+       Initialized empty Git repository in /tmp/hello-tracking/.git/
+       0 blocks
+       $ cd hello-tracking
+       $ git pull ../my-hello
+       remote: Generating pack...
+       remote: Done counting 5 objects.
+       Result has 3 objects.
+       Deltifying 3 objects...
+       Unpacking 3 objects...
+       remote:  100% (3/3) done
+       Total 3 (delta 1), reused 0 (delta 0)
+        100% (3/3) done
+       Updating a1a0e8b..839b58d
+       Fast forward
+        hello.c |    3 ++-
+        1 files changed, 2 insertions(+), 1 deletions(-)
+
+It should be plain to see that the "git pull" command really did the
+combined sequence of "git fetch" and "git merge". Also, if you want to
+pull from the same repository you cloned from originally, (which is
+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
+
+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.
+
+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:
+
+       $ git checkout 0a633bf5
+       Note: moving to "0a633bf5" which isn't a local branch
+       If you want to create a new branch from this checkout, you may do so
+       (now or later) by using -b with the checkout command again. Example:
+         git checkout -b <new_branch_name>
+       HEAD is now at 0a633bf... Create a makefile
+
+The note that git gives us is to indicate that we are checking out a
+non-branch revision. This is perfectly fine if we are just exploring
+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 now, let's return back to the tip of the master branch by just
+checking it out again:
+
+       $ git checkout 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
 

-Mercurial lets us push changes to another repository, from the
-repository we’re currently visiting. As with the example of “hg pull”
-above, we’ll create a temporary repository to push our changes into.
-
-       $ cd ..   
-       $ hg clone hello hello-push   
-       2 files updated, 0 files merged, 0 files removed, 0 files unresolved
-
-The “hg outgoing” command tells us what changes would be pushed into
-another repository.
-
-       $ cd my-hello   
-       $ hg outgoing ../hello-push   
-       comparing with ../hello-push   
-       searching for changes   
-       changeset:   5:fa1321bf0c80   
-       tag:         tip   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Sun Jun 17 18:05:50 2007 +0000   
-       summary:     Added an extra line of output   
-       
-
-And the “hg push” command does the actual push. 
-
-       $ hg push ../hello-push   
-       pushing to ../hello-push   
-       searching for changes   
-       adding changesets   
-       adding manifests   
-       adding file changes   
-       added 1 changesets with 1 changes to 1 files
+Git lets us push changes to another repository, from the repository
+we’re currently visiting. As with previous examples, above, we’ll
+first create a temporary repository to push our changes into. But
+instead of using "git clone", this time we'll use "git init" to make a
+repository from an empty directory. We do this to create a "bare"
+repository which is simply a repository that has no working-directory
+files associated with it. In general, you should only push to bare
+repositories.

 
 

-As with “hg pull”, the “hg push” command does not update the working
-directory in the repository that it’s pushing changes into. (Unlike
-“hg pull”, “hg push” does not provide a -u option that updates the
-other repository’s working directory.)
+       $ cd ..
+       $ mkdir hello-push
+       $ cd hello-push
+       $ git --bare init
+       Initialized empty Git repository in /tmp/hello-push/
+
+And then we'll go back to our my-hello repository to perform the
+push. Since this is our very first push into this repository we need
+to tell git which branches to push. The easiest way to do this is to
+use --all to indicate all branches:
+
+       $ cd ../my-hello
+       $ git push ../hello-push --all
+       updating 'refs/heads/master'
+         from 0000000000000000000000000000000000000000
+         to   839b58d021c618bd0e1d336d4d5878a0082672e6
+       Generating pack...
+       Done counting 18 objects.
+       Deltifying 18 objects...
+        100% (18/18) done
+       Writing 18 objects...
+        100% (18/18) done
+       Total 18 (delta 3), reused 0 (delta 0)
+       Unpacking 18 objects...
+        100% (18/18) done
+       refs/heads/master: 0000000000000000000000000000000000000000 -> 839b58d021c618bd0e1d336d4d5878a0082672e6
+
+For subsequent pushes we don't need to specify --all as "git push"
+will push all branches that exist in both the local and remote
+repositories.

 
 What happens if we try to pull or push changes and the receiving
 repository already has those changes? Nothing too exciting.
 
 
 What happens if we try to pull or push changes and the receiving
 repository already has those changes? Nothing too exciting.
 

-       $ hg push ../hello-push   
-       pushing to ../hello-push   
-       searching for changes   
-       no changes found
+       $ git push ../hello-push
+       Everything up-to-date

 
 #### 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
 
 #### 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

-same fashion over a network connection; simply pass in a URL instead
-of a local path.
-
-       $ hg outgoing http://hg.serpentine.com/tutorial/hello   
-       comparing with http://hg.serpentine.com/tutorial/hello   
-       searching for changes   
-       changeset:   5:fa1321bf0c80   
-       tag:         tip   
-       user:        Bryan O'Sullivan <bos@serpentine.com>   
-       date:        Sun Jun 17 18:05:50 2007 +0000   
-       summary:     Added an extra line of output   
-       
-
-In this example, we can see what changes we could push to the remote
-repository, but the repository is understandably not set up to let
-anonymous users push to it.
-
-       $ hg push http://hg.serpentine.com/tutorial/hello   
-       pushing to http://hg.serpentine.com/tutorial/hello   
-       searching for changes   
-       ssl required
-
-   [1]: http://hgbook.red-bean.com/hgbookch3.html
-   [2]: http://hgbook.red-bean.com/hgbookch1.html
-   [3]: http://hgbook.red-bean.com/hgbookch1.html#tailhgbookch1.html
-   [4]: #tailhgbookch2.html
-   [5]: http://hgbook.red-bean.com/hgbook.html#hgbookch2.html
-   [6]: http://mercurial.berkwood.com/
-   [7]: http://hgbook.red-bean.com/hgbookli4.html#Xweb:macpython
-   [8]: #x6-340581
-   [9]: hgbookch2_files/tour-history.png
-   [10]: http://hgbook.red-bean.com/hgbookch12.html#x16-27100012.4
-   [11]: #x6-420002.7.1
-   [12]: #x6-490002.8.1
-   [13]: http://hgbook.red-bean.com/hgbookch2.html
+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  
 Open Publication License
 
 ## Appendix D  
 Open Publication License