Git.Tags (git v0.4.0)

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.

Summary

Functions

create(name, opts \\ [])

Creates a tag.

delete(name, opts \\ [])

Deletes a tag.

exists?(name, opts \\ [])

Checks whether a tag exists.

latest(opts \\ [])

Returns the most recent tag reachable from HEAD.

list(opts \\ [])

Lists all tags with detailed information.

sorted(opts \\ [])

Returns tags sorted by semantic version.

Functions

create(name, opts \\ [])

@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(name, opts \\ [])

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

Deletes a tag.

Delegates to Git.tag(delete: name).

Returns {:ok, :done} on success.

exists?(name, opts \\ [])

@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(opts \\ [])

@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(opts \\ [])

@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(opts \\ [])

@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()]}.