class Git::Worktrees

Collection of all Git worktrees in a repository

Wraps every linked and main worktree and provides enumeration and path-based lookup.

@example Enumerate all worktrees

worktrees = repo.worktrees
worktrees.each { |wt| puts wt.dir }

@deprecated Use {Git::Repository::WorktreeOperations#worktree_list} instead

{Git::Repository::WorktreeOperations#worktree_list} returns
`Array<Git::WorktreeInfo>` (immutable value objects). Look a worktree up
by path with `worktree_list.find { |w| w.path == path }` in place of
{#[]}, and call {Git::Repository::WorktreeOperations#worktree_prune} in
place of {#prune}. Constructing a `Git::Worktrees` emits a deprecation
warning.

@api public

Public Class Methods

new (base)

Source

# File lib/git/worktrees.rb, line 40
def initialize(base)
  Git::Deprecation.warn(
    'Git::Worktrees is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#worktree_list instead.'
  )
  @worktrees = {}

  @base = base

  # worktrees_all is deprecated too; silence it so one Git::Worktrees.new emits one warning
  Git::Deprecation.silence { worktree_repository.worktrees_all }.each do |w|
    @worktrees[w[0]] = Git::Worktree.new(@base, w[0], w[1])
  end
end

Creates a new Worktrees collection populated from the given repository

@param base [Git::Repository] the repository to enumerate

worktrees from

@return [void]

@raise [Git::FailedError] if git exits with a non-zero exit status

@deprecated Use {Git::Repository::WorktreeOperations#worktree_list} instead

@see Git::Repository::WorktreeOperations#worktree_list

Public Instance Methods

[] (worktree_name)

Source

# File lib/git/worktrees.rb, line 105
def [](worktree_name)
  @worktrees.values.each_with_object(@worktrees) do |worktree, worktrees|
    worktrees[worktree.full] ||= worktree
  end[worktree_name.to_s]
end

Returns the worktree with the given path

Supports lookup by the filesystem path of the worktree directory or by the full worktree descriptor (path and optional commitish).

@example Look up a worktree by path

repo.worktrees['/path/to/linked-worktree']

@param worktree_name [#to_s] the path (or full descriptor) of the

worktree to retrieve

@return [Git::Worktree, nil] the matching worktree, or ‘nil` if not found

each (&)

Source

# File lib/git/worktrees.rb, line 88
def each(&)
  @worktrees.values.each(&)
end

Iterates over every worktree in the collection

@overload each

@example Get an enumerator over all worktrees
  enum = repo.worktrees.each

@return [Enumerator<Git::Worktree>] an enumerator over all worktrees

@overload each(&block)

@example Print every worktree path
  repo.worktrees.each { |wt| puts wt.dir }

@return [Array<Git::Worktree>] the full list of worktrees

@yield [worktree] passes each worktree to the block

@yieldparam worktree [Git::Worktree] a worktree in the repository

@yieldreturn [void]

prune ()

Source

# File lib/git/worktrees.rb, line 138
def prune
  worktree_repository.worktree_prune
end

Removes stale administrative files for worktrees that no longer exist

Runs ‘git worktree prune` to clean up any lingering worktree metadata for linked worktrees whose directories have been deleted.

@example Prune stale worktree metadata

repo.worktrees.prune

@return [String] stdout from the git command (typically empty)

@raise [Git::FailedError] if git exits with a non-zero exit status

size ()

Source

# File lib/git/worktrees.rb, line 62
def size
  @worktrees.size
end

Returns the number of worktrees in the collection

@example Count all worktrees

repo.worktrees.size  # => 2

@return [Integer] the total number of worktrees

to_s ()

Source

# File lib/git/worktrees.rb, line 118
def to_s
  out = +''
  @worktrees.each_value do |b|
    out << b.to_s << "\n"
  end
  out
end

Returns a string listing all worktrees, one per line

@example Display all worktrees

puts repo.worktrees.to_s

@return [String] a newline-separated listing of worktree descriptors

Private Instance Methods

worktree_repository ()

Source

# File lib/git/worktrees.rb, line 148
def worktree_repository
  @base
end

@return [Git::Repository] the repository used to enumerate worktrees

@api private