Class: Git::Worktree Deprecated

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

Overview

Deprecated.

Use Repository::WorktreeOperations#worktree_list and the path-based worktree operations on Repository instead

Repository::WorktreeOperations#worktree_list returns immutable WorktreeInfo value objects. Operations that lived on this class are called on the repository with the worktree path instead (for example Repository::WorktreeOperations#worktree_add and Repository::WorktreeOperations#worktree_remove). #gcommit, #add, and #remove each emit a deprecation warning; the dir, full, to_s, and to_a readers do not.

A worktree in a Git repository

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

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



54
55
56
57
58
59
60
 
# File 'lib/git/worktree.rb', line 54

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



40
41
42
 
# File 'lib/git/worktree.rb', line 40

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



34
35
36
 
# File 'lib/git/worktree.rb', line 34

def full
  @full
end

Instance Method Details

#add ⇒ String

Deprecated.

Use Repository::WorktreeOperations#worktree_add instead

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:

See Also:



117
118
119
120
121
122
123
 
# File 'lib/git/worktree.rb', line 117

def add
  Git::Deprecation.warn(
    'Git::Worktree#add is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#worktree_add instead.'
  )
  worktree_repository.worktree_add(@dir, @gcommit)
end

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

Deprecated.

Use Git::WorktreeInfo#head from Repository::WorktreeOperations#worktree_list instead

head is always the commit SHA as a String (or nil for a bare main worktree). Call repo.gcommit(info.head) for the commit object.

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

See Also:



91
92
93
94
95
96
97
98
 
# File 'lib/git/worktree.rb', line 91

def gcommit
  Git::Deprecation.warn(
    'Git::Worktree#gcommit is deprecated and will be removed in v6.0.0. ' \
    'Use Git::WorktreeInfo#head from Git::Repository#worktree_list instead.'
  )
  @gcommit ||= worktree_repository.gcommit(@full)
  @gcommit
end

#remove ⇒ String

Deprecated.

Use Repository::WorktreeOperations#worktree_remove instead

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:

See Also:



140
141
142
143
144
145
146
 
# File 'lib/git/worktree.rb', line 140

def remove
  Git::Deprecation.warn(
    'Git::Worktree#remove is deprecated and will be removed in v6.0.0. ' \
    'Use Git::Repository#worktree_remove instead.'
  )
  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



155
156
157
 
# File 'lib/git/worktree.rb', line 155

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)



166
167
168
 
# File 'lib/git/worktree.rb', line 166

def to_s
  @full
end