On Mon, Oct 6, 2025 at 5:47 PM Julia Evans [off-list ref] wrote:

On Mon, Oct 6, 2025, at 5:44 PM, D. Ben Knoble wrote:

quoted

On Mon, Oct 6, 2025 at 3:37 PM Julia Evans [off-list ref] wrote:

quoted

Thanks for the review!

quoted

quoted

2. Don't mention that the full name of the branch `main` is
   technically `refs/heads/main`. This should likely change but I
   haven't worked out how to do it in a clear way yet.

I think this is worth getting into.  This is a pretty
user-facing concept.

I think I'll see if I can figure out a way to mention this and at the
same time remove most of the rest of the references to the `.git`
directory when explaining references (which you talked about
further down), including packed refs.

A colleague will be explaining reflog for an audience tomorrow, and
decided to briefly explain refs, too—which tells me this is
much-needed.

For refs themselves, perhaps "git for-each-ref" is a reasonable place
to start? Since it tells you the refs you have and how to spell them
explicitly regardless of how they are stored?

Interesting, do you use git for-each-ref?
What do you use it for?

Ah, yes, but primarily for scripting.

What I should have clarified is that "the tool (I know of) to
interrogate the refs you currently have is git-for-each-ref" (like how
git-ls-remote is the tool to interrogate a remote's refs). It avoids
the issues with assuming "tree .git/refs" or similar will capture the
actual data.

-- 
D. Ben Knoble