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>
J. Bruce Fields committed
Jan 10, 2007 at 23:17 UTC
aec053bb0a1fb000622f51df22b2f18553a10efd
1 file changed
+57
-2
Documentation/user-manual.txt
+57
-2
@@ -622,7 +622,7 @@ We have seen several ways of naming commits already:
622
- HEAD: refers to the head of the current branch
623
624
There are many more; see the "SPECIFYING REVISION" section of the
625
-gitlink:git-rev-list[1] man page for the complete list of ways to
625
+gitlink:git-rev-parse[1] man page for the complete list of ways to
626
name revisions. Some examples:
627
628
-------------------------------------------------
@@ -663,6 +663,15 @@ When we discuss merges we'll also see the special name MERGE_HEAD,
663
which refers to the other branch that we're merging in to the current
664
branch.
665
666
+The gitlink:git-rev-parse[1] command is a low-level command that is
667
+occasionally useful for translating some name for a commit to the SHA1 id for
668
+that commit:
669
+
670
+-------------------------------------------------
671
+$ git rev-parse origin
672
+e05db0fd4f31dde7005f075a84f96b360d05984b
673
+-------------------------------------------------
674
+
675
Creating tags
676
-------------
677
@@ -757,6 +766,47 @@ $ git show v2.5:fs/locks.c
766
Before the colon may be anything that names a commit, and after it
767
may be any path to a file tracked by git.
768
769
+Examples
770
+--------
771
+
772
+Check whether two branches point at the same history
773
+----------------------------------------------------
774
+
775
+Suppose you want to check whether two branches point at the same point
776
+in history.
777
+
778
+-------------------------------------------------
779
+$ git diff origin..master
780
+-------------------------------------------------
781
+
782
+will tell you whether the contents of the project are the same at the two
783
+branches; in theory, however, it's possible that the same project contents
784
+could have been arrived at by two different historical routes. You could
785
+compare the SHA1 id's:
786
+
787
+-------------------------------------------------
788
+$ git rev-list origin
789
+e05db0fd4f31dde7005f075a84f96b360d05984b
790
+$ git rev-list master
791
+e05db0fd4f31dde7005f075a84f96b360d05984b
792
+-------------------------------------------------
793
+
794
+Or you could recall that the ... operator selects all commits contained
795
+reachable from either one reference or the other but not both: so
796
+
797
+-------------------------------------------------
798
+$ git log origin...master
799
+-------------------------------------------------
800
+
801
+will return no commits when the two branches are equal.
802
+
803
+Check which tagged version a given fix was first included in
804
+------------------------------------------------------------
805
+
806
+Suppose you know that a critical fix made it into the linux kernel with commit
807
+e05db0fd... You'd like to find which kernel version that commit first made it
808
+into.
809
+
810
Developing with git
811
===================
812
@@ -1590,7 +1640,12 @@ mywork. The result will look like:
1640
1641
In the process, it may discover conflicts. In that case it will stop and
1642
allow you to fix the conflicts as described in
1593
-"<<resolving-a-merge,Resolving a merge>>". Once the index is updated with
1643
+"<<resolving-a-merge,Resolving a merge>>".
1644
+
1645
+XXX: no, maybe not: git diff doesn't produce very useful results, and there's
1646
+no MERGE_HEAD.
1647
+
1648
+Once the index is updated with
1649
the results of the conflict resolution, instead of creating a new commit,
1650
just run
1651