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

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

Describes a commit using the most recent tag reachable from it.
Supports various formatting options for the description output.

# `t`

```elixir
@type t() :: %Git.Commands.Describe{
  abbrev: non_neg_integer() | nil,
  all: boolean(),
  always: boolean(),
  broken: boolean(),
  candidates: non_neg_integer() | nil,
  dirty: boolean() | String.t(),
  exact_match: boolean(),
  exclude: String.t() | nil,
  first_parent: boolean(),
  long: boolean(),
  match: String.t() | nil,
  ref: String.t() | nil,
  tags: boolean()
}
```

# `args`

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

Returns the argument list for `git describe`.

## Examples

    iex> Git.Commands.Describe.args(%Git.Commands.Describe{})
    ["describe"]

    iex> Git.Commands.Describe.args(%Git.Commands.Describe{tags: true, always: true})
    ["describe", "--tags", "--always"]

    iex> Git.Commands.Describe.args(%Git.Commands.Describe{abbrev: 4, long: true})
    ["describe", "--long", "--abbrev=4"]

    iex> Git.Commands.Describe.args(%Git.Commands.Describe{dirty: true})
    ["describe", "--dirty"]

    iex> Git.Commands.Describe.args(%Git.Commands.Describe{dirty: "-modified"})
    ["describe", "--dirty=-modified"]

# `parse_output`

```elixir
@spec parse_output(String.t(), non_neg_integer()) ::
  {:ok, String.t()} | {:error, {String.t(), non_neg_integer()}}
```

Parses the output of `git describe`.

On success (exit code 0), returns `{:ok, description}` where `description`
is the trimmed output string. On failure, returns
`{:error, {stdout, exit_code}}`.

---

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