Module: Git::Repository::Factories Private

Included in:
Git
Defined in:
lib/git/repository/factories.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.

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.

Instance Method Summary collapse

Instance Method Details

#bare(git_dir, options = {}) ⇒ Git::Repository

Open an existing bare repository at git_dir

Examples:

Open a bare repository

repository = Git.bare('/path/to/repo.git')

Parameters:

  • git_dir (String) —

    the path to the bare repository directory

  • options (Hash) (defaults to: {}) —

    options used to configure the repository instance

Options Hash (options):

  • :log (Logger, nil) —

    logger used for git operations

  • :git_ssh (String, nil, :use_global_config) —

    path to a custom SSH executable

    Pass :use_global_config (the default) to use Git.config.git_ssh.

  • :binary_path (String, :use_global_config) —

    path to the git binary

    Pass :use_global_config (the default) to use Git.config.binary_path.

Returns:

  • (Git::Repository) —

    a repository bound to the bare repository directory



333
334
335
336
337
 
# File 'lib/git/repository/factories.rb', line 333

def bare(git_dir, options = {})
  paths = PathResolver.resolve_paths(repository: git_dir, bare: true)

  from_paths(options, paths)
end

#clone(repository_url, directory = nil, options = {}) ⇒ Git::Repository

Clone a repository into a new directory

Examples:

Clone into the default directory

repository = Git.clone('https://github.com/ruby-git/ruby-git.git')

Clone into a specific directory

repo_url = 'https://github.com/ruby-git/ruby-git.git'
repository = Git.clone(repo_url, 'local')

Clone a bare repository

repo_url = 'https://github.com/ruby-git/ruby-git.git'
repository = Git.clone(repo_url, nil, bare: true)

Parameters:

  • repository_url (String, URI, Pathname) —

    the URL or path of the repository to clone

  • directory (String, Pathname, nil) (defaults to: nil) —

    the local directory name to clone into; git derives the name from the URL when nil

  • options (Hash) (defaults to: {}) —

    options that control cloning

    Some options configure the returned Git::Repository instance after the clone completes. Supported git clone options are forwarded.

Options Hash (options):

  • :template (String, nil) —

    template directory to use

  • :local (Boolean, nil) —

    use the local clone optimization

  • :no_local (Boolean, nil) —

    disable the local clone optimization

  • :shared (Boolean, nil) —

    set up a shared clone

  • :no_hardlinks (Boolean, nil) —

    copy files instead of hardlinks

  • :quiet (Boolean, nil) —

    suppress progress output

  • :verbose (Boolean, nil) —

    run verbosely

  • :progress (Boolean, nil) —

    force progress output

  • :no_checkout (Boolean, nil) —

    skip checking out HEAD

  • :bare (Boolean, nil) —

    clone as a bare repository

  • :mirror (Boolean, nil) —

    set up a mirror of the source (implies :bare)

  • :origin (String, nil) —

    remote name to use instead of origin

  • :branch (String, nil) —

    the branch or tag to check out after cloning

  • :revision (String, nil) —

    revision to check out after cloning

  • :upload_pack (String, nil) —

    remote git-upload-pack path

  • :reference (String, Array<String>, nil) —

    reference repository

  • :reference_if_able (String, Array<String>, nil) —

    optional reference repository

  • :dissociate (Boolean, nil) —

    stop borrowing from references

  • :separate_git_dir (String, nil) —

    alternate git directory path

  • :server_option (String, Array<String>, nil) —

    protocol-v2 server options

  • :depth (Integer, String, nil) —

    create a shallow clone

  • :shallow_since (String, nil) —

    create a shallow clone by date

  • :shallow_exclude (String, Array<String>, nil) —

    exclude commits reachable from a ref

  • :single_branch (Boolean, nil) —

    clone one branch's history

  • :no_single_branch (Boolean, nil) —

    clone all branch history

  • :tags (Boolean, nil) —

    include tags in the clone

  • :no_tags (Boolean, nil) —

    exclude tags from the clone

  • :recurse_submodules (Boolean, String, Array<String>, nil) —

    initialize submodules after cloning

    Pass true to initialize all submodules, or pass a pathspec string or array for a subset.

  • :shallow_submodules (Boolean, nil) —

    use depth 1 for submodules

  • :no_shallow_submodules (Boolean, nil) —

    use full submodule history

  • :remote_submodules (Boolean, nil) —

    use submodule remote branches

  • :no_remote_submodules (Boolean, nil) —

    use recorded submodule SHAs

  • :jobs (Integer, String, nil) —

    submodule jobs to run concurrently

  • :sparse (Boolean, nil) —

    enable sparse checkout

  • :reject_shallow (Boolean, nil) —

    reject shallow source repositories

  • :no_reject_shallow (Boolean, nil) —

    allow shallow sources

  • :filter (String, nil) —

    specify a partial clone filter

  • :also_filter_submodules (Boolean, nil) —

    filter submodules too

  • :config (String, Array<String>, nil) —

    repository config entries

  • :bundle_uri (String, nil) —

    bundle URI to prefetch

  • :ref_format (String, nil) —

    ref storage format

  • :timeout (Numeric, nil) —

    command timeout in seconds

  • :repository (String, nil) —

    alternate git directory path

    Preferred facade spelling for git clone --separate-git-dir.

  • :git_ssh (String, nil, :use_global_config) —

    path to a custom SSH executable

    Pass :use_global_config (the default) to use Git.config.git_ssh.

  • :binary_path (String, :use_global_config) —

    path to the git binary

    Pass :use_global_config (the default) to use Git.config.binary_path.

  • :log (Logger, nil) —

    logger used for git operations

  • :index (String, nil) —

    a non-standard path to the index file

  • :chdir (String, Pathname, nil) —

    run git clone from within this directory

  • :path (String, Pathname, nil) —

    deprecated; use :chdir instead

  • :recursive (Boolean, nil) —

    deprecated; use :recurse_submodules instead

  • :remote (String, nil) —

    deprecated; use :origin instead

