@spec add(binary(), :all | [binary()] | binary()) ::
  :ok | {:ok, binary()} | {:error, any()}

Stages files in a repository.

Pass :all to stage everything, a list of paths, or a single path binary.

@spec blame(binary(), binary()) :: {:ok, binary()} | {:error, binary()}

Shows who last modified each line of a file (blame).

@spec branch_exists?(binary()) :: boolean()

Returns true if the given branch exists locally or remotely.

@spec build_churn_args(keyword()) :: [binary()]

Builds churn arguments for git log.

@spec build_git_opts(binary(), integer() | nil) :: keyword()

Builds git options for a repository path and optional timeout.

@spec checkout(map()) :: {:ok, map()} | {:error, any()}

Checks out the main_branch of a repository, stashing uncommitted changes first if necessary.

@spec cherry_pick(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Cherry-picks a commit.

@spec churn(
  binary(),
  keyword()
) :: {:ok, [map()]} | {:error, binary()}

Returns churn metrics — the most frequently changed files.

Runs git log --name-only for the given period or max commits and counts how many times each file has been modified. Results are sorted by churn count descending.

When include_authors: true, uses --format=COMMIT:%an to track which authors touched each file, so callers can compute risk scores like churn * (1 + log(num_authors)).

Options

• :period — Time period for git log (default: "6.months"). Ignored if :max_commits is set.
• :max_commits — Limit to the last N commits (uses --max-count). Overrides :period.
• :no_merges — Exclude merge commits via --no-merges (default: false)
• :top — Return only the top N files (default: 20)
• :branch — Git branch to analyze (default: current branch)
• :include_authors — Track distinct authors per file (default: false). When true, each result includes :authors (list of author names).
• :timeout — Command timeout in milliseconds (default: nil, meaning Arrea's default). Passed to Arrea.Command.execute/2.

Examples

iex> Trebejo.Git.Local.churn(".")
{:ok, [%{file: "lib/foo.ex", churn: 15}, ...]}

iex> Trebejo.Git.Local.churn(".", max_commits: 1000, no_merges: true, include_authors: true)
{:ok, [%{file: "lib/foo.ex", churn: 15, authors: ["Alice", "Bob"]}, ...]}

@spec clone(map()) :: {:ok, map()} | {:error, any()}

Clones a repository from url to path.

@spec clone_repository(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Clones a repository from a URL to a target path.

@spec commit(map(), binary()) :: {:ok, map()} | {:error, any()}

Creates a commit with the given message in a repository.

@spec commit_all(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Commits all staged changes.

@spec config(
  binary(),
  keyword()
) :: binary()

Gets a Git configuration value (local → global → system).

Accepts an optional cd: option to scope the lookup to a specific repository directory.

@spec config_global(
  binary(),
  keyword()
) :: binary()

Gets a Git configuration value from the global scope.

Accepts an optional cd: option (kept for signature parity with config/2; ignored at the global scope).

@spec config_local(
  binary(),
  keyword()
) :: binary()

Gets a Git configuration value from the local (repo) scope.

Accepts an optional cd: option to scope the lookup to a specific repository directory.

@spec conflict_files(binary()) :: {:ok, [binary()]} | {:error, binary()}

Lists files with merge conflicts in the repo.

@spec contains_no_commits?(any()) :: boolean()

Checks if a repository contains no commits.

@spec create_branch(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Creates a new branch.

@spec delete_branch(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Deletes a branch.

@spec diff(
  binary(),
  keyword()
) :: {:ok, binary()} | {:error, binary()}

Shows diff of changes.

@spec ensure_clone(nil) :: {:error, :no_repo_defined}

Ensures a repository is cloned. If it already exists, updates it.

Accepts a single repo map, a list of repo maps, or nil.

@spec existing_repos([tuple()]) :: binary()

Returns a tree string of existing (already-cloned) repositories from a list of {:repo_exists | :repo_error, map(), ...} tuples.

@spec fetch(map()) :: {:ok, map()} | {:error, any()}

Fetches all remotes in a repository.

@spec fetch_all_changes(binary()) :: {:ok, binary()} | {:error, any()}

Fetches all repository changes from origin.

@spec fetch_origin(binary()) :: {:ok, binary()} | {:error, binary()}

Fetches from origin in the given repository path.

@spec fetch_repository_updates(binary()) :: {:ok, binary()} | {:error, any()}

Fetches repository updates from origin.

@spec get_commit_count(binary()) :: {:ok, integer()} | {:error, any()}

Gets the commit count for a repository.

@spec get_current_branch(binary()) :: {:ok, binary()} | {:error, binary()}

Returns the currently checked-out branch name.

@spec get_current_commit(binary()) :: {:ok, binary()} | {:error, any()}

Gets the current commit hash for a repository.

@spec get_first_commit(binary()) :: {:ok, binary()} | {:error, any()}

Gets the first commit hash for a repository.

@spec get_git_user_email() :: binary() | nil

Returns the configured Git user email, or nil if not set.

@spec get_git_user_name() :: binary() | nil

Returns the configured Git user name, or nil if not set.

@spec get_hostname() :: binary()

Returns the machine's hostname.

@spec get_short_commit(binary()) :: {:ok, binary()} | {:error, binary()}

Gets the short (7-char) commit hash for HEAD.

@spec get_system_user_email() :: binary()

Returns the current system user email from the USER_EMAIL env variable, falling back to "user@domain.com".

@spec get_system_user_name() :: binary()

Returns the current system user name.

@spec get_user_info() :: map()

Returns a map with the current Git user information.

Falls back to system user information if Git is not configured.

@spec get_working_directory() :: binary()

Gets the current working directory.

@spec gh_available?() :: boolean()

Checks if gh is available.

@spec glab_available?() :: boolean()

Checks if glab is available.

@spec has_stash?(binary()) :: boolean()

Returns true if the repository has stash entries.

@spec has_uncommitted_changes?(binary()) :: boolean()

Returns true if there are uncommitted changes in the repository.

@spec list_local_branches(binary()) :: {:ok, [binary()]} | {:error, any()}

Returns the list of all local branches.

@spec log(
  binary(),
  keyword()
) :: {:ok, binary()} | {:error, binary()}

Shows commit history (log).

@spec mark_resolved(binary(), binary()) :: :ok | {:error, binary()}

Marks a conflicted file as resolved (after manual fix).

@spec merge(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Merges a branch into the current branch.

@spec merge_abort(binary()) :: {:ok, binary()} | {:error, binary()}

Aborts a merge in progress.

@spec merge_commit(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Merges a commit into the current branch.

@spec parse_churn_output(binary(), boolean()) :: [binary()]

Parses churn output.

@spec pull(map()) :: {:ok, map()} | {:error, any()}

Pulls from origin using the repository's main_branch.

@spec pull_origin(binary(), binary()) :: {:ok, binary()} | {:error, binary()}

Pulls from origin for the given branch (default: "main").

@spec rebase(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Rebase a branch onto another.

@spec revert(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Reverts a commit.

@spec run_git(
  [binary()],
  keyword()
) :: {:ok, map()} | {:error, any()}

Runs a git command with options.

@spec run_system_cmd(binary(), binary(), keyword()) :: {:ok, map()} | {:error, any()}

Runs a system command with telemetry instrumentation.

@spec set_user_info(binary(), binary()) :: :ok | {:error, binary()}

Sets Git user name, email, and URL rewrite rules globally.

@spec setup_credential_helper(binary()) :: :ok | {:error, binary()}

Sets up a credential helper for git.

@spec setup_credentials(keyword()) :: :ok | {:error, binary()}

Configures Git credentials (SSH key path or credential helper).

@spec setup_ssh_key(binary()) :: :ok | {:error, binary()}

Sets up an SSH key for git.

@spec shell_quote(binary()) :: binary()

Quotes a binary string for safe shell use.

@spec squash(binary(), binary()) :: {:ok, binary()} | {:error, any()}

Squashes commits into one.

@spec stage_all(binary()) :: {:ok, binary()} | {:error, any()}

Stages all changes.

@spec stage_and_commit(map(), binary()) :: {:ok, map()} | {:error, any()}

Stages all changes and creates a commit with the given message.

@spec stash_if_needed(binary()) ::
  {:ok, {:stashed, binary()} | :clean} | {:error, any()}

Stashes uncommitted changes if the working tree is dirty.

Returns {:ok, {:stashed, branch}}, {:ok, :clean}, or {:error, reason}.

@spec stash_pop(binary()) :: {:ok, binary()} | {:error, binary()}

Restores stashed changes.

@spec stash_push(
  binary(),
  keyword()
) :: {:ok, binary()} | {:error, binary()}

Pushes stash entries in a repository.

Options

• :message — stash description (default: "auto-stash")
• :include_untracked — include untracked files (default: true)

@spec sync([map()]) :: :ok

@spec sync(map()) :: {:ok, map()} | {:error, any()}

Synchronises a list of repositories (checkout → fetch → pull).

@spec update_existing_repository(binary()) :: {:ok, binary()} | {:error, any()}

Updates an existing repository by fetching from origin.