module Git::Repository::Factories

Implementation of the {Git} module factory entry points

Provides ‘.open`, `.init`, `.clone`, and `.bare` — the four methods that construct a {Git::Repository}. Extended onto the {Git} module so that `Git.open(…)`, `Git.init(…)`, etc. resolve here.

@api private

Private Instance Methods

base_open_options_after_init (options)

Source

# File lib/git/repository/factories.rb, line 681
def base_open_options_after_init(options)
  {
    git_ssh: options.fetch(:git_ssh, :use_global_config),
    binary_path: options.fetch(:binary_path, :use_global_config)
  }.tap do |open_opts|
    open_opts[:log] = options[:log] if options[:log]
  end
end

Build common options for opening a repository after ‘git init`

@param options [Hash] the normalized options hash

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [Logger, nil] :log logger used for git operations

@return [Hash{Symbol => Object}] options accepted by {.open} and {.bare}

@api private

clone_repository_options (context_opts)

Source

# File lib/git/repository/factories.rb, line 424
def clone_repository_options(context_opts)
  {
    git_ssh: context_opts[:git_ssh],
    binary_path: context_opts[:binary_path],
    log: context_opts[:logger]
  }
end

Build repository construction options from clone context options

@param context_opts [Hash] context options produced while preparing clone

options

@return [Hash{Symbol => Object}] repository construction options

@api private

context_defaults (options)

Source

# File lib/git/repository/factories.rb, line 453
def context_defaults(options)
  {
    binary_path: options.fetch(:binary_path, :use_global_config),
    git_ssh: options.fetch(:git_ssh, :use_global_config)
  }
end

Build the ‘:binary_path` and `:git_ssh` execution-context defaults

Reads the values from the caller-supplied options, falling back to the ‘:use_global_config` sentinel for any the caller did not provide so the value is resolved from `Git::Config.instance` at call time.

@param options [Hash] the caller-supplied options hash

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@return [Hash] context defaults with two keys: ‘:binary_path`

(`String` or `:use_global_config` — `nil` is not valid and raises
`ArgumentError` in {Git::ExecutionContext#initialize}) and `:git_ssh`
(`String`, `nil`, or `:use_global_config`)

@api private

deprecate_clone_path_option! (opts)

Source

# File lib/git/repository/factories.rb, line 749
def deprecate_clone_path_option!(opts)
  return unless opts.key?(:path)

  if defined?(Git::Deprecation)
    Git::Deprecation.warn(
      'The :path option for Git.clone is deprecated and will be removed in v6.0.0. ' \
      'Use :chdir instead.'
    )
  end
  path = opts.delete(:path)
  opts[:chdir] ||= path
end

Handle the deprecated ‘:path` option for {clone}

@param opts [Hash] clone options (mutated in place)

@option opts [String, Pathname, nil] :path deprecated; use ‘:chdir`

instead

@option opts [String, Pathname, nil] :chdir run ‘git clone` from within

this directory

@return [void] mutates ‘opts` in place

@api private

deprecate_clone_recursive_option! (opts)

Source

# File lib/git/repository/factories.rb, line 776
def deprecate_clone_recursive_option!(opts)
  return unless opts.key?(:recursive)

  if defined?(Git::Deprecation)
    Git::Deprecation.warn(
      'The :recursive option for Git.clone is deprecated and will be removed in v6.0.0. ' \
      'Use :recurse_submodules instead.'
    )
  end
  opts[:recurse_submodules] = opts.delete(:recursive)
end

Handle the deprecated ‘:recursive` option for {clone}

@param opts [Hash] clone options (mutated in place)

@option opts [Boolean, nil] :recursive deprecated; use

`:recurse_submodules` instead

@option opts [Boolean, String, Array<String>, nil] :recurse_submodules

initialize submodules after cloning

@return [void] mutates ‘opts` in place

@api private

deprecate_clone_remote_option! (opts)

Source

# File lib/git/repository/factories.rb, line 801
def deprecate_clone_remote_option!(opts)
  return unless opts.key?(:remote)

  if defined?(Git::Deprecation)
    Git::Deprecation.warn(
      'The :remote option for Git.clone is deprecated and will be removed in v6.0.0. ' \
      'Use :origin instead.'
    )
  end
  opts[:origin] = opts.delete(:remote)
end

Handle the deprecated ‘:remote` option for {clone}

@param opts [Hash] clone options (mutated in place)

@option opts [String, nil] :remote deprecated; use ‘:origin` instead

@option opts [String, nil] :origin remote name to use instead of

`origin`

@return [void] mutates ‘opts` in place

@api private

extract_clone_context_options! (opts)

Source

