# `Git.Workflow`
[🔗](https://github.com/joshrotenberg/git_wrapper_ex/blob/main/lib/git/workflow.ex#L1)

Composable helpers for common multi-step git workflows.

Each function orchestrates several lower-level `Git` commands into a
single logical operation. All functions accept a keyword list where the
`:config` key, when present, must be a `Git.Config` struct and is
forwarded to every underlying git invocation.

## Examples

    # Stage everything and commit in one call
    {:ok, result} = Git.Workflow.commit_all("feat: ship it", config: cfg)

    # Work on a feature branch, then return to the original branch
    {:ok, result} = Git.Workflow.feature_branch("feat/cool", fn opts ->
      File.write!("cool.txt", "cool")
      {:ok, :done} = Git.add(files: ["cool.txt"], config: opts[:config])
      {:ok, _} = Git.commit("feat: cool", Keyword.take(opts, [:config]))
      {:ok, :worked}
    end, merge: true, config: cfg)

# `amend`

```elixir
@spec amend(keyword()) :: {:ok, Git.CommitResult.t()} | {:error, term()}
```

Amends the last commit.

When no `:message` is provided, the existing commit message is reused.
When `:all` is `true`, all changes are staged before amending.

## Options

  * `:message` - new commit message (default: reuse existing message)
  * `:all` - stage all changes before amending (default `false`)
  * `:config` - a `Git.Config` struct

Returns `{:ok, commit_result}` on success.

# `commit_all`

```elixir
@spec commit_all(
  String.t(),
  keyword()
) :: {:ok, Git.CommitResult.t()} | {:error, term()}
```

Stages all changes and commits with the given message.

Any additional keyword options (e.g., `:allow_empty`) are forwarded to
`Git.commit/2`.

## Options

  * `:config` - a `Git.Config` struct
  * All other options are passed to `Git.commit/2`.

Returns `{:ok, commit_result}` on success.

# `feature_branch`

```elixir
@spec feature_branch(
  String.t(),
  (keyword() -> {:ok, term()} | {:error, term()}),
  keyword()
) ::
  {:ok, term()} | {:error, term()}
```

Creates a feature branch, runs a function on it, and returns to the original
branch.

The function `fun` receives a keyword list containing the `:config` key
(when one was provided in `opts`). It must return `{:ok, result}` or
`{:error, reason}`.

After `fun` completes (successfully or not), the original branch is checked
out to ensure cleanup.

## Options

  * `:merge` - when `true`, merge the feature branch back into the original
    branch after `fun` succeeds (default `false`)
  * `:delete` - when `true`, delete the feature branch after a successful
    merge (default `false`; requires `:merge` to be `true`)
  * `:config` - a `Git.Config` struct

Returns `{:ok, result}` where `result` is the return value of `fun`, or
the merge result when `:merge` is `true`.

# `squash_merge`

```elixir
@spec squash_merge(
  String.t(),
  keyword()
) :: {:ok, Git.CommitResult.t()} | {:error, term()}
```

Merges a branch with `--squash` and commits with the given message.

## Options

  * `:message` - commit message (required)
  * `:delete` - when `true`, delete the source branch after merge
    (default `false`)
  * `:config` - a `Git.Config` struct

Returns `{:ok, commit_result}` on success.

# `sync`

```elixir
@spec sync(keyword()) :: {:ok, :synced} | {:error, term()}
```

Fetches from a remote and integrates changes using rebase or merge.

## Options

  * `:strategy` - `:rebase` (default) or `:merge`
  * `:autostash` - stash uncommitted changes before syncing and pop after
    (default `true`)
  * `:remote` - remote name (default `"origin"`)
  * `:branch` - branch to sync with (defaults to the upstream tracking branch)
  * `:config` - a `Git.Config` struct

Returns `{:ok, :synced}` on success.

---

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