worktree¶

For git-worktree(1).

Overview¶

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

Examples¶

Add a worktree checked out at HEAD, then look it up — the main worktree always exists, so the list grows to two:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.worktrees.add(path=tmp_path / 'example-worktree', commit_ish='HEAD')
'HEAD is now at ...'
>>> worktrees = git.worktrees.ls()
>>> len(worktrees) >= 2
True
>>> wt = git.worktrees.get(worktree_path=worktrees[0].worktree_path)
>>> wt.worktree_path == worktrees[0].worktree_path
True

Prune stale worktree metadata:

>>> from libvcs.cmd.git import Git
>>> git = Git(path=example_git_repo.path)
>>> git.worktrees.prune()
''

API Reference¶

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

Bases: object

Traverse git worktrees with QueryList.

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

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

Parameters:

  • path (StrPath) – 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', trim=True)
'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
¶
attribute
attribute
path: Path
¶

Directory to check out

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 a command against a git repository’s worktrees.

Wraps git worktree.

Examples

>>> len(GitWorktreeManager(path=example_git_repo.path).run('list')) > 0
True
Parameters:
Return type:

str

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

Add a new worktree.

Parameters:

  • path (StrPath) – 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)
¶
method[source]
method[source]
prune(*, dry_run=None, verbose=None, expire=None, log_in_real_time=False, check_returncode=None)
¶

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)
¶
method[source]
method[source]
_ls(*, verbose=None)
¶

List worktrees (raw output).

Examples

>>> len(GitWorktreeManager(path=example_git_repo.path)._ls()) >= 1
True
Parameters:

verbose (bool | None)

Return type:

list[str]

ls(*, verbose=None)
¶
method[source]
method[source]
ls(*, verbose=None)
¶

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

Get worktree via filter lookup.

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
Parameters:
Return type:

GitWorktreeCmd | None

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

Get worktrees via filter lookup.

Examples

>>> len(GitWorktreeManager(path=example_git_repo.path).filter()) >= 0
True
Parameters:
Return type:

list[GitWorktreeCmd]

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

Bases: object

Run git commands targeting a specific worktree.

__init__(*, path, cmd=None, worktree_path, head=None, branch=None, locked=False, prunable=False)
¶
method[source]
method[source]
__init__(*, path, cmd=None, worktree_path, head=None, branch=None, locked=False, prunable=False)
¶

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

Parameters:

  • path (StrPath) – 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
¶
attribute
attribute
path: Path
¶

Directory to check out

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 worktree.

Wraps git worktree.

Parameters:
Return type:

str

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

Remove this worktree.

Parameters:

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

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

  • 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(trim=True)
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
lock(*, reason=None, log_in_real_time=False, check_returncode=None, trim=False)
¶
method[source]
method[source]
lock(*, reason=None, log_in_real_time=False, check_returncode=None, trim=False)
¶

Lock this worktree.

Parameters:

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

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

  • 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(trim=True)
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
unlock(*, log_in_real_time=False, check_returncode=None, trim=False)
¶
method[source]
method[source]
unlock(*, log_in_real_time=False, check_returncode=None, trim=False)
¶

Unlock this worktree.

Examples

>>> GitWorktreeCmd(
...     path=example_git_repo.path,
...     worktree_path='/tmp/nonexistent-worktree',
... ).unlock(trim=True)
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
Parameters:
Return type:

str

move(new_path, *, force=False, log_in_real_time=False, check_returncode=None, trim=False)
¶
method[source]
method[source]
move(new_path, *, force=False, log_in_real_time=False, check_returncode=None, trim=False)
¶

Move this worktree to a new location.

Parameters:

  • new_path (StrPath) – New path for the worktree.

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

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

  • 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', trim=True)
"fatal: '/tmp/nonexistent-worktree' is not a working tree"
repair(*, log_in_real_time=False, check_returncode=None)
¶
method[source]
method[source]
repair(*, log_in_real_time=False, check_returncode=None)
¶

Repair this worktree.

Examples

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

str