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

[Jeff King <peff@peff.net>]

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

> On Wed, Feb 17, 2010 at 8:16 PM, Jeff King <peff@peff.net> wrote:
> > 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. :)

> > ++
> > +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