Class: Git::Worktree

Inherits:
Object
  • Object
show all
Defined in:
lib/git/worktree.rb

Overview

A worktree in a Git repository

Represents a single linked or main worktree. Constructed by Repository::WorktreeOperations#worktree or populated by Worktrees.

Accepts either a Repository (new form) or a Base (legacy form) as the base argument. The is_a?(Git::Base) guard routes git operations through the facade repository and will be removed when Base is deleted in Phase 4.

Examples:

Add and remove a linked worktree

worktree = repo.worktree('/path/to/new-worktree')
worktree.add
worktree.remove

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(base, dir, gcommit = nil)

Creates a new Worktree object

Parameters:

  • base (Git::Base, Git::Repository) —

    the repository that owns this worktree

  • dir (String) —

    filesystem path of the worktree

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

    commitish associated with the worktree; when non-nil it is appended to #full



50
51
52
53
54
55
56
 
# File 'lib/git/worktree.rb', line 50

def initialize(base, dir, gcommit = nil)
  @full = dir
  @full += " #{gcommit}" unless gcommit.nil?
  @base = base
  @dir = dir
  @gcommit = gcommit
end

Instance Attribute Details

#dir ⇒ String

Filesystem path of this worktree

Returns:

  • (String) —

    the filesystem path of the worktree directory



36
37
38
 
# File 'lib/git/worktree.rb', line 36

def dir
  @dir
end

#full ⇒ String

Full worktree descriptor including the optional commitish

Returns:

  • (String) —

    the filesystem path, space-separated with the commitish when one was given at construction time



30
31
32
 
# File 'lib/git/worktree.rb', line 30

def full
  @full
end

Instance Method Details

#add ⇒ String

Creates this worktree on disk

Runs git worktree add for #dir, optionally at the commitish passed at construction time.

Examples:

Add a worktree

worktree = repo.worktree('/path/to/new-worktree')
worktree.add

Returns:

  • (String) —

    stdout from the git command

Raises:



97
98
99
 
# File 'lib/git/worktree.rb', line 97

def add
  worktree_repository.worktree_add(@dir, @gcommit)
end

#gcommit ⇒ Git::Object::Commit, String

Returns the commit (or commitish string) associated with this worktree

When a commitish string was supplied at construction time (e.g. by Git::Worktrees which passes the raw SHA from git worktree list), that string is returned as-is. Otherwise the value is lazily resolved on first call via worktree_repository.gcommit(@full) and the result is memoized.

Examples:

When resolved lazily (no commitish at construction)

worktree = repo.worktree('/path/to/wt')
worktree.gcommit  # => #<Git::Object::Commit ...>

When the commitish was given at construction

worktree = repo.worktrees['/path/to/wt']
worktree.gcommit  # => "4bef5ab8c9..."   (raw SHA string)

Returns:

  • (Git::Object::Commit, String) —

    a commit object when lazily resolved, or the raw commitish string when pre-set at construction

Raises:

  • (Git::FailedError) —

    if git must resolve the commit and exits with a non-zero exit status



79
80
81
82
 
# File 'lib/git/worktree.rb', line 79

def gcommit
  @gcommit ||= worktree_repository.gcommit(@full)
  @gcommit
end

#remove ⇒ String

Removes this worktree from disk

Runs git worktree remove for #dir.

Examples:

Remove a worktree

worktree.remove

Returns:

  • (String) —

    stdout from the git command (typically empty)

Raises:



112
113
114
 
# File 'lib/git/worktree.rb', line 112

def remove
  worktree_repository.worktree_remove(@dir)
end

#to_a ⇒ Array<String>

Returns an array containing the full worktree descriptor

Examples:

Get the descriptor array

worktree.to_a  # => ["/path/to/worktree"]

Returns:

  • (Array<String>) —

    array containing the full worktree descriptor



123
124
125
 
# File 'lib/git/worktree.rb', line 123

def to_a
  [@full]
end

#to_s ⇒ String

Returns the full worktree descriptor as a string

Examples:

Get the descriptor string

worktree.to_s  # => "/path/to/worktree"

Returns:

  • (String) —

    the full worktree descriptor (path and optional commitish)



134
135
136
 
# File 'lib/git/worktree.rb', line 134

def to_s
  @full
end