Ragex.Git.Backend behaviour (Ragex v0.17.1)

View Source

Behaviour defining the contract for git backend implementations.

Two implementations exist:

  • Ragex.Git.Backend.CLI -- shells out to the git binary. Universal fallback that works everywhere git is installed. Also the only path for operations that libgit2 doesn't support (e.g. git log -L for function evolution).

  • Ragex.Git.Backend.Egit -- NIF bindings to libgit2 via the egit package. Faster (no process spawn, no text parsing) but requires libgit2-dev at build time and is an optional dependency.

Backend selection is automatic: if :git (egit) is loaded, prefer it; otherwise fall back to CLI. Override via config :ragex, git_backend: :egit | :cli | :auto.

Summary

Types

line()
path()
sha()

Callbacks

blame(path, path, keyword)

Blame a file, returning per-line authorship.

commit_info(path, sha)

Look up a single commit by SHA.

diff(path, sha, sha)

List files changed between two revisions.

log(path, path, keyword)

List commits touching a path.

repo_root(path)

Return the repository root for the given working directory.

rev_list(path, sha, keyword)

List commit SHAs reachable from rev, newest first.

Functions

active()

Returns the active backend module based on configuration and availability.

egit_available?()

Returns true when the egit NIF module is compiled and loadable.

Types

line()

@type line() :: pos_integer()

path()

@type path() :: String.t()

sha()

@type sha() :: String.t()

Callbacks

blame(path, path, keyword)

@callback blame(path(), path(), keyword()) ::
  {:ok, [Ragex.Git.BlameEntry.t()]} | {:error, term()}

Blame a file, returning per-line authorship.

Options

  • :start_line -- first line (1-indexed, default 1)
  • :end_line -- last line (default: end of file)

commit_info(path, sha)

@callback commit_info(path(), sha()) :: {:ok, Ragex.Git.Commit.t()} | {:error, term()}

Look up a single commit by SHA.

diff(path, sha, sha)

@callback diff(path(), sha(), sha()) :: {:ok, [{path(), atom()}]} | {:error, term()}

List files changed between two revisions.

Returns {:ok, [{path, status}]} where status is :added | :modified | :deleted | :renamed.

log(path, path, keyword)

@callback log(path(), path(), keyword()) ::
  {:ok, [Ragex.Git.Commit.t()]} | {:error, term()}

List commits touching a path.

Options

  • :max_count -- limit results (default 50)
  • :since -- ISO-8601 date string or ~D date
  • :author -- filter by author substring

repo_root(path)

@callback repo_root(path()) :: {:ok, path()} | {:error, term()}

Return the repository root for the given working directory.

rev_list(path, sha, keyword)

@callback rev_list(path(), sha(), keyword()) :: {:ok, [sha()]} | {:error, term()}

List commit SHAs reachable from rev, newest first.

Options

  • :max_count -- limit results (default 500)

Functions

active()

@spec active() :: module()

Returns the active backend module based on configuration and availability.

Resolution order:

  1. Explicit config :ragex, :git_backend (:egit or :cli)
  2. Auto-detect: egit if loaded, otherwise CLI

egit_available?()

@spec egit_available?() :: boolean()

Returns true when the egit NIF module is compiled and loadable.