@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 checkout(map()) :: {:ok, map()} | {:error, any()}

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

@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 url to target_path.

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

Creates a commit with the given message in a repository.

@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 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.

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

Fetches all remotes in a repository.

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

Fetches from origin in the given repository path.

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

Returns the currently checked-out branch name.

@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_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 gh_available?() :: boolean()

Checks if the GitHub CLI (gh) is available.

@spec glab_available?() :: boolean()

Checks if the GitLab CLI (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 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_abort(binary()) :: {:ok, binary()} | {:error, binary()}

Aborts a merge in progress.

@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 set_user_info(binary(), binary()) :: :ok

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

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

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

@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_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()] | map()) :: :ok | {: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.