Module: Git::Repository::WorktreeOperations Private

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

Overview

This module is part of a private API. You should avoid using this module if possible, as it may be removed or be changed in the future.

Facade methods for worktree operations: listing, adding, removing, moving, locking, repairing, and pruning worktrees

Included by Git::Repository.

API:

  • private

Instance Method Summary collapse

Instance Method Details

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use #worktree_add and #worktree_remove instead

repo.worktree(dir, commitish).add becomes repo.worktree_add(dir, commitish) and repo.worktree(dir).remove becomes repo.worktree_remove(dir). Read a worktree's checked-out commit from WorktreeInfo#head via #worktree_list.

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:

  • filesystem path for the worktree

  • (defaults to: nil)

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

Returns:

  • a worktree domain object for the given path

See Also:

API:

  • private



294
295
296
297
298
299
300
 
# File 'lib/git/repository/worktree_operations.rb', line 294

def worktree(dir, commitish = nil)
  Git::Deprecation.warn(
    'Git::Repository#worktree is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#worktree_add and Git::Repository#worktree_remove instead.'
  )
  Git::Worktree.new(self, dir, commitish)
end

#worktree_add(dir, commitish = nil) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:

  • filesystem path for the new worktree

  • (defaults to: nil)

    branch, tag, or commit to check out

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

Returns:

  • the output from the git worktree add command

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



104
105
106
107
108
109
 
# File 'lib/git/repository/worktree_operations.rb', line 104

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_list ⇒ Array<Git::WorktreeInfo>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns every worktree attached to the repository

Lists the main worktree first, then each linked worktree, in the order git reports them. The main worktree of a bare repository is included with WorktreeInfo#bare? true and no head or branch.

Examples:

List all worktrees

repo.worktree_list.map(&:path)
#=> ["/path/to/main", "/tmp/feature"]

Find the worktree that has a branch checked out

info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
info.path     #=> "/tmp/feature"
info.head     #=> "b8c63202c3c0ebd37b7e45fd0c22e6c20d5bead1"
info.locked?  #=> false

Returns:

  • one entry per worktree

Raises:

  • if git exits with a non-zero exit status

  • if the worktree listing cannot be parsed

See Also:

API:

  • private



44
45
46
47
 
# File 'lib/git/repository/worktree_operations.rb', line 44

def worktree_list
  result = Git::Commands::Worktree::List.new(@execution_context).call(porcelain: true)
  Git::Parsers::Worktree.parse_list(result.stdout)
end

#worktree_lock(worktree, opts = {}) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Lock a linked worktree so that git worktree prune leaves it alone

Lock a worktree whose directory is on removable media or a network share that is not always mounted.

Examples:

Lock a worktree

repo.worktree_lock('/tmp/feature')

Lock a worktree with a reason

repo.worktree_lock('/tmp/feature', reason: 'on an external drive')

Parameters:

  • the path of the worktree to lock, or its entry from #worktree_list

  • (defaults to: {})

    options for the lock

Options Hash (opts):

  • :reason (String, nil) — default: nil —

    an explanation stored with the lock and reported as WorktreeInfo#lock_reason

Returns:

  • the output from the git worktree lock command (typically empty)

Raises:

  • if unsupported options are provided

  • if git exits with a non-zero exit status

See Also:

API:

  • private



194
195
196
 
# File 'lib/git/repository/worktree_operations.rb', line 194

def worktree_lock(worktree, opts = {})
  Git::Commands::Worktree::Lock.new(@execution_context).call(worktree.to_s, **opts).stdout
end

#worktree_move(worktree, new_path, opts = {}) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Move a linked worktree to a new location

Examples:

Move a worktree

repo.worktree_move('/tmp/feature', '/tmp/feature-moved')

Move a locked worktree

repo.worktree_move('/tmp/feature', '/tmp/feature-moved', force: 2)

Parameters:

  • the path of the worktree to move, or its entry from #worktree_list

  • the destination path

  • (defaults to: {})

    options for the move

