tag

For git-tag(1).

Overview

Manage git tags using GitTagManager (collection-level) and GitTagCmd (per-tag operations).

Example

from libvcs.cmd.git import Git git = Git(path='/path/to/repo') # Create a tag git.tags.create(name='v1.0.0', message='Release 1.0.0') # List all tags tags = git.tags.ls() # Filter tags release_tags = git.tags.ls(pattern='v*') # Get a specific tag and operate on it tag = git.tags.get(tag_name='v1.0.0') tag.show() tag.delete() 

API Reference

class libvcs.cmd.git.GitTagManager(*, path, cmd=None)

Bases: object

Traverse and manage git tags with ORM-like filtering via QueryList.

Wrap some of git-tag(1), manager.

Parameters:

• path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

• cmd (Git | None)

Examples

>>> GitTagManager(path=tmp_path) <GitTagManager path=...> 

>>> GitTagManager(path=tmp_path).run() 'fatal: not a git repository (or any of the parent directories): .git' 

>>> mgr = GitTagManager(path=example_git_repo.path) >>> mgr.create(name='init-doctest-tag', message='For doctest') '' >>> mgr.run() '...init-doctest-tag...' 

__init__(*, path, cmd=None)

Wrap some of git-tag(1), manager.

Parameters:

• path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

• cmd (Git | None)

Return type:

None

Examples

>>> GitTagManager(path=tmp_path) <GitTagManager path=...> 

>>> GitTagManager(path=tmp_path).run() 'fatal: not a git repository (or any of the parent directories): .git' 

>>> mgr = GitTagManager(path=example_git_repo.path) >>> mgr.create(name='init-doctest-tag', message='For doctest') '' >>> mgr.run() '...init-doctest-tag...' 

path: Path

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

Run a command against a git repository’s tags.

Wraps git tag.

Return type:

str

Parameters:

• command (Literal['list', 'create', 'delete', 'verify'] | None)

