dulwich.worktree

module documentation

Working tree operations for Git repositories.

Class	`WorkTree`	Working tree operations for a Git repository.
Class	`WorkTreeContainer`	Container for managing multiple working trees.
Class	`WorkTreeInfo`	Information about a single worktree.
Function	`add_worktree`	Add a new worktree to the repository.
Function	`list_worktrees`	List all worktrees for the given repository.
Function	`lock_worktree`	Lock a worktree to prevent it from being pruned.
Function	`move_worktree`	Move a worktree to a new location.
Function	`prune_worktrees`	Prune worktree administrative files for missing worktrees.
Function	`read_worktree_lock_reason`	Read the lock reason for a worktree.
Function	`remove_worktree`	Remove a worktree.
Function	`repair_worktree`	Repair worktree administrative files.
Function	`temporary_worktree`	Create a temporary worktree that is automatically cleaned up.
Function	`unlock_worktree`	Unlock a worktree.
Function	`_compute_gitdir_path`	Compute the gitdir path and enable extension if needed.
Function	`_find_worktree_id`	Find the worktree identifier for the given path.
Function	`_should_use_relative_paths`	Determine whether to use relative paths for gitdir references.

Add a new worktree to the repository.

Parameters
repo:`Repo`	The main repository
path:`str \| bytes \| os.PathLike[str]`	Path where the new worktree should be created
branch:`str \| bytes \| None`	Branch to checkout in the new worktree (creates if doesn't exist)
commit:`ObjectID \| None`	Specific commit to checkout (results in detached HEAD)
force:`bool`	Force creation even if branch is already checked out elsewhere
detach:`bool`	Detach HEAD in the new worktree
exist_ok:`bool`	If True, do not raise an error if the directory already exists
relative_paths:`bool \| None`	If True, use relative paths for gitdir references. If None, check worktree.useRelativePaths config (defaults to False)

Returns
`Repo`	The newly created worktree repository

Raises
`ValueError`	If the path already exists (and exist_ok is False) or branch is already checked out

def list_worktrees(repo: Repo) -> list[WorkTreeInfo]: ¶

List all worktrees for the given repository.

Parameters
repo:`Repo`	The repository to list worktrees for

Returns
`list[WorkTreeInfo]`	A list of WorkTreeInfo objects

def lock_worktree(repo: Repo, path: str | bytes | os.PathLike[str], reason: str | None = None): ¶

Lock a worktree to prevent it from being pruned.

Parameters
repo:`Repo`	The main repository
path:`str \| bytes \| os.PathLike[str]`	Path to the worktree to lock
reason:`str \| None`	Optional reason for locking

Move a worktree to a new location.

Parameters
repo:`Repo`	The main repository
old_path:`str \| bytes \| os.PathLike[str]`	Current path of the worktree
new_path:`str \| bytes \| os.PathLike[str]`	New path for the worktree
relative_paths:`bool \| None`	If True, use relative paths for gitdir references. If None, check worktree.useRelativePaths config or preserve existing format

Raises
`ValueError`	If the worktree doesn't exist or new path already exists

def prune_worktrees(repo: Repo, expire: int | None = None, dry_run: bool = False) -> list[str]: ¶

Prune worktree administrative files for missing worktrees.

Parameters
repo:`Repo`	The main repository
expire:`int \| None`	Only prune worktrees older than this many seconds
dry_run:`bool`	Don't actually remove anything, just report what would be removed

Returns
`list[str]`	List of pruned worktree identifiers

def read_worktree_lock_reason(worktree_path: str) -> str | None: ¶

Read the lock reason for a worktree.

Parameters
worktree_path:`str`	Path to the worktree's administrative directory

Returns
`str \| None`	The lock reason if the worktree is locked, None otherwise

def remove_worktree(repo: Repo, path: str | bytes | os.PathLike[str], force: bool = False): ¶

Remove a worktree.

Parameters
repo:`Repo`	The main repository
path:`str \| bytes \| os.PathLike[str]`	Path to the worktree to remove
force:`bool`	Force removal even if there are local changes

Raises
`ValueError`	If the worktree doesn't exist, has local changes, or is locked

def repair_worktree(repo: Repo, paths: Sequence[str | bytes | os.PathLike[str]] | None = None, relative_paths: bool | None = None) -> list[str]: ¶

Repair worktree administrative files.

This repairs the connection between worktrees and the main repository when they have been moved or become corrupted.

Parameters
repo:`Repo`	The main repository
paths:`Sequence[str \| bytes \| os.PathLike[str]] \| None`	Optional list of worktree paths to repair. If None, repairs connections from the main repository to all linked worktrees.
relative_paths:`bool \| None`	If True, use relative paths for gitdir references. If None, check worktree.useRelativePaths config or preserve existing format

Returns
`list[str]`	List of repaired worktree paths

Raises
`ValueError`	If a specified path is not a valid worktree

@contextmanager

def temporary_worktree(repo: Repo, prefix: str = 'tmp-worktree-') -> Iterator[Repo]: ¶

Create a temporary worktree that is automatically cleaned up.

Parameters
repo:`Repo`	Dulwich repository object
prefix:`str`	Prefix for the temporary directory name

Returns
`Iterator[Repo]`	Undocumented

Yields
Worktree object

def unlock_worktree(repo: Repo, path: str | bytes | os.PathLike[str]): ¶

Unlock a worktree.

Parameters
repo:`Repo`	The main repository
path:`str \| bytes \| os.PathLike[str]`	Path to the worktree to unlock

def _compute_gitdir_path(repo: Repo, gitdir_file: str, worktree_control_dir: str, use_relative: bool) -> str: ¶

Compute the gitdir path and enable extension if needed.

Parameters
repo:`Repo`	The repository
gitdir_file:`str`	Absolute path to the .git file
worktree_control_dir:`str`	Absolute path to the worktree control directory
use_relative:`bool`	Whether to use relative paths

Returns
`str`	The path to write (relative or absolute)

def _find_worktree_id(repo: Repo, path: str | bytes | os.PathLike[str]) -> str: ¶

Find the worktree identifier for the given path.

Parameters
repo:`Repo`	The main repository
path:`str \| bytes \| os.PathLike[str]`	Path to the worktree

Returns
`str`	The worktree identifier

Raises
`ValueError`	If the worktree is not found

def _should_use_relative_paths(repo: Repo, relative_paths: bool | None, existing_path: bytes | None = None) -> bool: ¶

Determine whether to use relative paths for gitdir references.

Parameters
repo:`Repo`	The repository
relative_paths:`bool \| None`	Explicit preference (True/False) or None to check config
existing_path:`bytes \| None`	Optional existing path to check format (for preserving format)

Returns
`bool`	True if relative paths should be used, False otherwise