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

Higher-level stash management operations that compose the lower-level
`Git.stash/1` command.

All functions accept an optional keyword list. Use `:config` to specify the
repository via a `Git.Config` struct; when omitted a default config is built
from the environment.

# `apply`

```elixir
@spec apply(keyword()) :: {:ok, :done} | {:error, term()}
```

Applies the latest stash (or a specific stash by index) without removing it.

Uses raw `git stash apply` since the underlying command module does not
support the apply subcommand directly.

## Options

  * `:config` - a `Git.Config` struct
  * `:index` - stash index to apply (e.g., `1` for `stash@{1}`)

## Examples

    {:ok, :done} = Git.Stashes.apply()
    {:ok, :done} = Git.Stashes.apply(index: 2)

# `clear`

```elixir
@spec clear(keyword()) :: {:ok, :done} | {:error, term()}
```

Clears all stash entries.

Uses raw `git stash clear` since the underlying command module does not
support the clear subcommand directly.

## Options

  * `:config` - a `Git.Config` struct

## Examples

    {:ok, :done} = Git.Stashes.clear()

# `drop`

```elixir
@spec drop(keyword()) :: {:ok, :done} | {:error, term()}
```

Drops a specific stash entry.

Delegates to `Git.stash(drop: true)`.

## Options

  * `:config` - a `Git.Config` struct
  * `:index` - stash index to drop (e.g., `1` for `stash@{1}`)

## Examples

    {:ok, :done} = Git.Stashes.drop()
    {:ok, :done} = Git.Stashes.drop(index: 1)

# `list`

```elixir
@spec list(keyword()) :: {:ok, [Git.StashEntry.t()]} | {:error, term()}
```

Lists all stash entries.

Delegates to `Git.stash(list: true)`.

## Options

  * `:config` - a `Git.Config` struct

## Examples

    {:ok, entries} = Git.Stashes.list()

# `pop`

```elixir
@spec pop(keyword()) :: {:ok, :done} | {:error, term()}
```

Pops the latest stash entry, applying it and removing it from the stash list.

Delegates to `Git.stash(pop: true)`.

## Options

  * `:config` - a `Git.Config` struct

## Examples

    {:ok, :done} = Git.Stashes.pop()

# `save`

```elixir
@spec save(
  String.t(),
  keyword()
) :: {:ok, :done} | {:error, term()}
```

Saves current changes to the stash with a message.

Delegates to `Git.stash(save: true, message: message)`.

## Options

  * `:config` - a `Git.Config` struct

## Examples

    {:ok, :done} = Git.Stashes.save("work in progress")

---

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