Module ref_files 

Files-backend ref reads that answer without a Git process or decline. What: Reads of the files ref storage that answer a question without a Git process, and refuse to answer anything they cannot prove equal to Git’s answer. Why: git symbolic-ref --quiet HEAD only reads the worktree’s HEAD file and, for a branch, checks that the branch is not itself a symbolic ref. A strict reader of the plain spellings saves a process on every commit, and every other spelling (a different ref name shape, a link, a symbolic chain, reftable storage) returns None, which sends the caller to Git.

In TS you’d write (pseudocode):

const head = readHeadFile(layout); // undefined means "ask Git"

Structs

RefFilesLayout

What: Where one worktree’s ref files live and what format they are in. Why: The per-worktree HEAD is in the Git directory, the branches are in the common directory, and the length of an object name depends on the object format.

Functions

is_plain_branch_name

What: Whether name is a branch ref name of a plain, always valid shape: refs/heads/ and then components of ASCII letters, digits, ., _ and -. Why: Git refuses names with a component that starts with . or ends with .lock, a .., an empty component or a trailing .; the plain alphabet needs no other rule, and any other spelling is left to Git.

read_symbolic_head

What: git symbolic-ref --quiet HEAD answered from the worktree’s HEAD file, or None when the file is not one of the two plain spellings. Why: ref: <plain branch> and a lone object name are the only shapes the commit path meets; the file is read afresh on every call, so a landing that calls this under its lock sees the file as it is then.