Struct WorktreeDescriptor 

pub struct WorktreeDescriptor { /* private fields */ }

A handle to a git worktree with rich metadata access.

Wraps a git2::Worktree and exposes branch state, remote tracking info, commit history, and status checks used by the CLI commands.

Implementations

impl WorktreeDescriptor

pub fn new(repo: &Repository, name: &str) -> Result<Self>

Open a worktree by name within the given repository.

pub fn of(worktree: Worktree) -> Self

Wrap an existing git2::Worktree without a repository lookup.

pub fn name(&self) -> Option<&str>

Returns the name of the worktree, or None if the name is invalid UTF-8.

pub fn path(&self) -> &Path

Returns the filesystem path to the worktree’s working directory.

pub fn branch(&self) -> Result<Option<String>>

Returns the branch name if the worktree is on a branch, or None if detached.

This reads the HEAD file from the worktree’s git directory to determine if HEAD points to a branch reference or directly to a commit SHA.

pub fn is_detached(&self) -> Result<bool>

Returns true if the worktree has a detached HEAD (not on a branch).

pub fn is_dirty(&self) -> Result<bool>

Returns true if the worktree has uncommitted changes (dirty working tree).

This includes:

• Modified files (staged or unstaged)
• New untracked files
• Deleted files

pub fn has_tracked_changes(&self) -> Result<bool>

Returns true if the worktree has uncommitted changes to tracked files.

Unlike is_dirty(), this excludes untracked files. Use this when untracked files should not block an operation (e.g. pruning a worktree whose remote branch is gone).

pub fn has_unpushed_commits(&self) -> Result<bool>

Returns true if the worktree’s branch has unpushed commits (ahead of upstream).

Returns false if:

• The worktree is detached (no branch)
• The branch has no upstream configured
• The branch is up to date with upstream

Returns true if:

• The branch has commits ahead of its upstream
• The upstream is configured but the remote reference is gone (conservative)

pub fn is_behind_upstream(&self) -> Result<bool>

Returns true if the worktree’s branch is behind its upstream.

Returns false if:

• The worktree is detached (no branch)
• The branch has no upstream configured
• The branch is up to date with upstream
• The upstream is configured but the remote reference is gone

Returns true if:

• The branch has commits behind its upstream

pub fn has_gone_upstream(&self) -> Result<bool>

Returns true if the worktree’s upstream branch reference is gone (deleted on remote).

Returns false if:

• The worktree is detached (no branch)
• The branch has no upstream configured
• The upstream branch reference exists

Returns true if:

• Upstream is configured (branch.{name}.remote exists in config)
• But the upstream branch reference cannot be found

pub fn is_merged_into(&self, target_branch: &str) -> Result<bool>

Returns true if the worktree’s branch has been merged into the target branch.

A branch is considered merged if its HEAD commit is reachable from the target branch, meaning all commits in this branch exist in the target branch’s history.

Returns false if:

• The worktree is detached (no branch)
• The target branch doesn’t exist
• The branch has commits not in the target branch

Returns true if:

• All commits in this branch are reachable from the target branch

pub fn head_commit(&self) -> Result<Option<String>>

Returns the commit hash (SHA) of the worktree’s current HEAD.

Returns None if HEAD cannot be resolved (e.g., empty repository).

pub fn last_activity(&self) -> Result<Option<i64>>

Returns the timestamp of the HEAD commit as the last activity time.

Returns None if:

• HEAD cannot be resolved (empty/unborn repository)
• HEAD cannot be peeled to a commit

pub fn is_stale(&self, days: u32) -> Result<bool>

Returns true if the worktree’s last activity is older than days days.

Returns false if:

• Last activity cannot be determined
• The worktree has recent activity within the threshold

pub fn remote(&self) -> Result<Option<String>>

Returns the name of the remote that the worktree’s branch tracks (e.g., “origin”).

Returns None if:

• The worktree is detached (no branch)
• The branch has no upstream configured

pub fn remote_branch(&self) -> Result<Option<String>>

Returns the full name of the upstream remote branch (e.g., “refs/remotes/origin/main”).

Returns None if:

• The worktree is detached (no branch)
• The branch has no upstream configured

pub fn remote_url(&self) -> Result<Option<String>>

Returns the default URL for the remote (usually the fetch URL).

Returns None if:

• The worktree is detached (no branch)
• The branch has no upstream configured
• The remote has no URL configured

pub fn remote_fetch_url(&self) -> Result<Option<String>>

Returns the fetch URL for the remote.

Returns None if:

• The worktree is detached (no branch)
• The branch has no upstream configured
• The remote has no fetch URL configured

pub fn remote_push_url(&self) -> Result<Option<String>>

Returns the push URL for the remote.

Returns None if:

• The worktree is detached (no branch)
• The branch has no upstream configured
• The remote has no push URL configured (falls back to fetch URL)

Trait Implementations

impl Debug for WorktreeDescriptor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for WorktreeDescriptor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.