Documentation: rev-list -> rev-parse, other typos, start examples

Fix some typos, start adding some more simple examples.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 2fc8ce95827d5a2c5d571c5bfa57873a4ab49693..013e46fe3c5e04ff93d257e9d43382d7b54fef0a 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -622,7 +622,7 @@ We have seen several ways of naming commits already:
        - HEAD: refers to the head of the current branch
 
 There are many more; see the "SPECIFYING REVISION" section of the
        - HEAD: refers to the head of the current branch
 
 There are many more; see the "SPECIFYING REVISION" section of the

-gitlink:git-rev-list[1] man page for the complete list of ways to
+gitlink:git-rev-parse[1] man page for the complete list of ways to

 name revisions.  Some examples:
 
 -------------------------------------------------
 name revisions.  Some examples:
 
 -------------------------------------------------


@@ -663,6 +663,15 @@ When we discuss merges we'll also see the special name MERGE_HEAD,
 which refers to the other branch that we're merging in to the current
 branch.
 
 which refers to the other branch that we're merging in to the current
 branch.
 

+The gitlink:git-rev-parse[1] command is a low-level command that is
+occasionally useful for translating some name for a commit to the SHA1 id for
+that commit:
+
+-------------------------------------------------
+$ git rev-parse origin
+e05db0fd4f31dde7005f075a84f96b360d05984b
+-------------------------------------------------
+

 Creating tags
 -------------
 
 Creating tags
 -------------
 


@@ -757,6 +766,47 @@ $ git show v2.5:fs/locks.c
 Before the colon may be anything that names a commit, and after it
 may be any path to a file tracked by git.
 
 Before the colon may be anything that names a commit, and after it
 may be any path to a file tracked by git.
 

+Examples
+--------
+
+Check whether two branches point at the same history
+----------------------------------------------------
+
+Suppose you want to check whether two branches point at the same point
+in history.
+
+-------------------------------------------------
+$ git diff origin..master
+-------------------------------------------------
+
+will tell you whether the contents of the project are the same at the two
+branches; in theory, however, it's possible that the same project contents
+could have been arrived at by two different historical routes.  You could
+compare the SHA1 id's:
+
+-------------------------------------------------
+$ git rev-list origin
+e05db0fd4f31dde7005f075a84f96b360d05984b
+$ git rev-list master
+e05db0fd4f31dde7005f075a84f96b360d05984b
+-------------------------------------------------
+
+Or you could recall that the ... operator selects all commits contained
+reachable from either one reference or the other but not both: so
+
+-------------------------------------------------
+$ git log origin...master
+-------------------------------------------------
+
+will return no commits when the two branches are equal.
+
+Check which tagged version a given fix was first included in
+------------------------------------------------------------
+
+Suppose you know that a critical fix made it into the linux kernel with commit
+e05db0fd...  You'd like to find which kernel version that commit first made it
+into.
+

 Developing with git
 ===================
 
 Developing with git
 ===================
 


@@ -1590,7 +1640,12 @@ mywork.  The result will look like:
 
 In the process, it may discover conflicts.  In that case it will stop and
 allow you to fix the conflicts as described in
 
 In the process, it may discover conflicts.  In that case it will stop and
 allow you to fix the conflicts as described in

-"<<resolving-a-merge,Resolving a merge>>".  Once the index is updated with
+"<<resolving-a-merge,Resolving a merge>>".
+
+XXX: no, maybe not: git diff doesn't produce very useful results, and there's
+no MERGE_HEAD.
+
+Once the index is updated with

 the results of the conflict resolution, instead of creating a new commit,
 just run
 
 the results of the conflict resolution, instead of creating a new commit,
 just run