Module: Git::Repository::ContextHelpers Private

Included in:
Git::Repository
Defined in:
lib/git/repository/context_helpers.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 block-based directory and index context helpers

These helpers allow callers to temporarily change the working directory, the git index, or both, restoring the original state unconditionally when the block exits — even if the block raises an exception.

Included by Git::Repository.

Instance Method Summary collapse

Instance Method Details

#chdir {|dir| ... } ⇒ Object

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.

Changes the current working directory to the repository working directory for the duration of the block

Examples:

Write a file inside the repository working directory

repo.chdir do |dir|
  File.write('hello.txt', 'Hello, world!')
  repo.add('hello.txt')
end

Yields:

  • (dir) —

    the repository working directory

Yield Parameters:

  • dir (Pathname) —

    the working directory path

Yield Returns:

  • (Object) —

    returned as the method's return value

Returns:

  • (Object) —

    the value returned by the block

Raises:

  • (ArgumentError) —

    if the repository has no working directory (bare repository)



45
46
47
48
49
 
# File 'lib/git/repository/context_helpers.rb', line 45

def chdir
  raise ArgumentError, 'cannot chdir: repository has no working directory (bare repository)' if dir.nil?

  Dir.chdir(dir.to_s) { yield dir }
end

#set_index(index_file, check = nil, must_exist: nil)

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.

This method returns an undefined value.

Sets the git index to index_file and rebuilds the execution context

By default raises if index_file does not exist. Pass must_exist: false to skip the existence check (useful when the index will be created by git later).

Examples:

Set the index to a custom path

repo.set_index('/path/to/custom.index')

Parameters:

  • index_file (String, Pathname) —

    path to the new index file

  • check (Boolean, nil) (defaults to: nil) —

    deprecated positional argument — use must_exist: instead; emits a deprecation warning when non-nil

  • must_exist (Boolean, nil) (defaults to: nil) —

    when true (the default), raises ArgumentError if index_file does not exist on disk

Raises:

  • (ArgumentError) —

    if must_exist: true (the default) and index_file does not exist



227
228
229
230
231
232
 
# File 'lib/git/repository/context_helpers.rb', line 227

def set_index(index_file, check = nil, must_exist: nil)
  must_exist = context_helpers_deprecate_check_argument(check, must_exist)
  new_path = context_helpers_validate_path(index_file, must_exist)
  context_helpers_rebuild_context(git_index_file: new_path.to_s)
  nil
end

#set_working(work_dir, check = nil, must_exist: nil)

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.

This method returns an undefined value.

Sets the git working directory to work_dir and rebuilds the execution context

By default raises if work_dir does not exist. Pass must_exist: false to skip the existence check.

Examples:

Set the working directory to a custom path

repo.set_working('/path/to/working')

Parameters:

  • work_dir (String, Pathname) —

    path to the new working directory

  • check (Boolean, nil) (defaults to: nil) —

    deprecated positional argument — use must_exist: instead; emits a deprecation warning when non-nil

  • must_exist (Boolean, nil) (defaults to: nil) —

    when true (the default), raises ArgumentError if work_dir does not exist on disk

Raises:

  • (ArgumentError) —

    if must_exist: true (the default) and work_dir does not exist



256
257
258
259
260
261
 
# File 'lib/git/repository/context_helpers.rb', line 256

def set_working(work_dir, check = nil, must_exist: nil)
  must_exist = context_helpers_deprecate_check_argument(check, must_exist)
  new_path = context_helpers_validate_path(work_dir, must_exist)
  context_helpers_rebuild_context(git_work_dir: new_path.to_s)
  nil
end

#with_index(new_index) {|repo| ... } ⇒ Object

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.

Temporarily switches the git index to new_index for the duration of the block

Rebuilds the repository execution context to point to the new index file, yields self, then unconditionally restores the original execution context — even if the block raises an exception.

Deprecated form: a block that declares no positional parameter emits a deprecation warning, because v6.0.0 yields a separate repository instead of self.

Examples:

Read a tree into a custom index

repo.with_index('/tmp/custom.index') do |r|
  r.read_tree('HEAD')
end

Parameters:

  • new_index (String, Pathname) —

    path to the replacement index file

Yields:

  • (repo) —

    the repository instance with the new index active

Yield Parameters:

Yield Returns:

  • (Object) —

    returned as the method's return value

Returns:

  • (Object) —

    the value returned by the block



77
78
79
80
81
82
83
84
 
