# `Git.Commands.Worktree`
[🔗](https://github.com/joshrotenberg/git_wrapper_ex/blob/main/lib/git/commands/worktree.ex#L1)

Implements the `Git.Command` behaviour for `git worktree`.

Supports listing worktrees (default), adding a new worktree, removing,
moving, unlocking, repairing, and pruning worktrees. List output is
always parsed from `--porcelain` format for reliable structured data.

When adding with a new branch (`:add_new_branch`), `:start_point` names the
commit-ish the branch starts from; `:add_branch` alone checks out an existing
branch. `:repair` (with no directory noise) is the companion to `:prune` for
recovering worktrees whose administrative files moved.

# `t`

```elixir
@type t() :: %Git.Commands.Worktree{
  add_branch: String.t() | nil,
  add_new_branch: String.t() | nil,
  add_path: String.t() | nil,
  detach: boolean(),
  expire: String.t() | nil,
  force: boolean(),
  list: boolean(),
  lock: boolean(),
  move: {String.t(), String.t()} | nil,
  porcelain: boolean(),
  prune: boolean(),
  remove_path: String.t() | nil,
  repair: boolean(),
  start_point: String.t() | nil,
  unlock: String.t() | nil
}
```

# `args`

```elixir
@spec args(t()) :: [String.t()]
```

Returns the argument list for `git worktree`.

- If `:add_path` is set, builds `git worktree add [options] <path> [<commit-ish>]`.
- If `:remove_path` is set, builds `git worktree remove [--force] <path>`.
- If `:move` is a `{from, to}` tuple, builds `git worktree move [--force] <from> <to>`.
- If `:unlock` is set, builds `git worktree unlock <path>`.
- If `:repair` is true, builds `git worktree repair`.
- If `:prune` is true, builds `git worktree prune [--expire <time>]`.
- Otherwise, lists worktrees with `git worktree list --porcelain`.

## Examples

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{})
    ["worktree", "list", "--porcelain"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{add_path: "/tmp/wt", add_branch: "main"})
    ["worktree", "add", "/tmp/wt", "main"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{add_path: "/tmp/wt", add_new_branch: "feat", start_point: "main"})
    ["worktree", "add", "-b", "feat", "/tmp/wt", "main"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{remove_path: "/tmp/wt", force: true})
    ["worktree", "remove", "--force", "/tmp/wt"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{move: {"/tmp/wt", "/tmp/moved"}})
    ["worktree", "move", "/tmp/wt", "/tmp/moved"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{unlock: "/tmp/wt"})
    ["worktree", "unlock", "/tmp/wt"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{repair: true})
    ["worktree", "repair"]

    iex> Git.Commands.Worktree.args(%Git.Commands.Worktree{prune: true, expire: "now"})
    ["worktree", "prune", "--expire", "now"]

# `parse_output`

```elixir
@spec parse_output(String.t(), non_neg_integer()) ::
  {:ok, [Git.Worktree.t()]}
  | {:ok, :done}
  | {:error, {String.t(), non_neg_integer()}}
```

Parses the output of `git worktree`.

For list operations (exit 0), parses porcelain output into a list of
`Git.Worktree` structs. For add/remove/prune operations (exit 0),
returns `{:ok, :done}`. On failure, returns `{:error, {stdout, exit_code}}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*