silk.git.local.

When to use#

Call LocalRefs.read with the Git directory to get a RefList from silk.git.refs, then look up the current branch with RefList.head or a name with RefList.resolve. Use LocalRefs.gitDirectory to find the Git directory of a working tree, which is .git or the directory that a .git file names. It reads files through the FileSystem service of silk.system.filesystem, so tests can give files in memory.

Details#

A loose reference file holds an object id, or ref: and the name of another reference. A loose reference replaces a packed one of the same name. Symbolic references, such as HEAD on a branch, have the name as their target and the id that the chain of names ends at. The result has HEAD first, then the other references sorted by name, as git show-ref lists them. For a linked worktree, HEAD comes from its own Git directory and the other references from the common directory that its commondir file names.

Errors#

• GitRefError from silk.git.refs if packed-refs or HEAD is malformed, a chain of symbolic references loops, or the repository uses the reftable format.

• FileError if a file or directory cannot be read.

• OutOfMemoryError if the Allocator fails.

Gotchas#

Loose reference files that cannot be read as an id or a ref: line are skipped, as Git skips them, and so are .lock files. Only references are read: this does not read objects, so a tag is peeled only when packed-refs records it.

Import as LocalRefs with import silk.git.local { LocalRefs }.

Public declarations: 1.

LocalRefs#

pub struct LocalRefs

Functions that read the references of a local repository.

Implementation LocalRefs#

impl LocalRefs

Associated function gitDirectory#

pub effect fn gitDirectory(worktree: &Path) -> Path
    ! GitRefError | FileError | OutOfMemoryError
    ? &mut FileSystem | &mut Allocator

Returns the Git directory of the working tree at worktree.

Details#

When worktree/.git is a directory, that is the Git directory. When it is a file, as in a linked worktree or a submodule, the file holds gitdir: and a path, absolute or relative to worktree, and that path is the Git directory.

Errors#

• FileError with reason NotFound if worktree/.git does not exist, or another reason if it cannot be read.

• GitRefError.Malformed if the .git file does not start with gitdir: .

• OutOfMemoryError if the Allocator cannot supply the path.

Associated function read#

pub effect fn read(gitDir: &Path) -> RefList
    ! GitRefError | FileError | OutOfMemoryError
    ? &mut FileSystem | &mut Allocator

Returns the references of the repository whose Git directory is gitDir: HEAD first, then the loose and packed references sorted by name.

Details#

A loose reference under refs/ replaces a packed reference of the same name. A symbolic reference, such as HEAD when a branch is checked out, has the name it points at as its target and the id that the chain ends at. Its id is None when the chain ends at a reference that does not exist, such as the branch of a new repository. A detached HEAD has an id and no target. A tag has a peeled id when packed-refs records it.

For a linked worktree, whose Git directory has a commondir file, HEAD is read from gitDir and the other references from the common directory.

Errors#

• GitRefError.Malformed if HEAD or packed-refs is broken.

• GitRefError.SymbolicLoop if a chain of symbolic references is longer than five.

• GitRefError.Unsupported if the repository uses the reftable format.

• FileError if HEAD or a directory under refs/ cannot be read.

• OutOfMemoryError if the Allocator fails.

Gotchas#

Loose reference files that hold neither an id nor a ref: line are skipped, and so are .lock files, as Git does. Per-worktree references other than HEAD, such as refs/bisect/, are not read.

Associated function parsePackedRefs#

pub effect fn parsePackedRefs(contents: &[u8]) -> RefList
    ! GitRefError | OutOfMemoryError
    ? &mut Allocator

Returns the references of the packed-refs file contents, sorted by name.

Details#

The file has an optional # pack-refs with: line, then one <id> <name> line for each reference. A line ^<id> sets the peeled id of the reference before it.

Errors#

• GitRefError.Malformed with the offset of the first broken line.

• OutOfMemoryError if the Allocator fails.

Category: Version control.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.