`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(*, path, cmd=None)[source]¶

Bases: object

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

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

Parameters:

path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.
cmd (Git | 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

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

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

Parameters:

path (str | PathLike[str]) – 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¶: 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 reflog.

Wraps git reflog.

Parameters:

command (Optional[Literal['show', 'expire', 'delete', 'exists']]) – 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)[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)[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)[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)[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)[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)[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:

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)[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(*, path, refspec, cmd=None)[source]¶

Bases: object

Run git commands targeting a specific reflog entry.

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

Parameters:

path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.
refspec (str) – Reference specification (e.g., HEAD@{0}, master@{2}).
cmd (Git | None)

Examples

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

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

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

Parameters:

path (str | PathLike[str]) – 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¶: 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 specific reflog entry.

Wraps git reflog.

Parameters:

command (Optional[Literal['show', 'expire', 'delete', 'exists']]) – 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)[source]¶

Show this reflog entry.

Return type:

str

Parameters:

log_in_real_time (bool)
check_returncode (bool | None)

Examples

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

delete(*, rewrite=False, updateref=False, dry_run=False, verbose=False, log_in_real_time=False, check_returncode=None)[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(sha, refspec, action, message, _cmd=None)[source]¶

Bases: object

Represent a git reflog entry.

Parameters:

sha (str)
refspec (str)
action (str)
message (str)
_cmd (GitReflogEntryCmd | None)

sha: str¶: Commit SHA.

refspec: str¶: Reference specification (e.g., HEAD@{0}).

action: str¶: Action performed (e.g., commit, checkout, merge).

message: str¶: Commit/action message.

_cmd: GitReflogEntryCmd | None = None¶

GitReflogEntryCmd for operations on this entry

Type:: Internal

property cmd: GitReflogEntryCmd¶: Return command object for this reflog entry.

reflog¶

Overview¶

Example¶

API Reference¶

`reflog`¶