reflog

For git-reflog(1).

Overview

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

Examples

List reflog entries and look one up by refspec:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> entries = git.reflog.ls()
>>> len(entries) >= 1
True
>>> entry = git.reflog.get(refspec='HEAD@{0}')
>>> entry.refspec
'HEAD@{0}'

Check whether a ref has a reflog:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.reflog.exists('HEAD')
True

Expire old reflog entries:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.reflog.expire(expire='90.days.ago')
''

API Reference

class libvcs.cmd.git.GitReflogManager

class

class

class libvcs.cmd.git.GitReflogManager

Bases: object

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

__init__(*, path, cmd=None)

method

method

__init__(*, path, cmd=None)

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', trim=True)
'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

attribute

path: Path

Directory to check out

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

method

method

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

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

method

show(ref='HEAD', *, number=None, log_in_real_time=False, check_returncode=None)

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

method

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)

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

method

exists(ref, *, log_in_real_time=False, check_returncode=None)

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

method

_ls(ref='HEAD', *, number=None, log_in_real_time=False, check_returncode=None)

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

method

ls(ref='HEAD', *, number=None)

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

method

get(refspec=None, sha=None, **kwargs)

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:

• ObjectDoesNotExist – If no matching entry found.

• MultipleObjectsReturned – If multiple entries match.

Examples

>>> entry = GitReflogManager(path=example_git_repo.path).get(
...     refspec='HEAD@{0}'
... )
>>> entry.refspec
'HEAD@{0}'

filter(*args, **kwargs)

method

method

filter(*args, **kwargs)

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

class

class libvcs.cmd.git.GitReflogEntryCmd

Bases: object

Run git commands targeting a specific reflog entry.

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

method

method

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

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

attribute

path: Path

Directory to check out

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

method

method

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

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

method

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

Show this reflog entry.

Examples

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

Parameters:

• log_in_real_time (bool)

• check_returncode (bool | None)

Return type:

str

delete(*, rewrite=False, updateref=False, dry_run=False, verbose=False, log_in_real_time=False, check_returncode=None)

method

method

delete(*, rewrite=False, updateref=False, dry_run=False, verbose=False, log_in_real_time=False, check_returncode=None)

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

class

class libvcs.cmd.git.GitReflogEntry

Bases: object

Represent a git reflog entry.

__init__(sha, refspec, action, message, _cmd=None)

method

method

__init__(sha, refspec, action, message, _cmd=None)

Parameters:

• sha (str)

• refspec (str)

• action (str)

• message (str)

• _cmd (GitReflogEntryCmd | None)

Return type:

None

sha: str

attribute

attribute

sha: str

Commit SHA.

refspec: str

attribute

attribute

refspec: str

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

action: str

attribute

attribute

action: str

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

message: str

attribute

attribute

message: str

Commit/action message.

_cmd: GitReflogEntryCmd | None = None

attribute

attribute

_cmd: GitReflogEntryCmd | None = None

Internal: GitReflogEntryCmd for operations on this entry

property cmd: GitReflogEntryCmd

property

property

property cmd: GitReflogEntryCmd

Return command object for this reflog entry.