Git

A clean Elixir wrapper for the git CLI. Provides a direct, idiomatic mapping to git subcommands with fully parsed output structs and higher-level workflow abstractions. Runs git through a leak-free runner by default that kills the whole process group on timeout, and falls back to System.cmd/3 where that runner is unavailable (see Execution and timeouts).

Installation

Add git to your dependencies in mix.exs:

def deps do
  [
    {:git, "~> 0.6"}
  ]
end

Quick start

# Check repository status
{:ok, status} = Git.status()
status.branch   #=> "main"
status.entries  #=> [%{index: "M", working_tree: " ", path: "lib/foo.ex"}]

# Stage and commit
{:ok, :done}  = Git.add(all: true)
{:ok, result} = Git.commit("feat: add new feature")
result.hash    #=> "abc1234"

# Branch, push, pull
{:ok, _}     = Git.checkout(branch: "feat/new", create: true)
{:ok, :done} = Git.push(remote: "origin", branch: "feat/new", set_upstream: true)
{:ok, _}     = Git.pull(rebase: true, autostash: true)

# Inspect history
{:ok, commits} = Git.log(max_count: 5)
Enum.each(commits, fn c -> IO.puts("#{c.abbreviated_hash}  #{c.subject}") end)

Configuration

Pass a Git.Config struct via the :config option to control the working directory, git binary path, environment variables, timeout, runner, and per-invocation config:

config = Git.Config.new(
  working_dir: "/path/to/repo",
  timeout: 60_000,
  runner: :forcola,
  extra_config: [{"core.autocrlf", "false"}]
)

{:ok, status} = Git.status(config: config)

• :runner selects how git is executed: :forcola (the default, leak-free), :system_cmd, or any module implementing the Git.Runner behaviour. See Execution and timeouts.
• :extra_config is a list of {key, value} pairs emitted as git -c key=value on every invocation, so you can override config without touching the repository's .git/config.

Identity, dates, and a scratch index

Author/committer identity, commit dates, and the index file are set through :env and :extra_config (git reads them from the environment and per-invocation config) rather than dedicated options:

# Set identity without mutating repo config
Git.Config.new(extra_config: [
  {"user.name", "A U Thor"},
  {"user.email", "author@example.com"}
])

# Pin author and committer dates (commit --date sets only the author date)
Git.Config.new(env: [
  {"GIT_AUTHOR_DATE", "2020-01-01T00:00:00"},
  {"GIT_COMMITTER_DATE", "2020-01-01T00:00:00"}
])

# Build a commit off to the side against a scratch index
Git.Config.new(env: [{"GIT_INDEX_FILE", "/tmp/scratch.index"}])

Execution and timeouts

Every git command runs through a Git.Runner. The default, Git.Runner.Forcola, runs git in its own process group and kills the whole group (SIGTERM then SIGKILL) on timeout or BEAM death, so a {:error, :timeout} means git is actually gone.

This matters because System.cmd/3 implements timeouts by closing the Erlang port, which only closes the stdin/stdout pipes and never signals the git OS process. Under that model a git command that times out, and anything git spawned (ssh transports, credential helpers, hooks, sign helpers), can keep running and hold repository locks such as .git/index.lock. The forcola runner exists to close that gap, so it is the default.

forcola is an optional dependency. It is POSIX-only (macOS and Linux) and ships precompiled shim binaries, so no Rust toolchain is required on its supported targets. Add it to your dependencies to get the leak-free default:

# mix.exs
{:forcola, "~> 0.3"}

When forcola is not installed, or on a platform it does not support (for example Windows), the runner falls back to Git.Runner.SystemCmd, which uses System.cmd/3 and works everywhere with no extra dependencies. To select it explicitly:

config = Git.Config.new(runner: :system_cmd)
{:ok, status} = Git.status(config: config)

The :runner value may also be any module implementing the Git.Runner behaviour.

Commands

80 git commands with full option support and parsed output.

Core (snapshotting, branching, sharing)

Inspection and comparison

Patching and email

Administration and maintenance

Plumbing

All functions return {:ok, result} on success or {:error, {stdout, exit_code}} on failure.

Higher-level modules

Git.Repo

Stateful repository struct for cleaner API usage:

{:ok, repo} = Git.Repo.open("/path/to/repo")

{:ok, status} = Git.Repo.status(repo)
{:ok, :done}  = Git.Repo.add(repo, all: true)
{:ok, result} = Git.Repo.commit(repo, "feat: new feature")
{:ok, :done}  = Git.Repo.push(repo)

# Pipeline helpers
Git.Repo.ok(repo)
|> Git.Repo.run(fn r ->
  File.write!("new.txt", "content")
  {:ok, :done} = Git.Repo.add(r, files: ["new.txt"])
  {:ok, r}
end)
|> Git.Repo.run(fn r ->
  {:ok, _} = Git.Repo.commit(r, "add file")
  {:ok, r}
end)

