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

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

@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 commits_between(binary(), binary(), binary(), keyword()) ::
  {:ok, [{binary(), binary()}]} | {:error, binary()}

Returns the list of commits between from_sha and to_sha.

Equivalent to git log from_sha..to_sha. By default returns a list of {:ok, sha, message} tuples, one per commit.

Options

• :format — :short | :full | :oneline (default :short)

Examples

iex> Trebejo.Git.Local.History.commits_between(".", "abc123", "HEAD")
{:ok, [{"def456", "Fix bug"}, {"ghi789", "Add feature"}]}

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

Shows diff of changes.

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

Gets the commit count for a repository.

@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_short_commit(binary()) :: {:ok, binary()} | {:error, binary()}

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

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

Shows commit history (log).