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

On Wed, Feb 17, 2010 at 08:51:27PM -0500, Avery Pennarun wrote:

On Wed, Feb 17, 2010 at 8:16 PM, Jeff King [off-list ref] wrote:

quoted

Agreed. It's a minor point, but one that can mislead users who don't
know about packed refs. Maybe something like this?

Wow, you really go all out.  Looks pretty good to me, except maybe this:

Well, if we're going to spend the mental energy to change one spot, we
may as well grep and change them all. :)

quoted

++
+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`).

Are they really equal precedence?  How does git decide, when there's
one of each?  I'd guess packed-refs might actually be strictly higher
precedence, but I'm not sure.

No, packed refs are just below actual ref files in precedence, because
any writes since the pack will be in the actual ref file. What I meant
by "same precedence" was that a packed ref behaves in the lookup
precedence "as if" its ref file existed.

Perhaps it should read:

  (e.g., a line with `refs/heads/master` in the packed-refs file would
  have precedence just below `$GIT_DIR/refs/heads/master` but above
  `$GIT_DIR/refs/remotes/master`)

but that is really conflating two types of precedence (packed refs
versus ref files, and fully-qualifying ref names). They do form a strict
ordering when combined, but that does not necessarily mean that is the
best way for users to understand what is happening.

Maybe that section should also just lose the $GIT_DIR/ from all of the
refs examples, and then we should note later that they may come from
$GIT_DIR or from packed-refs.

-Peff