Git.Workflow

Composable multi-step workflows. Everyday commit helpers:

# Stage everything and commit in one call
Git.Workflow.commit_all("fix: patch bug", config: config)

# Amend the last commit; undo it (soft); squash the last N
Git.Workflow.amend(config: config)
Git.Workflow.undo_last_commit(config: config)
Git.Workflow.squash_last(3, "feat: combined change", config: config)

# Discard all uncommitted changes (tracked and untracked)
Git.Workflow.discard_all(config: config)

Brackets and combinators (each threads :config and cleans up after itself):

# Feature branch with automatic merge + cleanup
Git.Workflow.feature_branch("feat/login", fn opts ->
  File.write!("login.ex", "...")
  {:ok, :done} = Git.add(Keyword.merge(opts, files: ["login.ex"]))
  {:ok, _} = Git.commit("feat: add login", opts)
  {:ok, :done}
end, merge: true, delete: true, config: config)

# Check out a ref, run a function, restore the original branch (even on raise)
Git.Workflow.with_branch("main", fn opts -> Git.log(opts) end, config: config)

# Stash, run a function, pop the stash
Git.Workflow.with_stash(fn opts -> Git.pull(opts) end, config: config)

# Run a runtime-built list of steps, short-circuiting on the first error
[
  {:stage, fn o -> Git.add(Keyword.merge(o, all: true)) end},
  {:commit, fn o -> Git.commit("chore: release", o) end}
]
|> Git.Workflow.chain(config: config)

Integration, release, and collaboration:

# Sync with upstream (fetch + rebase, with autostash)
Git.Workflow.sync(config: config)

# Rebase / merge that rolls back cleanly on conflict
Git.Workflow.safe_rebase(config: config)
Git.Workflow.try_merge("feature-branch", config: config)

# Squash merge a branch
Git.Workflow.squash_merge("feature-branch", message: "feat: all the things", config: config)

# Cut a release, publish the current branch, sync a fork, backport commits
Git.Workflow.release("v1.2.0", config: config)
Git.Workflow.publish(config: config)
Git.Workflow.sync_fork(config: config)
Git.Workflow.backport(["abc1234"], config: config)

# Recreate a branch that was deleted (from the reflog)
Git.Workflow.restore_branch("feat/lost", config: config)

Git.History

Query commit history:

{:ok, commits} = Git.History.commits_between("v1.0.0", "v2.0.0", config: config)
{:ok, changelog} = Git.History.changelog("v1.0.0", "v2.0.0", config: config)
# changelog.features, changelog.fixes, changelog.other

{:ok, contributors} = Git.History.contributors(path: "lib/", config: config)
{:ok, true} = Git.History.ancestor?("v1.0.0", "main", config: config)

Git.Changes

Analyze repository changes:

{:ok, changes} = Git.Changes.between("HEAD~5", "HEAD", config: config)
# [%{status: :modified, path: "lib/foo.ex"}, %{status: :added, path: "lib/bar.ex"}]

{:ok, uncommitted} = Git.Changes.uncommitted(config: config)
# uncommitted.staged, uncommitted.modified, uncommitted.untracked

{:ok, conflicts} = Git.Changes.conflicts(config: config)

Git.Info

Repository introspection:

{:ok, summary} = Git.Info.summary(config: config)
# summary.branch, summary.commit, summary.dirty, summary.ahead, summary.behind, ...

{:ok, true} = Git.Info.dirty?(config: config)
{:ok, head} = Git.Info.head(config: config)
{:ok, root} = Git.Info.root(config: config)

Git.Search

Search content and history:

{:ok, results} = Git.Search.grep("TODO", config: config)
# [%Git.GrepResult{file: "lib/foo.ex", line_number: 42, content: "# TODO: refactor"}]

{:ok, commits} = Git.Search.commits("fix:", config: config)
{:ok, commits} = Git.Search.pickaxe("my_function", config: config)
{:ok, files} = Git.Search.files("*.ex", config: config)

Git.Branches

Branch management:

{:ok, "main"} = Git.Branches.current(config: config)
{:ok, true} = Git.Branches.exists?("feat/login", config: config)
{:ok, merged} = Git.Branches.merged(config: config)
{:ok, deleted} = Git.Branches.cleanup_merged(exclude: ["main", "develop"], config: config)
{:ok, %{ahead: 3, behind: 0}} = Git.Branches.divergence("feat/x", "main", config: config)
{:ok, recent} = Git.Branches.recent(count: 5, config: config)

