Tak.Worktrees (tak v0.4.2)

View Source

Public runtime API for Tak worktree lifecycle operations.

The supported surface is intentionally small:

  • create/3 creates a worktree and returns %Tak.Worktree{} data
  • list/0 reports the main repo and known worktrees with runtime status
  • remove/2 removes a worktree and returns %Tak.RemoveResult{} data
  • doctor/0 returns structured environment checks for CLI rendering

Tak uses three public data shapes:

Summary

Functions

create(branch, name, opts \\ [])

Creates a worktree. Returns {:ok, %Tak.Worktree{}} or {:error, reason}.

doctor()

Runs doctor checks. Returns {passed, failed, results} where results is a list of {:ok | :error | :warn, message} tuples.

list()

Lists the main repository and all known worktrees.

remove(name, opts \\ [])

Removes a worktree. Returns {:ok, %Tak.RemoveResult{}} or {:error, reason}.

Functions

create(branch, name, opts \\ [])

Creates a worktree. Returns {:ok, %Tak.Worktree{}} or {:error, reason}.

When name is nil, the first available slot is picked automatically.

The core API does not raise for expected git or mix command failures. Those return tagged errors instead:

  • {:git_failed, command, output}
  • {:bootstrap_failed, command, output}
  • {:bootstrap_failed, command, output, :cleanup_failed}

Options

  • :create_db - whether to create the database (default: from config)

doctor()

Runs doctor checks. Returns {passed, failed, results} where results is a list of {:ok | :error | :warn, message} tuples.

list()

Lists the main repository and all known worktrees.

Returns {main, worktrees} where main is a %Tak.WorktreeStatus{} for the current repository and worktrees is a list of %Tak.WorktreeStatus{} values for entries found in Tak.trees_dir/0.

Status is :running, :stopped, or :unknown.

remove(name, opts \\ [])

Removes a worktree. Returns {:ok, %Tak.RemoveResult{}} or {:error, reason}.

Options

  • :force - force removal even with uncommitted changes (default: false)
  • :keep_db - keep the database instead of dropping it (default: false)