From: Julia Evans <julia@jvns.ca>
Date: Tue, 03 Nov 2026 14:36:17 GMT
Subject: Re: [PATCH v2 0/5] root refs vs pseudorefs
Message-ID: <d3878168-95b9-4b4b-bfd8-85d459122e5f@app.fastmail.com>
In-Reply-To: <CAHWeT-YSK3xFA=Hztr3Uj5UW=L9JcC_0iOa5pUG-WGCpwng9vw@mail.gmail.com>


> pseudoref
>     A name that can be used like a ref to refer to an object, but that
>     is not stored in the same way as refs. For example, pseudorefs can
>     be passed to git-log(1) or git-diff(1), but they cannot be written
>     by git-update-ref(1) or listed by git-for-each-ref(1).
>
>     The following pseudorefs are known to Git:
>
>     •   FETCH_HEAD is written by git-fetch(1) or git-pull(1). It may
>         refer to multiple object IDs. Each object ID is annotated with
>         metadata indicating where it was fetched from and its fetch
>         status.

I found "Each object ID is annotated with metadata  indicating where it was
fetched from and its fetch status." to be very hard to parse, and I had to
go look at .git/FETCH_HEAD myself to understand what it was talking about.

It might help to instead describe `FETCH_HEAD` with an example,
especially since we already aren't giving a lot of details. 
Maybe something like this:

  Git has 2 special pseudorefs: `MERGE_HEAD` and `FETCH_HEAD`.
  Unlike references (which can only contain an object ID or the name of
  another reference), these have their own format:
  
  - `FETCH_HEAD` has a list of entries like this:
    `d4c5f27105ee2e44366d718dbc5db95bbe99c714 not-for-merge branch 'example' of https://example.com/x/y`
    with details about what was fetched by linkgit:git-fetch[1].
  - `MERGE_HEAD` has a list of commit IDs
  
  These are stored as files in the `.git` directory. You can pass a pseudoref
  to `git show`, `git log`, etc, and it will use the first ID in the list. 
  Pseudorefs can't be written by git-update-ref(1) or listed by
  git-for-each-ref(1).