Options Hash (opts):

  • :force (Boolean, Integer, nil) — default: nil —

    override git's safeguards; git refuses to move a locked worktree unless the flag is given twice, so pass 2 for that

Returns:

  • the output from the git worktree move command (typically empty)

Raises:

  • if unsupported options are provided

  • if git exits with a non-zero exit status

See Also:

API:

  • private



162
163
164
 
# File 'lib/git/repository/worktree_operations.rb', line 162

def worktree_move(worktree, new_path, opts = {})
  Git::Commands::Worktree::Move.new(@execution_context).call(worktree.to_s, new_path, **opts).stdout
end

#worktree_prune ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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:

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

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



261
262
263
 
# File 'lib/git/repository/worktree_operations.rb', line 261

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

#worktree_remove(worktree) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Remove a linked worktree

Examples:

Remove a worktree by path

repo.worktree_remove('/tmp/feature')

Remove a worktree from the list

info = repo.worktree_list.find { |w| w.branch == 'refs/heads/feature' }
repo.worktree_remove(info)

Parameters:

  • the path of the worktree to remove, or its entry from #worktree_list

Returns:

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

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



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

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

#worktree_repair(*paths) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Repair the links between the repository and its linked worktrees

With no paths, repairs the link from each linked worktree back to the repository, which is needed after the repository directory was moved. Given the current paths of linked worktrees that were moved without #worktree_move, also repairs the repository's links to them.

Examples:

Repair after the repository directory was moved

repo.worktree_repair

Repair after a linked worktree was moved by hand

repo.worktree_repair('/new/path/to/feature')

Parameters:

  • the current paths of the worktrees to repair, or their entries from #worktree_list

Returns:

  • the output from the git worktree repair command, which reports each repair made

Raises:

  • if git exits with a non-zero exit status

  • if the installed git is older than 2.29.0

See Also:

API:

  • private



242
243
244
 
# File 'lib/git/repository/worktree_operations.rb', line 242

def worktree_repair(*paths)
  Git::Commands::Worktree::Repair.new(@execution_context).call(*paths.map(&:to_s)).stdout
end

#worktree_unlock(worktree) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Unlock a linked worktree

Examples:

Unlock a worktree

repo.worktree_unlock('/tmp/feature')

Parameters:

  • the path of the worktree to unlock, or its entry from #worktree_list

Returns:

  • the output from the git worktree unlock command (typically empty)

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



213
214
215
 
# File 'lib/git/repository/worktree_operations.rb', line 213

def worktree_unlock(worktree)
  Git::Commands::Worktree::Unlock.new(@execution_context).call(worktree.to_s).stdout
end

#worktrees ⇒ Git::Worktrees

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use #worktree_list instead

#worktree_list returns Array<Git::WorktreeInfo>. Look a worktree up by path with worktree_list.find { |w| w.path == path } in place of worktrees[path], and call #worktree_prune in place of worktrees.prune. Calling this method emits one deprecation warning.

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:

  • an enumerable collection of all worktrees

Raises:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



330
331
332
333
334
335
336
 
# File 'lib/git/repository/worktree_operations.rb', line 330

def worktrees
  Git::Deprecation.warn(
    'Git::Repository#worktrees is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#worktree_list instead.'
  )
  Git::Worktrees.new(self)
end

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

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use #worktree_list instead

#worktree_list returns one WorktreeInfo per worktree, with path and head in place of the pair, and includes the main worktree of a bare repository.

Returns all worktrees as an array of directory and SHA pairs

Lists the main worktree and all linked worktrees. The main worktree of a bare repository has no checked-out commit and is omitted.

Examples:

List all worktrees

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

Returns:

  • 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:

  • if git exits with a non-zero exit status

See Also:

API:

  • private



76
77
78
79
80
81
82
 
# File 'lib/git/repository/worktree_operations.rb', line 76

def worktrees_all
  Git::Deprecation.warn(
    'Git::Repository#worktrees_all is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#worktree_list instead.'
  )
  worktree_list.reject { |worktree| worktree.head.nil? }.map { |worktree| [worktree.path, worktree.head] }
end