stash¶

For git-stash(1).

Overview¶

Manage git stashes using GitStashManager (collection-level) and GitStashEntryCmd (per-stash operations).

Note

GitStashCmd is the legacy interface. Use git.stashes (GitStashManager) for the new Manager/Cmd pattern.

Example¶

from libvcs.cmd.git import Git

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

# Push changes to stash
git.stashes.push(message='Work in progress')

# List all stashes
stashes = git.stashes.ls()

# Get a specific stash and operate on it
stash = git.stashes.get(index=0)
stash.show()
stash.apply()
stash.drop()

# Clear all stashes
git.stashes.clear()

API Reference¶

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

Bases: object

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

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

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

Parameters:

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

  • cmd (Git | None)

Return type:

None

Examples

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

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

>>> GitStashManager(
...     path=example_git_repo.path
... ).run()
'No local changes to save'
path: Path
¶
attribute

Directory to check out

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

Run a command against a git repository’s stash storage.

Wraps git stash.

Examples

>>> GitStashManager(path=example_git_repo.path).run()
'No local changes to save'
Parameters:
Return type:

str

push(*, message=None, path=None, patch=None, staged=None, keep_index=None, include_untracked=None, _all=None, quiet=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash push.

Save local modifications to a new stash entry.

Parameters:

  • message (str | None) – Stash message

  • path (list[StrPath] | StrPath | None) – Limit stash to specific paths

  • patch (bool | None) – Interactive patch selection (-p)

  • staged (bool | None) – Stash only staged changes (-S)

  • keep_index (bool | None) – Keep index intact (-k)

  • include_untracked (bool | None) – Include untracked files (-u)

  • _all (bool | None) – Include ignored files (-a)

  • quiet (bool | None) – Suppress output (-q)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitStashManager(path=example_git_repo.path).push()
'No local changes to save'

>>> GitStashManager(path=example_git_repo.path).push(message='WIP')
'No local changes to save'
clear(*, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash clear.

Remove all stash entries.

Examples

>>> GitStashManager(path=example_git_repo.path).clear()
''
Parameters:
Return type:

str

_ls()
¶
method[source]

List stashes (raw output).

Examples

>>> GitStashManager(path=example_git_repo.path)._ls()
[]
Return type:

list[str]

ls()
¶
method[source]

List stashes.

Returns a QueryList of GitStashEntryCmd objects.

Parses stash list format: - stash@{0}: On master: message - stash@{0}: WIP on master: commit

Examples

>>> GitStashManager(path=example_git_repo.path).ls()
[]
Return type:

QueryList[GitStashEntryCmd]

get(*args, **kwargs)
¶
method[source]

Get stash entry via filter lookup.

Examples

>>> GitStashManager(
...     path=example_git_repo.path
... ).get(index=0)
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
Parameters:
Return type:

GitStashEntryCmd | None

filter(*args, **kwargs)
¶
method[source]

Get stash entries via filter lookup.

Examples

>>> GitStashManager(
...     path=example_git_repo.path
... ).filter(branch__contains='master')
[]
Parameters:
Return type:

list[GitStashEntryCmd]

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

Bases: object

Run git commands targeting a specific stash entry.

__init__(*, path, index, branch=None, message='', cmd=None)
¶
method[source]

Lite, typed, pythonic wrapper for git-stash(1) per-entry operations.

Parameters:

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

  • index (int) – Stash index (0 = most recent)

  • branch (str | None) – Branch the stash was created on

  • message (str) – Stash message

  • cmd (Git | None)

Return type:

None

Examples

>>> GitStashEntryCmd(
...     path=example_git_repo.path,
...     index=0,
...     branch='master',
...     message='WIP',
... )
<GitStashEntryCmd path=... index=0>
path: Path
¶
attribute

Directory to check out

index: int
¶
attribute
branch: str | None
¶
attribute
message: str
¶
attribute
property stash_ref: str
¶
property

Return the stash reference string.

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

Run command against a git stash entry.

Wraps git stash.

Parameters:
Return type:

str

show(*, stat=None, patch=None, include_untracked=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash show for this stash entry.

Parameters:

  • stat (bool | None) – Show diffstat (–stat)

  • patch (bool | None) – Show patch (-p)

  • include_untracked (bool | None) – Include untracked files (-u)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitStashEntryCmd(
...     path=example_git_repo.path,
...     index=0,
... ).show()
'error: stash@{0} is not a valid reference'
apply(*, index=None, quiet=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash apply for this stash entry.

Apply the stash without removing it from the stash list.

Parameters:

  • index (bool | None) – Try to reinstate not only the working tree but also the index (–index)

  • quiet (bool | None) – Suppress output (-q)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitStashEntryCmd(
...     path=example_git_repo.path,
...     index=0,
... ).apply()
'error: stash@{0} is not a valid reference'
pop(*, index=None, quiet=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash pop for this stash entry.

Apply the stash and remove it from the stash list.

Parameters:

  • index (bool | None) – Try to reinstate not only the working tree but also the index (–index)

  • quiet (bool | None) – Suppress output (-q)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitStashEntryCmd(
...     path=example_git_repo.path,
...     index=0,
... ).pop()
'error: stash@{0} is not a valid reference'
drop(*, quiet=None, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash drop for this stash entry.

Remove this stash from the stash list.

Parameters:

  • quiet (bool | None) – Suppress output (-q)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitStashEntryCmd(
...     path=example_git_repo.path,
...     index=0,
... ).drop()
'error: stash@{0} is not a valid reference'
create_branch(branch_name, *, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash branch for this stash entry.

Create a new branch from this stash entry and apply the stash.

Parameters:

  • branch_name (str) – Name of the branch to create

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitStashEntryCmd(
...     path=example_git_repo.path,
...     index=0,
... ).create_branch('new-branch')
'error: stash@{0} is not a valid reference'
class libvcs.cmd.git.GitStashCmd
¶
class[source]

Bases: object

Run git stash commands (low-level, use GitStashManager for traversal).

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

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

Parameters:

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

  • cmd (Git | None)

Return type:

None

Examples

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

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

>>> GitStashCmd(path=example_git_repo.path).run(quiet=True)
''
path: Path
¶
attribute

Directory to check out

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

Run a command against a git repository’s stash storage.

Wraps git stash.

Examples

>>> GitStashCmd(path=example_git_repo.path).run()
'No local changes to save'
Parameters:
Return type:

str

ls(*, log_in_real_time=False, check_returncode=None)
¶
method[source]

Git stash list.

Examples

>>> GitStashCmd(path=example_git_repo.path).ls()
''
Parameters:
Return type:

str

push(*, path=None, patch=None, staged=None, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]

Push changes to the stash.

Wraps git stash push.

Parameters:

  • path (list[StrPath] | StrPath | None) – Limit stash to specific path(s).

  • patch (bool | None) – Interactively select hunks to stash.

  • staged (bool | None) – Stash only staged changes.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Return type:

str

Examples

>>> GitStashCmd(path=example_git_repo.path).push()
'No local changes to save'

>>> GitStashCmd(path=example_git_repo.path).push(path='.')
'No local changes to save'
pop(*, stash=None, index=None, quiet=None, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]

Git stash pop.

Examples

>>> GitStashCmd(path=example_git_repo.path).pop()
'No stash entries found.'

>>> GitStashCmd(path=example_git_repo.path).pop(stash=0)
'error: stash@{0} is not a valid reference'

>>> GitStashCmd(path=example_git_repo.path).pop(stash=1, index=True)
'error: stash@{1} is not a valid reference'

>>> GitStashCmd(path=example_git_repo.path).pop(stash=1, quiet=True)
'error: stash@{1} is not a valid reference'

>>> GitStashCmd(path=example_git_repo.path).push(path='.')
'No local changes to save'
Parameters:
Return type:

str

save(*, message=None, staged=None, keep_index=None, patch=None, include_untracked=None, _all=None, quiet=None, log_in_real_time=False, check_returncode=None, **kwargs)
¶
method[source]

Git stash save.

Examples

>>> GitStashCmd(path=example_git_repo.path).save()
'No local changes to save'

>>> GitStashCmd(path=example_git_repo.path).save(message="Message")
'No local changes to save'
Parameters:
Return type:

str