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

Higher-level tag management helpers that compose lower-level `Git` functions.

Provides convenience functions for creating, listing, sorting, and querying
tags.

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.

# `create`

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

Creates a tag.

Delegates to `Git.tag/1` with the `:create` option. Supports `:message`
for annotated tags and `:ref` for tagging a specific commit.

## Options

  * `:message` - annotation message (creates an annotated tag)
  * `:ref` - commit to tag (default: HEAD)
  * `:config` - a `Git.Config` struct

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

# `delete`

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

Deletes a tag.

Delegates to `Git.tag(delete: name)`.

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

# `exists?`

```elixir
@spec exists?(
  String.t(),
  keyword()
) :: {:ok, boolean()} | {:error, term()}
```

Checks whether a tag exists.

Lists all tags and checks if the given name is present.

Returns `{:ok, true}` or `{:ok, false}`.

# `latest`

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

Returns the most recent tag reachable from HEAD.

Uses `Git.describe(tags: true, abbrev: 0)` to find the latest tag.

Returns `{:ok, String.t()}` with the tag name, or `{:error, term()}` if
no tags exist.

# `list`

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

Lists all tags with detailed information.

Delegates to `Git.tag/1` with no create/delete options.

Returns `{:ok, [Git.Tag.t()]}`.

# `sorted`

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

Returns tags sorted by semantic version.

Lists all tags, then sorts them using `Version.parse/1` where possible.
Tags that are not valid semver are sorted lexicographically and placed
after the versioned tags.

Returns `{:ok, [Git.Tag.t()]}`.

---

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