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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Get tag via filter lookup.

Return type:

GitTagCmd | None

Parameters:

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)[source]¶

Get tags via filter lookup.

Return type:

list[GitTagCmd]

Parameters:

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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
...