Returns:

  • (Git::Repository) —

    a repository bound to the cloned working copy or bare repository

Raises:

  • (ArgumentError) —

    if unsupported options are provided

  • (Git::FailedError) —

    if git exits with a non-zero exit status

  • (Git::UnexpectedResultError) —

    if the cloned directory cannot be determined from git's output



178
179
180
181
182
183
184
 
# File 'lib/git/repository/factories.rb', line 178

def clone(repository_url, directory = nil, options = {})
  opts, context_opts = prepare_clone_options(options)
  clone_result = run_clone_command(repository_url, directory, opts, context_opts)
  paths = resolve_paths_from_clone_result(clone_result, opts, context_opts)

  from_paths(clone_repository_options(context_opts), paths)
end

#init(directory = '.', options = {}) ⇒ Git::Repository

Create an empty Git repository or reinitialize an existing one

Examples:

Initialize in the current directory

repository = Git.init

Initialize in a specific directory

repository = Git.init('/path/to/project')

Initialize a bare repository

repository = Git.init('/path/to/project.git', bare: true)

Parameters:

  • directory (String) (defaults to: '.') —

    the directory to initialize; defaults to '.'

  • options (Hash) (defaults to: {}) —

    options that control initialization

    Some options configure the returned Git::Repository instance after the repository is initialized.

Options Hash (options):

  • :bare (Boolean, nil) —

    create a bare repository at directory

  • :initial_branch (String, nil) —

    the name for the initial branch

  • :repository (String, nil) —

    path for the .git directory

    Writes a gitfile in the working tree. Alias: :separate_git_dir.

  • :separate_git_dir (String, nil) —

    alias for :repository

  • :git_ssh (String, nil, :use_global_config) —

    path to a custom SSH executable

    Pass :use_global_config (the default) to use Git.config.git_ssh.

  • :binary_path (String, :use_global_config) —

    path to the git binary

    Pass :use_global_config (the default) to use Git.config.binary_path.

  • :log (Logger, nil) —

    logger used for git operations

  • :index (String, nil) —

    custom index path for the returned repository

    Ignored when :bare is true.

Returns:

  • (Git::Repository) —

    a repository bound to the newly initialized repository

Raises:



239
240
241
242
243
244
245
246
247
 
# File 'lib/git/repository/factories.rb', line 239

def init(directory = '.', options = {})
  options = options.dup
  if options.key?(:separate_git_dir) && options[:repository].nil?
    options[:repository] = options.delete(:separate_git_dir)
  end

  run_init_command(directory, options)
  open_after_init(directory, options)
end

#open(working_dir, options = {}) ⇒ Git::Repository

Note:

This method opens working copies only. To open a bare repository, use Git.bare.

Open a working copy at an existing path

Examples:

Open the working copy in the current directory

repository = Git.open('.')

Parameters:

  • working_dir (String) —

    the path to the root of the working copy

    May be any path inside the working tree when :repository is not given.

  • options (Hash) (defaults to: {}) —

    options that control how the repository is located

Options Hash (options):

  • :repository (String, nil) —

    a non-standard path to the .git directory

    When given, working_dir is used as-is (the working tree root is not auto-detected).

  • :index (String, nil) —

    a non-standard path to the index file

  • :log (Logger, nil) —

    logger used for git operations

  • :git_ssh (String, nil, :use_global_config) —

    path to a custom SSH executable

    Pass :use_global_config (the default) to use Git.config.git_ssh.

  • :binary_path (String, :use_global_config) —

    path to the git binary

    Pass :use_global_config (the default) to use Git.config.binary_path.

Returns:

Raises:

  • (ArgumentError) —

    if working_dir is not a directory or is not inside a git working tree



292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/git/repository/factories.rb', line 292

def open(working_dir, options = {})
  raise ArgumentError, "'#{working_dir}' is not a directory" unless Dir.exist?(working_dir)

  working_dir = resolve_open_working_dir(working_dir, options) unless options[:repository]

  paths = PathResolver.resolve_paths(
    working_directory: working_dir,
    repository: options[:repository],
    index: options[:index]
  )

  from_paths(options, paths)
end