# Delete a branch; prune locals whose upstream is gone; find squash-merged branches
{:ok, :done} = Git.Branches.delete_branch("feat/done", config: config)
{:ok, pruned} = Git.Branches.prune_gone(config: config)
{:ok, would_delete} = Git.Branches.delete_squashed(target: "main", config: config)  # dry-run by default
{:ok, deleted} = Git.Branches.delete_squashed(target: "main", dry_run: false, config: config)

Git.Tags

Tag management:

{:ok, :done} = Git.Tags.create("v1.0.0", message: "Release 1.0.0", config: config)
{:ok, tags} = Git.Tags.list(config: config)
{:ok, "v1.0.0"} = Git.Tags.latest(config: config)
{:ok, sorted} = Git.Tags.sorted(config: config)  # version-sorted
{:ok, true} = Git.Tags.exists?("v1.0.0", config: config)
{:ok, :done} = Git.Tags.delete("v0.1.0", config: config)

Git.Remotes

Remote management:

{:ok, remotes} = Git.Remotes.list_detailed(config: config)
{:ok, :done} = Git.Remotes.add("upstream", "https://github.com/upstream/repo.git", config: config)
{:ok, :done} = Git.Remotes.set_url("origin", "git@github.com:me/repo.git", config: config)
{:ok, :done} = Git.Remotes.prune("origin", config: config)
{:ok, :done} = Git.Remotes.remove("upstream", config: config)

Git.Stashes

Stash management:

{:ok, _} = Git.Stashes.save("work in progress", config: config)
{:ok, stashes} = Git.Stashes.list(config: config)
{:ok, _} = Git.Stashes.apply(config: config)
{:ok, _} = Git.Stashes.pop(config: config)
{:ok, :done} = Git.Stashes.drop(config: config)
{:ok, :done} = Git.Stashes.clear(config: config)

Git.Patch

Patch creation and application:

{:ok, files} = Git.Patch.create("HEAD~3", output_directory: "/tmp/patches", config: config)
{:ok, :done} = Git.Patch.check("/tmp/patches/0001-fix.patch", config: config)
{:ok, :done} = Git.Patch.apply("/tmp/patches/0001-fix.patch", config: config)
{:ok, :done} = Git.Patch.apply_mailbox(["0001-fix.patch", "0002-feat.patch"], config: config)

Git.Conflicts

Merge conflict helpers:

{:ok, false} = Git.Conflicts.detect(config: config)
{:ok, files} = Git.Conflicts.files(config: config)
{:ok, true} = Git.Conflicts.resolved?(config: config)

# Inspect the three sides of a conflicted path
{:ok, base} = Git.Conflicts.base("shared.txt", config: config)
{:ok, ours} = Git.Conflicts.ours("shared.txt", config: config)
{:ok, theirs} = Git.Conflicts.theirs("shared.txt", config: config)

# Resolve by taking one side (single path or a list), then it is staged for you
{:ok, :done} = Git.Conflicts.take_ours("shared.txt", config: config)
{:ok, :done} = Git.Conflicts.take_theirs(["a.txt", "b.txt"], config: config)
{:ok, :done} = Git.Conflicts.resolve("shared.txt", using: :ours, config: config)

# Abort or continue whatever operation is in progress (merge/rebase/cherry-pick/revert)
{:ok, :done} = Git.Conflicts.abort(config: config)
{:ok, _} = Git.Conflicts.continue(config: config)

Git.Hooks

Manage git hooks:

{:ok, hooks} = Git.Hooks.list(config: config)
{:ok, path} = Git.Hooks.write("pre-commit", "#!/bin/sh\nmix format --check-formatted", config: config)
{:ok, true} = Git.Hooks.enabled?("pre-commit", config: config)
{:ok, _} = Git.Hooks.disable("pre-commit", config: config)
:ok = Git.Hooks.remove("pre-commit", config: config)

Git.Signing

Configure commit and tag signing (sets the relevant git config keys):

# SSH signing (sets gpg.format=ssh, user.signingkey, commit.gpgsign=true)
{:ok, :done} = Git.Signing.use_ssh("/home/me/.ssh/id_ed25519.pub", config: config)

# GPG signing by key id
{:ok, :done} = Git.Signing.use_gpg("ABCD1234", config: config)

# Also sign annotated tags by default
{:ok, :done} = Git.Signing.sign_tags(true, config: config)

The actual signing happens when a commit, tag, or merge is created. Once the config above is set, Git.commit/2, Git.tag/1, and Git.merge/2 sign automatically, or you can request it per call with :sign / :gpg_sign / :local_user:

{:ok, _} = Git.commit("feat: signed change", sign: true, config: config)
{:ok, :done} = Git.tag(create: "v1.0.0", message: "release", sign: true, config: config)

License

MIT