reflog¶

For git-reflog(1).

Overview¶

Manage git reflog using GitReflogManager (collection-level) and GitReflogEntryCmd (per-entry operations).

Example¶

from libvcs.cmd.git import Git

git = Git(path='/path/to/repo')

# List reflog entries
entries = git.reflog.ls()

# List entries for a specific ref
head_entries = git.reflog.ls(ref='HEAD')

# Check if reflog exists for a ref
git.reflog.exists(ref='main')

# Expire old reflog entries
git.reflog.expire(ref='HEAD', expire='90.days.ago')

API Reference¶

class libvcs.cmd.git.GitReflogManager
¶
class[source]

Bases: object

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

__init__(*, path, cmd=None)
¶
method[source]

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

Parameters:

  • path (StrPath) – Operates as PATH in the corresponding git subcommand.

  • cmd (Git | None)

Return type:

None

Examples

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

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

>>> len(GitReflogManager(path=example_git_repo.path).run('show')) > 0
True
path: Path
¶
attribute

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]

Run a command against a git repository’s reflog.

Wraps git reflog.

Parameters:

  • command (GitReflogCommandLiteral | None) – Reflog command to run.

  • local_flags (list[str] | None) – Additional flags to pass.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Return type:

str

Examples

>>> len(GitReflogManager(path=example_git_repo.path).run('show')) > 0
True
show(ref='HEAD', *, number=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Show reflog for a ref.

Parameters:

  • ref (str) – Reference to show reflog for (default: HEAD).

  • number (int | None) – Limit number of entries to show.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitReflogManager(path=example_git_repo.path).show()
>>> len(result) > 0
True

>>> result = GitReflogManager(path=example_git_repo.path).show(number=5)
>>> len(result) > 0
True
expire(*, expire=None, expire_unreachable=None, rewrite=False, updateref=False, stale_fix=False, dry_run=False, verbose=False, all_refs=False, single_worktree=False, refs=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Expire old reflog entries.

Parameters:

  • expire (str | None) – Expire entries older than this time.

  • expire_unreachable (str | None) – Expire unreachable entries older than this time.

  • rewrite (bool) – Adjust reflog entries as old entries are pruned.

  • updateref (bool) – Update ref to pruned value.

  • stale_fix (bool) – Prune stale git-hierarchies too.

  • dry_run (bool) – Don’t actually prune, just report.

  • verbose (bool) – Print extra information.

  • all_refs (bool) – Process reflogs of all refs.

  • single_worktree (bool) – Only process reflogs for current worktree.

  • refs (list[str] | None) – Specific refs to expire.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitReflogManager(path=example_git_repo.path).expire(
...     dry_run=True
... )
>>> 'error' in result.lower() or result == ''
True
exists(ref, *, log_in_real_time=False, check_returncode=None)
¶
method[source]

Check if a reflog exists for a ref.

Parameters:

  • ref (str) – Reference to check.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Returns:

True if reflog exists, False otherwise.

Return type:

bool

Examples

>>> GitReflogManager(path=example_git_repo.path).exists('HEAD')
True

>>> GitReflogManager(path=example_git_repo.path).exists(
...     'refs/heads/nonexistent-branch-xyz123456'
... )
False
_ls(ref='HEAD', *, number=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Parse reflog output into structured data.

Parameters:

  • ref (str) – Reference to list reflog for.

  • number (int | None) – Limit number of entries.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Returns:

List of parsed reflog entries.

Return type:

list[dict[str, str]]

Examples

>>> entries = GitReflogManager(path=example_git_repo.path)._ls()
>>> len(entries) > 0
True
ls(ref='HEAD', *, number=None)
¶
method[source]

List reflog entries as GitReflogEntry objects.

Parameters:

  • ref (str) – Reference to list reflog for.

  • number (int | None) – Limit number of entries.

Returns:

List of reflog entries with ORM-like filtering.

Return type:

QueryList[GitReflogEntry]

Examples

>>> entries = GitReflogManager(path=example_git_repo.path).ls()
>>> isinstance(entries, QueryList)
True
>>> len(entries) > 0
True
get(refspec=None, sha=None, **kwargs)
¶
method[source]

Get a specific reflog entry.

Parameters:

  • refspec (str | None) – Reference specification to find.

  • sha (str | None) – SHA to find.

  • **kwargs (Any) – Additional filter criteria.

Returns:

The matching reflog entry.

Return type:

GitReflogEntry

Raises:

Examples

>>> entry = GitReflogManager(path=example_git_repo.path).get(
...     refspec='HEAD@{0}'
... )
>>> entry.refspec
'HEAD@{0}'
filter(*args, **kwargs)
¶
method[source]

Filter reflog entries.

Parameters:

  • *args (Any) – Positional arguments for QueryList.filter().

  • **kwargs (Any) – Keyword arguments for filtering (supports Django-style lookups).

Returns:

Filtered list of reflog entries.

Return type:

QueryList[GitReflogEntry]

Examples

>>> entries = GitReflogManager(path=example_git_repo.path).filter(
...     action='commit'
... )
>>> isinstance(entries, QueryList)
True
class libvcs.cmd.git.GitReflogEntryCmd
¶
class[source]

Bases: object

Run git commands targeting a specific reflog entry.

__init__(*, path, refspec, cmd=None)
¶
method[source]

Wrap some of git-reflog(1) for specific entry operations.

Parameters:

  • path (StrPath) – Operates as PATH in the corresponding git subcommand.

  • refspec (str) – Reference specification (e.g., HEAD@{0}, master@{2}).

  • cmd (Git | None)

Return type:

None

Examples

>>> GitReflogEntryCmd(
...     path=example_git_repo.path,
...     refspec='HEAD@{0}',
... )
<GitReflogEntryCmd HEAD@{0}>
path: Path
¶
attribute

Directory to check out

run(command=None, local_flags=None, *, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]

Run a command against a specific reflog entry.

Wraps git reflog.

Parameters:

  • command (GitReflogCommandLiteral | None) – Reflog command to run.

  • local_flags (list[str] | None) – Additional flags to pass.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Return type:

str

Examples

>>> GitReflogEntryCmd(
...     path=example_git_repo.path,
...     refspec='HEAD@{0}',
... ).run('show')
'...'
show(*, log_in_real_time=False, check_returncode=None)
¶
method[source]

Show this reflog entry.

Examples

>>> result = GitReflogEntryCmd(
...     path=example_git_repo.path,
...     refspec='HEAD@{0}',
... ).show()
>>> len(result) > 0
True
Parameters:
Return type:

str

delete(*, rewrite=False, updateref=False, dry_run=False, verbose=False, log_in_real_time=False, check_returncode=None)
¶
method[source]

Delete this reflog entry.

Parameters:

  • rewrite (bool) – Adjust subsequent entries to compensate.

  • updateref (bool) – Update the ref to the value of the prior entry.

  • dry_run (bool) – Don’t actually delete, just show what would be deleted.

  • verbose (bool) – Print extra information.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> result = GitReflogEntryCmd(
...     path=example_git_repo.path,
...     refspec='HEAD@{0}',
... ).delete(dry_run=True)
>>> 'error' in result.lower() or result == ''
True
class libvcs.cmd.git.GitReflogEntry
¶
class[source]

Bases: object

Represent a git reflog entry.

__init__(sha, refspec, action, message, _cmd=None)
¶
method[source]
Parameters:
Return type:

None

sha: str
¶
attribute

Commit SHA.

refspec: str
¶
attribute

Reference specification (e.g., HEAD@{0}).

action: str
¶
attribute

Action performed (e.g., commit, checkout, merge).

message: str
¶
attribute

Commit/action message.

_cmd: GitReflogEntryCmd | None = None
¶
attribute

Internal: GitReflogEntryCmd for operations on this entry

property cmd: GitReflogEntryCmd
¶
property

Return command object for this reflog entry.