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

Returns ahead/behind counts relative to the upstream tracking branch.

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

Gets blame information for a specific line of a file.

Returns {:ok, blame_text} with a human-readable blame string, or :error if blame fails.

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

Creates a new branch and checks it out.

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

Deletes a branch.

@spec branch_list(String.t()) ::
  {:ok, [Minga.Git.BranchInfo.t()]} | {:error, String.t()}

Lists all branches (local and remote).

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

Switches to an existing branch.

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

Creates a commit with the given message.

Options: :amend (boolean, default false) to amend the previous commit.

@spec conflict_count(GenServer.server()) :: non_neg_integer()

Returns the parsed merge conflict count for a tracked buffer.

@spec conflicts(GenServer.server()) :: [Minga.Git.MergeConflict.Region.t()]

Returns parsed merge conflict regions for a tracked buffer.

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

Returns the current branch name for a git repository.

Returns {:ok, branch_name} or :error if it can't be determined (e.g., detached HEAD, not a git repo).

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

Returns the diff for a specific file or all changes.

Options: :path (file path), :staged (boolean, default false), :commit (commit hash). :commit may be combined with :staged, false; commit diffs can still be narrowed with :path.

@spec diff_lines([String.t()], [String.t()]) :: [Minga.Core.Diff.hunk()]

Computes line-level diff hunks between two lists of lines.

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

Discards working tree changes for a file. Destructive and irreversible.

For tracked files, runs git checkout -- <path>. For untracked files, deletes the file.

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

Fetches from all remotes.

@spec gutter_signs(GenServer.server()) :: %{required(non_neg_integer()) => atom()}

Returns gutter sign indicators (line → hunk type) for a tracked buffer.

@spec hunk_at(GenServer.server(), non_neg_integer()) :: Minga.Core.Diff.hunk() | nil

Returns the hunk at a specific line, or nil.

@spec hunks(GenServer.server()) :: [Minga.Core.Diff.hunk()]

Returns all diff hunks for a tracked buffer.

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

Returns the message of the most recent commit.

@spec log(
  String.t(),
  keyword()
) :: {:ok, [log_entry()]} | {:error, String.t()}

Returns recent commits as structured entries.

Options: :count (default 10), :path (limit to file).

@spec lookup_repo(String.t()) :: pid() | nil

Finds the Repo process for a git root path, or nil if not started.

@spec modeline_info(GenServer.server()) :: Minga.Git.Buffer.modeline_info()

Returns modeline-ready git info (branch, hunk counts) for a tracked buffer.

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

Pulls from the upstream remote (fetch + merge).

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

Pushes the current branch to its upstream remote.

@spec refresh_repo(pid()) :: :ok

Triggers a background refresh of the Repo's cached git state.

@spec relative_path(String.t(), String.t()) :: String.t()

Returns the path of a file relative to the git root.

@spec repo_status(pid()) :: [status_entry()]

Returns cached status entries from a running Repo process.

@spec repo_summary(pid()) :: map()

Returns a summary map (branch, ahead/behind, file counts) from a Repo.

@spec revert_hunk([String.t()], Minga.Core.Diff.hunk()) :: [String.t()]

Reverts a single hunk, restoring the base content for those lines.

@spec root_for(String.t()) :: {:ok, String.t()} | :not_git

Finds the git repository root for a file path.

Returns {:ok, root_path} if the file is inside a git repo, or :not_git if it isn't.

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

Reads the HEAD version of a file from git.

Returns {:ok, content} with the file content at HEAD, or :error if the file doesn't exist in HEAD (new file, not tracked, etc.).

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

Reads the staged (index) version of a file from git.

Returns {:ok, content} with the file content in the index, or :error if the file is not staged.

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

Stages specific files (equivalent to git add).

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

Applies a unified diff patch to the git index (staging area).

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

Saves current worktree changes to a stash.

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

Drops a stash by index.

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

Lists stashes for a repository.

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

Pops the most recent stash.

@spec status(String.t(), status_opts()) ::
  {:ok, [status_entry()]} | {:error, String.t()}

Returns a structured list of changed files with their status.

@spec sync_tracked_buffer(pid(), String.t()) :: :ok

Synchronizes a tracked buffer cache with the provided content.

@spec tracking_pid(pid()) :: pid() | nil

Returns the git tracking process for a buffer, or nil if untracked.

Composes the Tracker lookup so callers don't need to know about the Tracker → Buffer two-step.

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

Unstages specific files from the index (equivalent to git reset HEAD -- <paths>).

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

Unstages all staged files (equivalent to git reset HEAD).