Documentation: do not blindly run 'cat' .git/HEAD, or echo into it.

Many places in the documentation we still talked about reading
what commit is recorded in .git/HEAD or writing the new head
information into it, both assuming .git/HEAD is a symlink.  That
is not necessarily so.

Signed-off-by: Junio C Hamano <junkio@cox.net>

6 files changed, 11 insertions, 10 deletions

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index b426a14f5e..97756ec030 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -81,7 +81,7 @@ The "diff" formatting options can be customized via the
 environment variable 'GIT_DIFF_OPTS'.  For example, if you
 prefer context diff:
 
-      GIT_DIFF_OPTS=-c git-diff-index -p $(cat .git/HEAD)
+      GIT_DIFF_OPTS=-c git-diff-index -p HEAD
 
 
 2. When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 5cf6bd3e21..a794192d7b 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -26,8 +26,9 @@ to get there.
 
 Normally a commit would identify 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.
+tend to just write the result to the file that is pointed at by
+`.git/HEAD`, so that we can always see what the last committed
+state was.
 
 OPTIONS
 -------
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index d8fc78fab9..dba6d30fcf 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -57,14 +57,14 @@ some files in the index and are ready to commit. You want to see eactly
 *what* you are going to commit is without having to write a new tree
 object and compare it that way, and to do that, you just do
 
-	git-diff-index --cached $(cat .git/HEAD)
+	git-diff-index --cached HEAD
 
 Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had
 done an "git-update-index" to make that effective in the index file.
 "git-diff-files" wouldn't show anything at all, since the index file
 matches my working directory. But doing a "git-diff-index" does:
 
-  torvalds@ppc970:~/git> git-diff-index --cached $(cat .git/HEAD)
+  torvalds@ppc970:~/git> git-diff-index --cached HEAD
   -100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit.c
   +100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git-commit.c
 
@@ -98,7 +98,7 @@ show that. So let's say that you have edited `kernel/sched.c`, but
 have not actually done a "git-update-index" on it yet - there is no
 "object" associated with the new state, and you get:
 
-  torvalds@ppc970:~/v2.6/linux> git-diff-index $(cat .git/HEAD )
+  torvalds@ppc970:~/v2.6/linux> git-diff-index HEAD
   *100644->100664 blob    7476bb......->000000......      kernel/sched.c
 
 ie it shows that the tree has changed, and that `kernel/sched.c` has is
diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt
index 37e8055d21..bab1f6080c 100644
--- a/Documentation/git-fsck-objects.txt
+++ b/Documentation/git-fsck-objects.txt
@@ -68,7 +68,7 @@ that aren't readable from any of the specified head nodes.
 
 So for example
 
-	git-fsck-objects --unreachable $(cat .git/HEAD .git/refs/heads/*)
+	git-fsck-objects --unreachable HEAD $(cat .git/refs/heads/*)
 
 will do quite a _lot_ of verification on the tree. There are a few
 extra validity tests to be added (make sure that tree objects are
diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
index 7be0cbd620..8b91847856 100644
--- a/Documentation/git-read-tree.txt
+++ b/Documentation/git-read-tree.txt
@@ -237,7 +237,7 @@ This is done to prevent you from losing your work-in-progress
 changes.  To illustrate, suppose you start from what has been
 commited last to your repository:
 
-    $ JC=`cat .git/HEAD`
+    $ JC=`git-rev-parse --verify "HEAD^0"`
     $ git-checkout-index -f -u -a $JC
 
 You do random edits, without running git-update-index.  And then
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt
index a851ae24c4..68ac6a65df 100644
--- a/Documentation/git-symbolic-ref.txt
+++ b/Documentation/git-symbolic-ref.txt
@@ -24,8 +24,8 @@ Traditionally, `.git/HEAD` is a symlink pointing at
 we did `ln -sf refs/heads/newbranch .git/HEAD`, and when we want
 to find out which branch we are on, we did `readlink .git/HEAD`.
 This was fine, and internally that is what still happens by
-default, but on platforms that does not have working symlinks,
-or that does not have the `readlink(1)` command, this was a bit
+default, but on platforms that do not have working symlinks,
+or that do not have the `readlink(1)` command, this was a bit
 cumbersome.  On some platforms, `ln -sf` does not even work as
 advertised (horrors).