• local_flags (list[str] | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Examples

>>> mgr = GitTagManager(path=example_git_repo.path) >>> mgr.create(name='run-doctest-tag', message='For doctest') '' >>> mgr.run() '...run-doctest-tag...' 

create(*, name, ref=None, message=None, annotate=None, sign=None, local_user=None, force=None, file=None, log_in_real_time=False, check_returncode=None)

Git tag create.

Parameters:

• name (str) – Name of the tag to create

• ref (str | None) – Git reference (commit, branch) to tag. Defaults to HEAD.

• message (str | None) – Tag message (implies annotated tag)

• annotate (bool | None) – Create an annotated tag

• sign (bool | None) – Create a GPG-signed tag

• local_user (str | None) – Use specific GPG key for signing

• force (bool | None) – Replace existing tag

• file (str | PathLike[str] | None) – Read message from file

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

Examples

Create a lightweight tag:

>>> GitTagManager(path=example_git_repo.path).create(name='lightweight-tag') '' 

Create an annotated tag:

>>> GitTagManager(path=example_git_repo.path).create( ...  name='annotated-tag', message='This is an annotated tag' ... ) '' 

Create a tag on a specific commit:

>>> GitTagManager(path=example_git_repo.path).create( ...  name='ref-tag', ref='HEAD', message='Tag at HEAD' ... ) '' 

_ls(*, pattern=None, sort=None, contains=None, no_contains=None, merged=None, no_merged=None, lines=None)

List tags (raw output).

Return type:

list[str]

Parameters:

• pattern (str | None)

• sort (str | None)

• contains (str | None)

• no_contains (str | None)

• merged (str | None)

• no_merged (str | None)

• lines (int | None)

Examples

>>> GitTagManager(path=example_git_repo.path).create( ...  name='list-tag-1', message='First tag' ... ) '' >>> GitTagManager(path=example_git_repo.path).create( ...  name='list-tag-2', message='Second tag' ... ) '' >>> 'list-tag-1' in GitTagManager(path=example_git_repo.path)._ls() True 

ls(*, pattern=None, sort=None, contains=None, no_contains=None, merged=None, no_merged=None)

List tags.

Parameters:

• pattern (str | None) – List tags matching pattern (shell wildcard)

• sort (str | None) – Sort by key (e.g., ‘version:refname’, ‘-creatordate’)

• contains (str | None) – Only tags containing the specified commit

• no_contains (str | None) – Only tags not containing the specified commit

• merged (str | None) – Only tags merged into the specified commit

• no_merged (str | None) – Only tags not merged into the specified commit

Return type:

QueryList[GitTagCmd]

Examples

>>> GitTagManager(path=example_git_repo.path).create( ...  name='ls-tag', message='Listing tag' ... ) '' >>> tags = GitTagManager(path=example_git_repo.path).ls() >>> any(t.tag_name == 'ls-tag' for t in tags) True 

get(*args, **kwargs)

Get tag via filter lookup.

Return type:

GitTagCmd | None

Parameters:

• args (Any)

• kwargs (Any)

Examples

Create a tag first:

>>> GitTagManager(path=example_git_repo.path).create( ...  name='get-tag', message='Get this tag' ... ) '' 

>>> GitTagManager( ...  path=example_git_repo.path ... ).get(tag_name='get-tag') <GitTagCmd path=... tag_name=get-tag> 

>>> GitTagManager( ...  path=example_git_repo.path ... ).get(tag_name='unknown') Traceback (most recent call last):  exec(compile(example.source, filename, "single",  ...  return self.ls().get(*args, **kwargs)  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  File "..._internal/query_list.py", line ..., in get  raise ObjectDoesNotExist libvcs._internal.query_list.ObjectDoesNotExist 

filter(*args, **kwargs)

Get tags via filter lookup.

Return type:

list[GitTagCmd]

Parameters:

• args (Any)

• kwargs (Any)

Examples

>>> GitTagManager(path=example_git_repo.path).create( ...  name='filter-tag-a', message='Filter tag A' ... ) '' >>> GitTagManager(path=example_git_repo.path).create( ...  name='filter-tag-b', message='Filter tag B' ... ) '' 

>>> len(GitTagManager( ...  path=example_git_repo.path ... ).filter(tag_name__contains='filter-tag')) >= 2 True 

>>> GitTagManager( ...  path=example_git_repo.path ... ).filter(tag_name__contains='unknown') [] 

class libvcs.cmd.git.GitTagCmd(*, path, tag_name, cmd=None)

Bases: object

Run git commands targeting a specific tag.

Lite, typed, pythonic wrapper for git-tag(1).

Parameters:

• path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

• tag_name (str) – Name of tag

• cmd (Git | None)

Examples

>>> GitTagCmd( ...  path=example_git_repo.path, ...  tag_name='v1.0.0', ... ) <GitTagCmd path=... tag_name=v1.0.0> 

__init__(*, path, tag_name, cmd=None)

Lite, typed, pythonic wrapper for git-tag(1).

Parameters:

• path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

• tag_name (str) – Name of tag

• cmd (Git | None)

Return type:

None

Examples

>>> GitTagCmd( ...  path=example_git_repo.path, ...  tag_name='v1.0.0', ... ) <GitTagCmd path=... tag_name=v1.0.0> 

path: Path

Directory to check out

tag_name: str

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)

Run command against a git tag.

Wraps git tag.

Return type:

str

Parameters:

• command (Literal['list', 'create', 'delete', 'verify'] | None)

• local_flags (list[str] | None)

• log_in_real_time (bool)

• check_returncode (bool | None)

• kwargs (Any)

Examples

>>> GitTagManager(path=example_git_repo.path).create( ...  name='test-tag', message='Test tag' ... ) '' >>> GitTagCmd( ...  path=example_git_repo.path, ...  tag_name='test-tag', ... ).run() '...test-tag...' 

delete(*, log_in_real_time=False, check_returncode=None)

Git tag delete.

Return type:

str

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Examples

Create a tag first:

>>> GitTagManager(path=example_git_repo.path).create( ...  name='delete-me', message='Tag to delete' ... ) '' 

Now delete it:

>>> GitTagCmd( ...  path=example_git_repo.path, ...  tag_name='delete-me', ... ).delete() "Deleted tag 'delete-me'..." 

verify(*, log_in_real_time=False, check_returncode=None)

Git tag verify.

Verify a GPG-signed tag.

Return type:

str

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Examples

First create a lightweight tag:

>>> GitTagManager(path=example_git_repo.path).create(name='verify-tag') '' 

Try to verify it (lightweight tags can’t be verified):

>>> GitTagCmd( ...  path=example_git_repo.path, ...  tag_name='verify-tag', ... ).verify() 'error: verify-tag: cannot verify a non-tag object...' 

show(*, log_in_real_time=False, check_returncode=None)

Show tag details using git show.

Return type:

str

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Examples

Create an annotated tag first:

>>> GitTagManager(path=example_git_repo.path).create( ...  name='show-tag', message='Show this tag' ... ) '' 

Show the tag:

>>> print(GitTagCmd( ...  path=example_git_repo.path, ...  tag_name='show-tag', ... ).show()) tag show-tag Tagger: ... Show this tag ...