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

Bases: object

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

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

Parameters:: path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

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'

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

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

Parameters:

path (str | PathLike[str]) – 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¶: Directory to check out

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

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

Wraps git stash.

Return type:

str

Parameters:

command (Literal['list', 'show', 'save', 'drop', 'branch', 'pop', 'apply', 'push', 'clear', 'create', 'store'] | None)
local_flags (list[str] | None)
quiet (bool | None)
log_in_real_time (bool)
check_returncode (bool | None)
kwargs (Any)

Examples

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

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

Git stash push.

Save local modifications to a new stash entry.

Parameters:

message (str | None) – Stash message
path (list[str | PathLike[str]] | str | PathLike[str] | 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)[source]¶

Git stash clear.

Remove all stash entries.

Return type:

str

Parameters:

log_in_real_time (bool)
check_returncode (bool | None)

Examples

>>> GitStashManager(path=example_git_repo.path).clear()
''

_ls()[source]¶

List stashes (raw output).

Return type:: list[str]

Examples

>>> GitStashManager(path=example_git_repo.path)._ls()
[]

ls()[source]¶

List stashes.

Returns a QueryList of GitStashEntryCmd objects.

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

Return type:: QueryList[GitStashEntryCmd]

Examples

>>> GitStashManager(path=example_git_repo.path).ls()
[]

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

Get stash entry via filter lookup.

Return type:

GitStashEntryCmd | None

Parameters:

args (Any)
kwargs (Any)

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

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

Get stash entries via filter lookup.

Return type:

list[GitStashEntryCmd]

Parameters:

args (Any)
kwargs (Any)

Examples

>>> GitStashManager(
...     path=example_git_repo.path
... ).filter(branch__contains='master')
[]

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

Bases: object

Run git commands targeting a specific stash entry.

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

Parameters:

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

Examples

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

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

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

Parameters:

path (str | PathLike[str]) – 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¶: Directory to check out

index: int¶

branch: str | None¶

message: str¶

property stash_ref: str¶: Return the stash reference string.

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

Run command against a git stash entry.

Wraps git stash.

Return type:

str

Parameters:

command (Literal['list', 'show', 'save', 'drop', 'branch', 'pop', 'apply', 'push', 'clear', 'create', 'store'] | None)
local_flags (list[str] | None)
log_in_real_time (bool)
check_returncode (bool | None)
kwargs (Any)

show(*, stat=None, patch=None, include_untracked=None, log_in_real_time=False, check_returncode=None)[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)[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)[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)[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)[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[source]¶

Bases: object

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

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

Parameters:: path (str | PathLike[str]) – Operates as PATH in the corresponding git subcommand.

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)
''

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

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

Parameters:

path (str | PathLike[str]) – 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¶: Directory to check out

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

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

Wraps git stash.

Return type:

str

Parameters:

command (Literal['list', 'show', 'save', 'drop', 'branch', 'pop', 'apply', 'push', 'clear', 'create', 'store'] | None)
local_flags (list[str] | None)
quiet (bool | None)
log_in_real_time (bool)
check_returncode (bool | None)
kwargs (Any)

Examples

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

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

Git stash list.

Return type:

str

Parameters:

log_in_real_time (bool)
check_returncode (bool | None)

Examples

>>> GitStashCmd(path=example_git_repo.path).ls()
''

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

Push changes to the stash.

Wraps git stash push.

Parameters:

path (list[str | PathLike[str]] | str | PathLike[str] | 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)[source]¶

Git stash pop.

Return type:

str

Parameters:

stash (int | None)
index (bool | None)
quiet (bool | None)
log_in_real_time (bool)
check_returncode (bool | None)
kwargs (Any)

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'

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

Git stash save.

Return type:

str

Parameters:

message (str | None)
staged (int | None)
keep_index (int | None)
patch (bool | None)
include_untracked (bool | None)
_all (bool | None)
quiet (bool | None)
log_in_real_time (bool)
check_returncode (bool | None)
kwargs (Any)

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'

stash¶

Overview¶

Example¶

API Reference¶

`stash`¶