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.

Examples¶

Stash work in progress, inspect it, restore it, then clear the stash list:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> _ = (example_git_repo.path / 'testfile.test').write_text('wip', encoding='utf-8')
>>> git.stashes.push(message='Work in progress')
'Saved working directory and index state ...'
>>> stashes = git.stashes.ls()
>>> len(stashes)
1
>>> stash = git.stashes.get(index=0)
>>> stash.show()
'...testfile.test...'
>>> stash.apply()
'...'
>>> git.stashes.clear()
''

API Reference¶

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

Bases: object

Traverse git stashes with QueryList.

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

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(trim=True)
'fatal: not a git repository (or any of the parent directories): .git'

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

Directory to check out

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

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

Wraps git stash.

Examples

>>> GitStashManager(path=example_git_repo.path).run(trim=True)
'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, trim=False)
¶
method[source]
method[source]
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, trim=False)
¶

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)

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

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

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

Git stash clear.

Remove all stash entries.

Examples

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

str

_ls()
¶
method[source]
method[source]
_ls()
¶

List stashes (raw output).

Examples

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

list[str]

ls()
¶
method[source]
method[source]
ls()
¶

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]
method[source]
get(*args, **kwargs)
¶

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]
method[source]
filter(*args, **kwargs)
¶

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]
class[source]
class libvcs.cmd.git.GitStashEntryCmd
¶

Bases: object

Run git commands targeting a specific stash entry.

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

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
attribute
path: Path
¶

Directory to check out

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

Return the stash reference string.

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

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

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)

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

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

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)

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

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

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)

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

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

Git stash drop for this stash entry.

Remove this stash from the stash list.

Parameters:

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

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

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

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

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • 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', trim=True)
'error: stash@{0} is not a valid reference'
class libvcs.cmd.git.GitStashCmd
¶
class[source]
class[source]
class libvcs.cmd.git.GitStashCmd
¶

Bases: object

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

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

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, trim=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
attribute
path: Path
¶

Directory to check out

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

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

Wraps git stash.

Examples

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

str

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

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, trim=False, **kwargs)
¶
method[source]
method[source]
push(*, path=None, patch=None, staged=None, log_in_real_time=False, check_returncode=None, trim=False, **kwargs)
¶

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.

  • trim (bool, default: False) – Strip trailing whitespace/newline from command output.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Return type:

str

Examples

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

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

Git stash pop.

Examples

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

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

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

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

>>> GitStashCmd(path=example_git_repo.path).push(path='.', trim=True)
'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, trim=False, **kwargs)
¶
method[source]
method[source]
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, trim=False, **kwargs)
¶

Git stash save.

Examples

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

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

str