@spec branch_upstream(String.t(), String.t()) :: String.t() | nil

Returns the short upstream tracking ref for branch at root (for example origin/feature-parent), or nil when no upstream is configured or git cannot resolve it.

@spec commit_meta(String.t(), String.t()) :: {:ok, commit_meta()} | {:error, term()}

Returns parsed metadata for a single commit. Errors on unparseable output - the most common cause is a literal \x1f byte in a subject or body, which collides with the field separator used in the format string.

@spec commit_numstat(String.t(), String.t()) ::
  {:ok, commit_numstat()} | {:error, term()}

Returns the changed file list and per-file diffstat counts for a single commit.

@spec commit_shas(String.t(), String.t()) :: {:ok, [String.t()]} | {:error, term()}

Lists every commit SHA reachable from ref, newest first (rev-list order). Used by the commit indexer to enumerate index candidates.

@spec current_branch() :: String.t() | nil

Returns the current branch name for the effective directory, the short SHA prefixed with @ when HEAD is detached, or nil on failure.

@spec default_branch(String.t() | nil) :: String.t() | nil

Returns the repository's default branch for indexing purposes:

1. origin/HEAD - the remote's declared default (usually main).
2. Local main or master, in that order.
3. nil - do not silently fall back to the current branch, since that would make fnord index on a feature branch index the feature branch rather than the project's canonical source.

Callers fall back to filesystem-mode indexing when this returns nil, so the user still gets their working tree indexed; they just won't get default-branch semantics.

@spec diff_stat(String.t(), String.t()) :: {:ok, String.t()} | :error

Returns git diff --stat output for range at root.

@spec fetch_ref(String.t(), String.t(), String.t()) :: {:ok, String.t()} | :error

Fetches ref from remote at root. Network-touching: review uses it to make never-checked-out branches reviewable, and nothing else should reach for it casually.

@spec git_info() :: String.t()

Returns a formatted, user-facing description of the current git context (branch and root), or a note that the project is not under version control.

@spec ignored_files(String.t() | nil) :: map()

Returns a map of absolute paths to true for every gitignored file under root. Returns an empty map if root is nil.

@spec is_git_repo?() :: boolean()

Returns true when the effective directory (project root override or cwd) is inside a git working tree.

@spec is_git_repo_at?(String.t() | nil) :: boolean()

Returns true when the given path is inside a git working tree.

@spec is_worktree?() :: boolean()

Returns true when the effective directory is inside a git working tree. We currently treat any such directory as worktree-aware enough for callers using this predicate, including detached HEAD state.

@spec log_oneline(String.t(), String.t()) :: {:ok, String.t()} | :error

Returns git log --oneline output for range at root.

@spec ls_tree(String.t(), String.t()) ::
  {:ok, [{String.t(), String.t()}]} | {:error, term()}

Lists every blob in branch's tree as {blob_sha, rel_path} pairs. The blob sha is git's content-addressed hash and is stable across clones and checkouts, so it's usable as a freshness key for the indexer.

@spec merge_base(String.t(), String.t(), String.t()) :: {:ok, String.t()} | :error

Returns the merge base of two refs at root. The review ops below return bare :error on git failure rather than {:error, term}: their callers present target-specific context ("failed to resolve branch X") and have no use for raw plumbing output.

@spec primary_root_at(String.t()) :: String.t() | nil

Returns the primary clone's root for the repo containing dir, or nil when dir is not inside a git work tree. For a linked worktree this is the root of the clone the worktree was created from (via git rev-parse --git-common-dir); for a primary checkout it is the repo root itself. Project resolution uses this to map a worktree directory back to the configured project root.

@spec repo_root() :: String.t() | nil

Returns the repository toplevel for the effective directory, or nil when not in a repo (or git is not installed).

@spec repo_root_at(String.t()) :: {:ok, String.t()} | {:error, :not_a_repo}

Returns the repository toplevel for the given directory, or {:error, :not_a_repo} when the path is not inside a git working tree. Unlike repo_root/0, this ignores the project root override - callers use it to resolve the repo that owns an explicit path (e.g. a stored worktree) regardless of session state.

@spec show_blob(String.t(), String.t(), String.t()) ::
  {:ok, binary()} | {:error, term()}

Returns the content of rel_path as it exists on branch, or an error tuple if git rejects the request (missing file, invalid branch, etc.). Content is returned as a binary; binaries that aren't valid UTF-8 are still returned — callers decide how to handle them.

@spec status_short(String.t()) :: {:ok, [String.t()]} | {:error, term()}

Returns the raw git status --short --untracked-files=all lines for the repo at root, one entry per changed or untracked file. Used by validation-rule changed-file discovery.

@spec verify_commit(String.t(), String.t()) :: {:ok, String.t()} | :error

Resolves ref to a commit SHA if it exists locally (rev-parse --verify --quiet ref^{commit}). Never touches the network; pair with fetch_ref/3 to make remote-only refs resolvable via FETCH_HEAD.

@spec worktree_root() :: String.t() | nil

Returns the toplevel of the current worktree, or nil when not in one.