X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=README;h=36fef6ec041cd1d0d31c79a98f23a84e9a8691fd;hb=0890098780f295f2a58658d1f6b6627e40426c72;hp=6b38a7aa7a711c327d82e2da5e474544a7befc34;hpb=215a7ad1ef790467a4cd3f0dcffbd6e5f04c38f7;p=git.git

diff --git a/README b/README
index 6b38a7aa..36fef6ec 100644
--- a/README
+++ b/README
@@ -104,8 +104,8 @@ object. The object is totally independent of its location in the
 directory tree, and renaming a file does not change the object that
 file is associated with in any way.
 
-A blob is typically created when link:git-update-index.html[git-update-index]
-is run, and its data can be accessed by link:git-cat-file.html[git-cat-file].
+A blob is typically created when gitlink:git-update-index[1]
+is run, and its data can be accessed by gitlink:git-cat-file[1].
 
 Tree Object
 ~~~~~~~~~~~
@@ -143,9 +143,9 @@ involved), you can see trivial renames or permission changes by
 noticing that the blob stayed the same.  However, renames with data
 changes need a smarter "diff" implementation.
 
-A tree is created with link:git-write-tree.html[git-write-tree] and
-its data can be accessed by link:git-ls-tree.html[git-ls-tree].
-Two trees can be compared with link:git-diff-tree.html[git-diff-tree].
+A tree is created with gitlink:git-write-tree[1] and
+its data can be accessed by gitlink:git-ls-tree[1].
+Two trees can be compared with gitlink:git-diff-tree[1].
 
 Commit Object
 ~~~~~~~~~~~~~
@@ -169,8 +169,8 @@ implicit in the trees involved (the result tree, and the result trees
 of the parents), and describing that makes no sense in this idiotic
 file manager.
 
-A commit is created with link:git-commit-tree.html[git-commit-tree] and
-its data can be accessed by link:git-cat-file.html[git-cat-file].
+A commit is created with gitlink:git-commit-tree[1] and
+its data can be accessed by gitlink:git-cat-file[1].
 
 Trust
 ~~~~~
@@ -215,10 +215,10 @@ Note that despite the tag features, "git" itself only handles content
 integrity; the trust framework (and signature provision and
 verification) has to come from outside.
 
-A tag is created with link:git-mktag.html[git-mktag],
-its data can be accessed by link:git-cat-file.html[git-cat-file],
+A tag is created with gitlink:git-mktag[1],
+its data can be accessed by gitlink:git-cat-file[1],
 and the signature can be verified by
-link:git-verify-tag.html[git-verify-tag].
+gitlink:git-verify-tag[1].
 
 
 The "index" aka "Current Directory Cache"
@@ -286,7 +286,7 @@ main combinations:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You update the index with information from the working directory with
-the link:git-update-index.html[git-update-index] command.  You
+the gitlink:git-update-index[1] command.  You
 generally update the index information by just specifying the filename
 you want to update, like so:
 
@@ -396,15 +396,55 @@ git-commit-tree will return the name of the object that represents
 that commit, and you should save it away for later use. Normally,
 you'd commit a new `HEAD` state, and while git doesn't care where you
 save the note about that state, in practice we tend to just write the
-result to the file `.git/HEAD`, so that we can always see what the
-last committed state was.
+result to the file pointed at by `.git/HEAD`, so that we can always see
+what the last committed state was.
+
+Here is an ASCII art by Jon Loeliger that illustrates how
+various pieces fit together.
+
+------------
+
+                     commit-tree
+                      commit obj
+                       +----+
+                       |    |
+                       |    |
+                       V    V
+                    +-----------+
+                    | Object DB |
+                    |  Backing  |
+                    |   Store   |
+                    +-----------+
+                       ^
+           write-tree  |     |
+             tree obj  |     |
+                       |     |  read-tree
+                       |     |  tree obj
+                             V
+                    +-----------+
+                    |   Index   |
+                    |  "cache"  |
+                    +-----------+
+         update-index  ^
+             blob obj  |     |
+                       |     |
+    checkout-index -u  |     |  checkout-index
+             stat      |     |  blob obj
+                             V
+                    +-----------+
+                    |  Working  |
+                    | Directory |
+                    +-----------+
+
+------------
+
 
 6) Examining the data
 ~~~~~~~~~~~~~~~~~~~~~
 
 You can examine the data represented in the object database and the
 index with various helper tools. For every object, you can use
-link:git-cat-file.html[git-cat-file] to examine details about the
+gitlink:git-cat-file[1] to examine details about the
 object:
 
 		git-cat-file -t <objectname>
@@ -424,7 +464,7 @@ tend to be small and fairly self-explanatory. In particular, if you
 follow the convention of having the top commit name in `.git/HEAD`,
 you can do
 
-		git-cat-file commit $(cat .git/HEAD)
+		git-cat-file commit HEAD
 
 to see what the top commit was.