Re: Host refs to push are chosen (documentation error)?

[Jeff King <peff@peff.net>]

On Wed, Feb 17, 2010 at 06:04:00PM -0800, Junio C Hamano wrote:

> This is not about "I have packed refs/heads/master and then a loose
> refs/heads/master also exists" case.  After packing, update ref simply
> creates a new loose ref, and we read loose ones and give precedence to it
> over packed one.  This is so that you once gc and most of the unchanging
> refs will stay in packed file, but some active branches can be quickly
> flipped without having to rewrite the whole packed refs file (or removing
> the ref from that file).
> 
> But the statement is not about that.  The statement is about this:
> 
>     "refs/tags/master" gets higher precedence over "refs/heads/master",
>     and this order is indifferent to where these two refs come from,
>     either packed refs or loose in the filesystem.

Exactly what I meant, but if somebody as clueful as Avery gets confused,
then probably I need to be a bit more clear in my note.

Maybe just this squashed into my previous patch?

---
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 9ee006b..1a613aa 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -197,15 +197,15 @@ blobs contained in a commit.
   . if `$GIT_DIR/<name>` exists, that is what you mean (this is usually
     useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD` and `MERGE_HEAD`);
 
-  . otherwise, `$GIT_DIR/refs/<name>` if exists;
+  . otherwise, `refs/<name>` if exists;
 
-  . otherwise, `$GIT_DIR/refs/tags/<name>` if exists;
+  . otherwise, `refs/tags/<name>` if exists;
 
-  . otherwise, `$GIT_DIR/refs/heads/<name>` if exists;
+  . otherwise, `refs/heads/<name>` if exists;
 
-  . otherwise, `$GIT_DIR/refs/remotes/<name>` if exists;
+  . otherwise, `refs/remotes/<name>` if exists;
 
-  . otherwise, `$GIT_DIR/refs/remotes/<name>/HEAD` if exists.
+  . otherwise, `refs/remotes/<name>/HEAD` if exists.
 +
 HEAD names the commit your changes in the working tree is based on.
 FETCH_HEAD records the branch you fetched from a remote repository
@@ -217,10 +217,8 @@ them easily.
 MERGE_HEAD records the commit(s) you are merging into your branch
 when you run 'git merge'.
 +
-For any of the `$GIT_DIR/refs` cases above, packed refs from
-`$GIT_DIR/packed-refs` may be substituted (e.g., a line with
-`refs/heads/master` in the packed-refs file would have the same
-precedence as the file `$GIT_DIR/refs/heads/master`).
+Note that any of the `refs/*` cases above may come either from
+the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
 
 * A ref followed by the suffix '@' with a date specification
   enclosed in a brace