worktree¶

For git-worktree(1).

Overview¶

Manage git worktrees using GitWorktreeManager (collection-level) and GitWorktreeCmd (per-worktree operations).

Example¶

from libvcs.cmd.git import Git

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

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

# Add a new worktree
git.worktrees.add(path='/path/to/worktree', branch='feature-branch')

# Get a specific worktree and operate on it
wt = git.worktrees.get(worktree_path='/path/to/worktree')
wt.lock(reason='Do not delete')
wt.unlock()
wt.remove()

# Prune stale worktrees
git.worktrees.prune()

API Reference¶

class libvcs.cmd.git.GitWorktreeManager(*, path, cmd=None)[source]¶

Bases: object

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

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

Parameters:

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

  • cmd (Git | None)

Examples

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

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

>>> len(GitWorktreeManager(path=example_git_repo.path).run('list')) > 0
True
__init__(*, path, cmd=None)[source]¶

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

Parameters:

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

  • cmd (Git | None)

Return type:

None

Examples

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

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

>>> len(GitWorktreeManager(path=example_git_repo.path).run('list')) > 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 worktrees.

Wraps git worktree.

Return type:

str

Parameters:

  • command (Literal['add', 'list', 'lock', 'move', 'prune', 'remove', 'repair', 'unlock'] | None)

  • local_flags (list[str] | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

Examples

>>> len(GitWorktreeManager(path=example_git_repo.path).run('list')) > 0
True
add(path, *, commit_ish=None, force=None, detach=None, checkout=None, lock=None, reason=None, new_branch=None, new_branch_force=None, orphan=None, track=None, guess_remote=None, log_in_real_time=False, check_returncode=None)[source]¶

Add a new worktree.

Parameters:

  • path (str | PathLike[str]) – Path for the new worktree.

  • commit_ish (str | None) – Commit/branch to checkout in the new worktree.

  • force (bool | None) – Force creation even if path already exists.

  • detach (bool | None) – Detach HEAD in the new worktree.

  • checkout (bool | None) – Checkout commit after creating worktree.

  • lock (bool | None) – Lock the worktree after creation.

  • reason (str | None) – Reason for locking (requires lock=True).

  • new_branch (str | None) – Create a new branch (-b).

  • new_branch_force (str | None) – Force create a new branch (-B).

  • orphan (bool | None) – Create a new orphan branch.

  • track (bool | None) – Set up tracking for the new branch.

  • guess_remote (bool | None) – Guess remote tracking branch.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitWorktreeManager(path=example_git_repo.path).add(
...     path='/tmp/test-worktree-add', commit_ish='HEAD'
... )
"Preparing worktree (detached HEAD ...)..."
prune(*, dry_run=None, verbose=None, expire=None, log_in_real_time=False, check_returncode=None)[source]¶

Prune worktree information.

Parameters:

  • dry_run (bool | None) – Do not remove anything, just report what would be done.

  • verbose (bool | None) – Report all removals.

  • expire (str | None) – Only expire unused worktrees older than the given time.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitWorktreeManager(path=example_git_repo.path).prune()
''

>>> GitWorktreeManager(path=example_git_repo.path).prune(dry_run=True)
''
_ls(*, verbose=None)[source]¶

List worktrees (raw output).

Return type:

list[str]

Parameters:

verbose (bool | None)

Examples

>>> len(GitWorktreeManager(path=example_git_repo.path)._ls()) >= 1
True
ls(*, verbose=None)[source]¶

List worktrees.

Returns a QueryList of GitWorktreeCmd objects.

Parameters:

verbose (bool | None) – Include additional information.

Return type:

QueryList[GitWorktreeCmd]

Examples

>>> worktrees = GitWorktreeManager(path=example_git_repo.path).ls()
>>> len(worktrees) >= 1
True
get(*args, **kwargs)[source]¶

Get worktree via filter lookup.

Return type:

GitWorktreeCmd | None

Parameters:

Examples

>>> worktrees = GitWorktreeManager(path=example_git_repo.path).ls()
>>> if len(worktrees) > 0:
...     wt = GitWorktreeManager(path=example_git_repo.path).get(
...         worktree_path=worktrees[0].worktree_path
...     )
...     wt is not None
... else:
...     True
True
filter(*args, **kwargs)[source]¶

Get worktrees via filter lookup.

Return type:

list[GitWorktreeCmd]

Parameters:

Examples

>>> len(GitWorktreeManager(path=example_git_repo.path).filter()) >= 0
True
class libvcs.cmd.git.GitWorktreeCmd(*, path, cmd=None, worktree_path, head=None, branch=None, locked=False, prunable=False)[source]¶

Bases: object

Run git commands targeting a specific worktree.

Lite, typed, pythonic wrapper for a git-worktree(1) entry.

Parameters:

  • path (str | PathLike[str]) – Path to the main git repository.

  • worktree_path (str) – Path to this worktree.

  • head (str | None) – HEAD commit SHA for this worktree.

  • branch (str | None) – Branch checked out in this worktree.

  • locked (bool) – Whether this worktree is locked.

  • prunable (bool) – Whether this worktree is prunable.

  • cmd (Git | None)

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/example-worktree',
... )
<GitWorktreeCmd path=... worktree_path=/tmp/example-worktree>
__init__(*, path, cmd=None, worktree_path, head=None, branch=None, locked=False, prunable=False)[source]¶

Lite, typed, pythonic wrapper for a git-worktree(1) entry.

Parameters:

  • path (str | PathLike[str]) – Path to the main git repository.

  • worktree_path (str) – Path to this worktree.

  • head (str | None) – HEAD commit SHA for this worktree.

  • branch (str | None) – Branch checked out in this worktree.

  • locked (bool) – Whether this worktree is locked.

  • prunable (bool) – Whether this worktree is prunable.

  • cmd (Git | None)

Return type:

None

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/example-worktree',
... )
<GitWorktreeCmd path=... worktree_path=/tmp/example-worktree>
path: Path¶

Directory to check out

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

Run command against a git worktree.

Wraps git worktree.

Return type:

str

Parameters:

  • command (Literal['add', 'list', 'lock', 'move', 'prune', 'remove', 'repair', 'unlock'] | None)

  • local_flags (list[str] | None)

  • log_in_real_time (bool)

  • check_returncode (bool | None)

  • kwargs (Any)

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

Remove this worktree.

Parameters:

  • force (bool) – Force removal even if worktree is dirty or locked.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/nonexistent-worktree',
... ).remove()
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
lock(*, reason=None, log_in_real_time=False, check_returncode=None)[source]¶

Lock this worktree.

Parameters:

  • reason (str | None) – Reason for locking the worktree.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/nonexistent-worktree',
... ).lock()
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
unlock(*, log_in_real_time=False, check_returncode=None)[source]¶

Unlock this worktree.

Return type:

str

Parameters:

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/nonexistent-worktree',
... ).unlock()
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
move(new_path, *, force=False, log_in_real_time=False, check_returncode=None)[source]¶

Move this worktree to a new location.

Parameters:

  • new_path (str | PathLike[str]) – New path for the worktree.

  • force (bool) – Force move even if worktree is dirty or locked.

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Return type:

str

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/nonexistent-worktree',
... ).move('/tmp/new-worktree')
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
repair(*, log_in_real_time=False, check_returncode=None)[source]¶

Repair this worktree.

Return type:

str

Parameters:

  • log_in_real_time (bool)

  • check_returncode (bool | None)

Examples

>>> result = GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/nonexistent-worktree',
... ).repair()
>>> result == '' or 'error' in result
True