# File lib/git/repository/factories.rb, line 554
def extract_clone_context_options!(opts)
  {
    logger: opts.delete(:log),
    git_ssh: opts.key?(:git_ssh) ? opts.delete(:git_ssh) : :use_global_config,
    binary_path: opts.key?(:binary_path) ? opts.delete(:binary_path) : :use_global_config,
    index: opts.delete(:index)
  }
end

Extract clone context options from command-ready options

@param opts [Hash] clone options (mutated in place)

@option opts [Logger, nil] :log logger used for clone operations

@option opts [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@option opts [String, :use_global_config] :binary_path path to the git

binary

@option opts [String, nil] :index custom index path for the returned

repository

@return [Hash{Symbol => Object}] context options for clone setup

@api private

from_paths (options, paths)

Source

# File lib/git/repository/factories.rb, line 501
def from_paths(options, paths)
  Git::Repository.new(execution_context: Git::ExecutionContext::Repository.from_hash(
    options.merge(paths), logger: options[:log]
  ))
end

Build a repository from caller options and resolved paths

@param options [Hash] the caller-supplied options (‘:git_ssh`,

`:binary_path`, `:log`)

@param paths [Hash{Symbol => (String, nil)}] the resolved paths

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [Logger, nil] :log logger used for git operations

@return [Git::Repository] the constructed repository

@api private

normalize_clone_repository_option! (opts)

Source

# File lib/git/repository/factories.rb, line 573
def normalize_clone_repository_option!(opts)
  return unless opts.key?(:repository)

  repository_val = opts.delete(:repository)
  opts[:separate_git_dir] = repository_val if repository_val
end

Normalize the clone repository option for ‘git clone`

@param opts [Hash] clone options (mutated in place)

@option opts [String, nil] :repository alternate git directory path

@return [void] mutates ‘opts` in place

@api private

open_after_init (directory, options)

Source

# File lib/git/repository/factories.rb, line 659
def open_after_init(directory, options)
  return bare(options[:repository] || directory, base_open_options_after_init(options)) if options[:bare]

  self.open(directory, worktree_open_options_after_init(options))
end

Open the repository produced by ‘git init`

@param directory [String] the initialized directory

@param options [Hash] the normalized options hash

@option options [Boolean, nil] :bare create a bare repository at

`directory`

@option options [String, nil] :repository path for the ‘.git` directory

@option options [String, nil] :index custom index path for the returned

repository

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@option options [Logger, nil] :log logger used for git operations

@return [Git::Repository] the repository opened after initialization

@api private

parse_clone_stderr (stderr)

Source

# File lib/git/repository/factories.rb, line 728
def parse_clone_stderr(stderr)
  match = stderr.match(/Cloning into (?:(bare repository) )?'(.+)'\.\.\./)
  raise Git::UnexpectedResultError, "Unable to determine clone directory from: #{stderr}" unless match

  [match[2], !match[1].nil?]
end

Parse the clone directory and bare status from ‘git clone` stderr output

@param stderr [String] stderr output from ‘git clone`

@return [Array] a two-element tuple ‘[clone_dir, bare]`

@raise [Git::UnexpectedResultError] if the stderr output cannot be parsed

@api private

prepare_clone_options (options)

Source

# File lib/git/repository/factories.rb, line 524
def prepare_clone_options(options)
  opts = options.dup
  deprecate_clone_path_option!(opts)
  deprecate_clone_recursive_option!(opts)
  deprecate_clone_remote_option!(opts)
  context_opts = extract_clone_context_options!(opts)
  normalize_clone_repository_option!(opts)

  [opts, context_opts]
end

Extract facade-level options from the raw clone options and return command-ready options

Returns ‘[command_opts, context_opts]` where `command_opts` is the caller’s options with facade-level keys removed. Remaining keys are forwarded to ‘Git::Commands::Clone`, which raises `ArgumentError` for unsupported ones. `context_opts` contains values used for the execution context and post-clone path resolution.

@param options [Hash] raw caller-supplied options

@option options [Boolean, nil] :bare clone as a bare repository

@return [Array<Hash>] a two-element tuple ‘[command_opts, context_opts]`

@api private

resolve_clone_paths (clone_dir, bare, index)

Source

# File lib/git/repository/factories.rb, line 592
def resolve_clone_paths(clone_dir, bare, index)
  args = bare ? { repository: clone_dir, bare: true } : { working_directory: clone_dir }
  PathResolver.resolve_paths(**args, index: index)
end

Resolve paths for the cloned repository

@param clone_dir [String] the directory reported by ‘git clone`

@param bare [Boolean] whether the clone is bare

@param index [String, nil] optional custom index path

@return [Hash{Symbol => (String, nil)}] resolved path hash

@api private

resolve_open_working_dir (working_dir, options)

Source

# File lib/git/repository/factories.rb, line 478
def resolve_open_working_dir(working_dir, options)
  PathResolver.root_of_worktree(working_dir, **context_defaults(options))
end

Resolve the worktree root to use as the working directory for {.open}

@param working_dir [String] a path inside the working tree

@param options [Hash] the caller-supplied options hash from {.open}

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@return [String] the absolute path to the root of the working tree

@raise [ArgumentError] if ‘working_dir` is not inside a git working tree

@api private

resolve_paths_from_clone_result (clone_result, opts, context_opts)

Source

# File lib/git/repository/factories.rb, line 406
def resolve_paths_from_clone_result(clone_result, opts, context_opts)
  clone_dir, cloned_bare = parse_clone_stderr(clone_result.stderr)
  chdir = opts[:chdir]
  clone_dir = File.join(chdir, clone_dir) if chdir && !Pathname.new(clone_dir).absolute?

  bare = opts[:bare] || opts[:mirror] || cloned_bare
  resolve_clone_paths(clone_dir, bare, context_opts[:index])
end

Resolve repository paths from a completed clone result

@param clone_result [Git::CommandLine::Result] the completed clone result

@param opts [Hash] command-ready clone options

@param context_opts [Hash] context options produced while preparing clone

options

@option opts [String, Pathname, nil] :chdir run ‘git clone` from within

this directory

@option opts [Boolean, nil] :bare clone as a bare repository

@option opts [Boolean, nil] :mirror set up a mirror of the source

@option context_opts [String, nil] :index custom index path for the

returned repository

@return [Hash{Symbol => (String, nil)}] resolved path hash

@raise [Git::UnexpectedResultError] if the clone directory cannot be parsed

@api private

run_clone_command (repository_url, directory, opts, context_opts)

Source

# File lib/git/repository/factories.rb, line 371
def run_clone_command(repository_url, directory, opts, context_opts)
  context = Git::ExecutionContext::Global.new(
    binary_path: context_opts[:binary_path],
    git_ssh: context_opts[:git_ssh],
    logger: context_opts[:logger]
  )

  Git::Commands::Clone.new(context).call(repository_url, directory, **opts)
end

Run the ‘git clone` command using a global execution context

@param repository_url [String, URI, Pathname] the URL or path of the repository to clone

@param directory [String, Pathname, nil] the local directory name to clone into

@param opts [Hash] command-ready clone options

@param context_opts [Hash] context options produced while preparing clone

options

@option opts [Boolean, nil] :bare clone as a bare repository

@option context_opts [String, :use_global_config] :binary_path path to

the git binary

@option context_opts [String, nil, :use_global_config] :git_ssh path to

a custom SSH executable

@option context_opts [Logger, nil] :logger logger used for clone

operations

@return [Git::CommandLine::Result] the result of running ‘git clone`

@raise [ArgumentError] if unsupported options are provided

@raise [Git::FailedError] if git exits with a non-zero exit status

@api private

run_init_command (directory, options)

Source

# File lib/git/repository/factories.rb, line 625
def run_init_command(directory, options)
  init_opts = options.slice(:bare, :initial_branch)
  init_opts[:separate_git_dir] = options[:repository] if options.key?(:repository)

  context = Git::ExecutionContext::Global.new(**context_defaults(options), logger: options[:log])
  Git::Commands::Init.new(context).call(directory, **init_opts)
end

Run the ‘git init` command using a global execution context

@param directory [String] the directory to initialize

@param options [Hash] the normalized options hash (after alias resolution)

@option options [Boolean, nil] :bare create a bare repository at

`directory`

@option options [String, nil] :initial_branch the name for the initial

branch

@option options [String, nil] :repository path for the ‘.git` directory

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@option options [Logger, nil] :log logger used for git operations

@return [Git::CommandLine::Result] the result of running ‘git init`

@raise [Git::FailedError] if git exits with a non-zero exit status

@api private

worktree_open_options_after_init (options)

Source

# File lib/git/repository/factories.rb, line 711
def worktree_open_options_after_init(options)
  base_open_options_after_init(options).tap do |open_opts|
    open_opts[:index] = options[:index] if options[:index]
    open_opts[:repository] = options[:repository] if options[:repository]
  end
end

Build worktree options for opening a repository after ‘git init`

@param options [Hash] the normalized options hash

@option options [String, nil, :use_global_config] :git_ssh path to a

custom SSH executable

@option options [String, :use_global_config] :binary_path path to the

git binary

@option options [Logger, nil] :log logger used for git operations

@option options [String, nil] :index custom index path for the returned

repository

@option options [String, nil] :repository path for the ‘.git` directory

@return [Hash{Symbol => Object}] options accepted by {.open}

@api private