# File 'lib/git/repository/context_helpers.rb', line 77

def with_index(new_index, &block) # :yields: self
  context_helpers_warn_if_block_declares_no_parameter(:with_index, block)
  old_context = @execution_context
  set_index(new_index, must_exist: false)
  yield self
ensure
  @execution_context = old_context
end

#with_temp_index {|repo| ... } ⇒ Object

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.

Temporarily switches the git index to a new temporary file for the duration of the block, then removes the file

The temporary index file does not exist until git creates it on first write. A unique temporary directory is created to hold the index path, avoiding the risk of presenting an empty file to git (which git would reject as a corrupt index). The directory — and any files inside it — are removed unconditionally after the block exits, even if the block raises an exception.

Deprecated form: a block that declares no positional parameter emits a deprecation warning, because v6.0.0 yields a separate repository instead of self.

Examples:

Stage changes using a temporary index

repo.with_temp_index do |r|
  r.read_tree('HEAD')
  r.write_tree
end

Yields:

  • (repo) —

    the repository instance with the temporary index active

Yield Parameters:

Yield Returns:

  • (Object) —

    returned as the method's return value

Returns:

  • (Object) —

    the value returned by the block



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/git/repository/context_helpers.rb', line 114

def with_temp_index(&block) # :yields: self
  context_helpers_warn_if_block_declares_no_parameter(:with_temp_index, block)
  # Use a unique temp directory so the index file path is collision-free
  # and does not exist until git writes it. An existing empty file would
  # be treated as a corrupt index by git.
  temp_dir = Dir.mktmpdir('git-temp-index-')
  begin
    # The inner block declares a parameter so with_index does not warn a
    # second time under its own name; forwarding &block would.
    # rubocop:disable-next Style/ExplicitBlockArgument
    with_index(File.join(temp_dir, 'index')) { |repo| yield repo }
  ensure
    FileUtils.remove_entry(temp_dir, true)
  end
end

#with_temp_working {|repo| ... } ⇒ Object

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.

Temporarily switches the git working directory to a new temporary directory for the duration of the block, then removes the directory and its contents

The temporary directory is removed unconditionally after the block exits, even if the block raises an exception.

Deprecated form: a block that declares no positional parameter emits a deprecation warning, because v6.0.0 yields a separate repository instead of self.

Examples:

Write files in an isolated temporary working directory

repo.with_temp_working do |r|
  File.write('scratch.txt', 'temporary content')
  r.add('scratch.txt')
end

Yields:

  • (repo) —

    the repository instance with the temporary working directory active

Yield Parameters:

Yield Returns:

  • (Object) —

    returned as the method's return value

Returns:

  • (Object) —

    the value returned by the block



197
198
199
200
201
202
203
 
# File 'lib/git/repository/context_helpers.rb', line 197

def with_temp_working(&block) # :yields: self
  context_helpers_warn_if_block_declares_no_parameter(:with_temp_working, block)
  # The inner block declares a parameter so with_working does not warn a
  # second time under its own name; forwarding &block would.
  # rubocop:disable-next Style/ExplicitBlockArgument
  Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir) { |repo| yield repo } }
end

#with_working(work_dir) {|repo| ... } ⇒ Object

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.

Temporarily switches the git working directory to work_dir for the duration of the block

Rebuilds the repository execution context to point to the new working directory, changes the process working directory via Dir.chdir, yields self, then unconditionally restores the original execution context — even if the block raises an exception.

Deprecated form: a block that declares no positional parameter emits a deprecation warning, because v6.0.0 yields a separate repository instead of self.

Examples:

Commit changes from a different worktree path

repo.with_working('/path/to/worktree') do |r|
  r.add('.')
  r.commit('chore: automated update')
end

Parameters:

  • work_dir (String, Pathname) —

    path to the replacement working directory

Yields:

  • (repo) —

    the repository instance with the new working directory active

Yield Parameters:

Yield Returns:

  • (Object) —

    returned as the method's return value

Returns:

  • (Object) —

    the value returned by the block

Raises:

  • (ArgumentError) —

    if work_dir does not exist on disk



162
163
164
165
166
167
168
169
 
# File 'lib/git/repository/context_helpers.rb', line 162

def with_working(work_dir, &block) # :yields: self
  context_helpers_warn_if_block_declares_no_parameter(:with_working, block)
  old_context = @execution_context
  set_working(work_dir)
  Dir.chdir(dir.to_s) { yield self }
ensure
  @execution_context = old_context
end