Module: Git::Repository::WorktreeOperations

Included in:
Git::Repository
Defined in:
lib/git/repository/worktree_operations.rb

Overview

Facade methods for worktree operations

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#worktree(dir, commitish = nil) ⇒ Git::Worktree

Return a Worktree object for the given directory and optional commitish

This is a factory method — it constructs the domain object but does not immediately execute any git commands.

Examples:

Get a worktree object for a new path

wt = repo.worktree('/tmp/feature')

Get a worktree object for a specific branch or commit

wt = repo.worktree('/tmp/hotfix', 'main')

Parameters:

  • dir (String) —

    filesystem path for the worktree

  • commitish (String, nil) (defaults to: nil) —

    branch, tag, or commit to associate with the worktree; nil means no commitish is specified

Returns:

  • (Git::Worktree) —

    a worktree domain object for the given path



131
132
133
 
# File 'lib/git/repository/worktree_operations.rb', line 131

def worktree(dir, commitish = nil)
  Git::Worktree.new(self, dir, commitish)
end

#worktree_add(dir, commitish = nil) ⇒ String

Create a new linked worktree at the given directory

Examples:

Create a worktree at a path (auto-creates a branch)

repo.worktree_add('/tmp/feature')

Create a worktree and check out an existing commitish

repo.worktree_add('/tmp/hotfix', 'main')

Parameters:

  • dir (String) —

    filesystem path for the new worktree

  • commitish (String, nil) (defaults to: nil) —

    branch, tag, or commit to check out

    When nil, git creates a new branch named after the final path component

Returns:

  • (String) —

    the output from the git worktree add command

Raises:

See Also:



69
70
71
72
73
74
 
# File 'lib/git/repository/worktree_operations.rb', line 69

def worktree_add(dir, commitish = nil)
  args = [dir]
  args << commitish unless commitish.nil?

  Git::Commands::Worktree::Add.new(@execution_context).call(*args).stdout
end

#worktree_prune ⇒ String

Prune stale worktree administrative files

Removes stale administrative files from $GIT_DIR/worktrees. A worktree becomes stale when its directory no longer exists on disk.

Examples:

Prune stale worktrees

repo.worktree_prune

Returns:

  • (String) —

    the output from the git worktree prune command (typically empty)

Raises:

See Also:



109
110
111
 
# File 'lib/git/repository/worktree_operations.rb', line 109

def worktree_prune
  Git::Commands::Worktree::Prune.new(@execution_context).call.stdout
end

#worktree_remove(dir) ⇒ String

Remove a linked worktree

Examples:

Remove a worktree

repo.worktree_remove('/tmp/feature')

Parameters:

  • dir (String) —

    filesystem path of the worktree to remove

Returns:

  • (String) —

    the output from the git worktree remove command (typically empty)

Raises:

See Also:



90
91
92
 
# File 'lib/git/repository/worktree_operations.rb', line 90

def worktree_remove(dir)
  Git::Commands::Worktree::Remove.new(@execution_context).call(dir).stdout
end

#worktrees ⇒ Git::Worktrees

Return a Worktrees collection of all worktrees (main and linked)

The collection is populated eagerly when this method is called (git runs at construction time). It is enumerable and supports indexed access by worktree path.

Examples:

Iterate over all worktrees

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

Count worktrees

repo.worktrees.size

Access a specific worktree by path

repo.worktrees['/tmp/feature']

Returns:

Raises:



154
155
156
 
# File 'lib/git/repository/worktree_operations.rb', line 154

def worktrees
  Git::Worktrees.new(self)
end

#worktrees_all ⇒ Array<Array(String, String)>

Returns all worktrees as an array of directory and SHA pairs

Lists all worktrees attached to the repository, including the main worktree and all linked worktrees.

Examples:

List all worktrees

repo.worktrees_all
#=> [["/path/to/main", "4bef5ab..."], ["/tmp/worktree-1", "b8c6320..."]]

Returns:

  • (Array<Array(String, String)>) —

    array of [directory, sha] pairs

    directory is the worktree path reported by git (absolute or relative, depending on repository configuration); sha is the full SHA of the checked-out HEAD commit

Raises:

See Also:



35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/git/repository/worktree_operations.rb', line 35

def worktrees_all
  worktree_entries = []
  current_directory = ''
  command_output = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true).stdout

  command_output.each_line(chomp: true) do |line|
    key, value = line.split(' ', 2)
    current_directory = value if key == 'worktree'
    worktree_entries << [current_directory, value] if key == 'HEAD'
  end

  worktree_entries
end