Module: Git

Extended by:
Configuring
Defined in:
lib/git.rb,
lib/git.rb,
lib/git/log.rb,
lib/git/url.rb,
lib/git/diff.rb,
lib/git/stash.rb,
lib/git/author.rb,
lib/git/branch.rb,
lib/git/config.rb,
lib/git/errors.rb,
lib/git/object.rb,
lib/git/remote.rb,
lib/git/status.rb,
lib/git/status.rb,
lib/git/status.rb,
lib/git/stashes.rb,
lib/git/version.rb,
lib/git/branches.rb,
lib/git/commands.rb,
lib/git/file_ref.rb,
lib/git/tag_info.rb,
lib/git/worktree.rb,
lib/git/diff_info.rb,
lib/git/worktrees.rb,
lib/git/diff_stats.rb,
lib/git/repository.rb,
lib/git/stash_info.rb,
lib/git/branch_info.rb,
lib/git/commands/am.rb,
lib/git/commands/gc.rb,
lib/git/commands/mv.rb,
lib/git/commands/rm.rb,
lib/git/configuring.rb,
lib/git/deprecation.rb,
lib/git/diff_result.rb,
lib/git/fsck_object.rb,
lib/git/fsck_result.rb,
lib/git/parsers/tag.rb,
lib/git/args_builder.rb,
lib/git/command_line.rb,
lib/git/commands/add.rb,
lib/git/commands/log.rb,
lib/git/commands/tag.rb,
lib/git/dirstat_info.rb,
lib/git/escaped_path.rb,
lib/git/parsers/diff.rb,
lib/git/parsers/fsck.rb,
lib/git/parsers/grep.rb,
lib/git/commands/base.rb,
lib/git/commands/diff.rb,
lib/git/commands/fsck.rb,
lib/git/commands/grep.rb,
lib/git/commands/init.rb,
lib/git/commands/pull.rb,
lib/git/commands/push.rb,
lib/git/commands/show.rb,
lib/git/parsers/stash.rb,
lib/git/commands/apply.rb,
lib/git/commands/clean.rb,
lib/git/commands/clone.rb,
lib/git/commands/fetch.rb,
lib/git/commands/merge.rb,
lib/git/commands/reset.rb,
lib/git/commands/stash.rb,
lib/git/encoding_utils.rb,
lib/git/parsers/branch.rb,
lib/git/commands/branch.rb,
lib/git/commands/commit.rb,
lib/git/commands/remote.rb,
lib/git/commands/repack.rb,
lib/git/commands/revert.rb,
lib/git/commands/status.rb,
lib/git/parsers/ls_tree.rb,
lib/git/commands/am/quit.rb,
lib/git/commands/am/skip.rb,
lib/git/commands/archive.rb,
lib/git/commands/ls_tree.rb,
lib/git/commands/version.rb,
lib/git/diff_path_status.rb,
lib/git/parsers/cat_file.rb,
lib/git/command_line/base.rb,
lib/git/commands/am/abort.rb,
lib/git/commands/am/apply.rb,
lib/git/commands/am/retry.rb,
lib/git/commands/cat_file.rb,
lib/git/commands/checkout.rb,
lib/git/commands/describe.rb,
lib/git/commands/ls_files.rb,
lib/git/commands/name_rev.rb,
lib/git/commands/show_ref.rb,
lib/git/commands/tag/list.rb,
lib/git/commands/worktree.rb,
lib/git/config_entry_info.rb,
lib/git/execution_context.rb,
lib/git/parsers/ls_remote.rb,
lib/git/tag_delete_result.rb,
lib/git/commands/arguments.rb,
lib/git/commands/ls_remote.rb,
lib/git/commands/read_tree.rb,
lib/git/commands/rev_parse.rb,
lib/git/commands/stash/pop.rb,
lib/git/detached_head_info.rb,
lib/git/diff_file_raw_info.rb,
lib/git/repository/diffing.rb,
lib/git/repository/logging.rb,
lib/git/repository/merging.rb,
lib/git/repository/staging.rb,
lib/git/tag_delete_failure.rb,
lib/git/version_constraint.rb,
lib/git/command_line/result.rb,
lib/git/command_line_result.rb,
lib/git/commands/diff_files.rb,
lib/git/commands/diff_index.rb,
lib/git/commands/merge/quit.rb,
lib/git/commands/merge_base.rb,
lib/git/commands/remote/add.rb,
lib/git/commands/stash/drop.rb,
lib/git/commands/stash/list.rb,
lib/git/commands/stash/push.rb,
lib/git/commands/stash/show.rb,
lib/git/commands/tag/create.rb,
lib/git/commands/tag/delete.rb,
lib/git/commands/tag/verify.rb,
lib/git/commands/update_ref.rb,
lib/git/commands/write_tree.rb,
lib/git/repository/stashing.rb,
lib/git/branch_delete_result.rb,
lib/git/commands/am/continue.rb,
lib/git/commands/branch/copy.rb,
lib/git/commands/branch/list.rb,
lib/git/commands/branch/move.rb,
lib/git/commands/commit_tree.rb,
lib/git/commands/maintenance.rb,
lib/git/commands/merge/abort.rb,
lib/git/commands/merge/start.rb,
lib/git/commands/remote/list.rb,
lib/git/commands/remote/show.rb,
lib/git/commands/revert/quit.rb,
lib/git/commands/revert/skip.rb,
lib/git/commands/stash/apply.rb,
lib/git/commands/stash/clear.rb,
lib/git/commands/stash/store.rb,
lib/git/diff_file_patch_info.rb,
lib/git/parsers/config_entry.rb,
lib/git/repository/branching.rb,
lib/git/repository/factories.rb,
lib/git/branch_delete_failure.rb,
lib/git/commands/cat_file/raw.rb,
lib/git/commands/remote/prune.rb,
lib/git/commands/revert/abort.rb,
lib/git/commands/revert/start.rb,
lib/git/commands/stash/branch.rb,
lib/git/commands/stash/create.rb,
lib/git/commands/symbolic_ref.rb,
lib/git/commands/worktree/add.rb,
lib/git/repository/committing.rb,
lib/git/repository/inspecting.rb,
lib/git/command_line/capturing.rb,
lib/git/command_line/streaming.rb,
lib/git/commands/branch/create.rb,
lib/git/commands/branch/delete.rb,
lib/git/commands/remote/remove.rb,
lib/git/commands/remote/rename.rb,
lib/git/commands/remote/update.rb,
lib/git/commands/show_ref/list.rb,
lib/git/commands/worktree/list.rb,
lib/git/commands/worktree/lock.rb,
lib/git/commands/worktree/move.rb,
lib/git/diff_file_numstat_info.rb,
lib/git/repository/maintenance.rb,
lib/git/commands/cat_file/batch.rb,
lib/git/commands/checkout/files.rb,
lib/git/commands/checkout_index.rb,
lib/git/commands/merge/continue.rb,
lib/git/commands/remote/get_url.rb,
lib/git/commands/remote/set_url.rb,
lib/git/commands/worktree/prune.rb,
lib/git/commands/checkout/branch.rb,
lib/git/commands/maintenance/run.rb,
lib/git/commands/remote/set_head.rb,
lib/git/commands/revert/continue.rb,
lib/git/commands/show_ref/exists.rb,
lib/git/commands/show_ref/verify.rb,
lib/git/commands/worktree/remove.rb,
lib/git/commands/worktree/repair.rb,
lib/git/commands/worktree/unlock.rb,
lib/git/execution_context/global.rb,
lib/git/repository/path_resolver.rb,
lib/git/commands/maintenance/stop.rb,
lib/git/commands/update_ref/batch.rb,
lib/git/repository/shared_private.rb,
lib/git/commands/cat_file/filtered.rb,
lib/git/commands/maintenance/start.rb,
lib/git/commands/symbolic_ref/read.rb,
lib/git/commands/update_ref/delete.rb,
lib/git/commands/update_ref/update.rb,
lib/git/repository/context_helpers.rb,
lib/git/commands/remote/set_url_add.rb,
lib/git/commands/branch/set_upstream.rb,
lib/git/commands/branch/show_current.rb,
lib/git/commands/remote/set_branches.rb,
lib/git/commands/symbolic_ref/delete.rb,
lib/git/commands/symbolic_ref/update.rb,
lib/git/execution_context/repository.rb,
lib/git/repository/object_operations.rb,
lib/git/repository/remote_operations.rb,
lib/git/repository/status_operations.rb,
lib/git/commands/archive/list_formats.rb,
lib/git/commands/config_option_syntax.rb,
lib/git/commands/maintenance/register.rb,
lib/git/commands/am/show_current_patch.rb,
lib/git/commands/branch/unset_upstream.rb,
lib/git/commands/remote/set_url_delete.rb,
lib/git/repository/worktree_operations.rb,
lib/git/commands/maintenance/unregister.rb,
lib/git/commands/config_option_syntax/add.rb,
lib/git/commands/config_option_syntax/get.rb,
lib/git/commands/config_option_syntax/set.rb,
lib/git/commands/worktree/management_base.rb,
lib/git/commands/config_option_syntax/list.rb,
lib/git/commands/show_ref/exclude_existing.rb,
lib/git/commands/config_option_syntax/unset.rb,
lib/git/commands/config_option_syntax/get_all.rb,
lib/git/commands/config_option_syntax/get_color.rb,
lib/git/commands/config_option_syntax/unset_all.rb,
lib/git/commands/config_option_syntax/get_regexp.rb,
lib/git/commands/config_option_syntax/replace_all.rb,
lib/git/commands/config_option_syntax/get_urlmatch.rb,
lib/git/commands/config_option_syntax/get_color_bool.rb,
lib/git/commands/config_option_syntax/remove_section.rb,
lib/git/commands/config_option_syntax/rename_section.rb

Overview

The Git module provides a Ruby interface to Git version control.

Defined Under Namespace

Modules: CommandLine, Commands, Configuring, EncodingUtils, Parsers Classes: ArgsBuilder, Author, Branch, BranchDeleteFailure, BranchDeleteResult, BranchInfo, Branches, CommandLineError, Config, ConfigEntryInfo, DetachedHeadInfo, Diff, DiffFileNumstatInfo, DiffFilePatchInfo, DiffFileRawInfo, DiffInfo, DiffPathStatus, DiffResult, DiffStats, DirstatEntry, DirstatInfo, Error, EscapedPath, ExecutionContext, FailedError, FileDiffInfo, FileRef, FsckObject, FsckResult, GitAltURI, Log, Object, ProcessIOError, Remote, Repository, SignaledError, Stash, StashInfo, Stashes, Status, TagDeleteFailure, TagDeleteResult, TagInfo, TimeoutError, URL, UnexpectedResultError, Version, VersionConstraint, VersionError, Worktree, Worktrees

Constant Summary collapse

MINIMUM_GIT_VERSION =

Minimum git version required by this gem

Commands and features may require newer versions, but this is the absolute minimum supported version for the gem as a whole.

Returns:

Version.parse('2.28.0')
GitExecuteError =
Deprecated.

Use Git::Error instead

An alias for Git::Error

Git::GitExecuteError error class is an alias for Git::Error for backwards compatibility. It is recommended to use Git::Error directly.

ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Git::GitExecuteError', 'Git::Error', Git::Deprecation)
VERSION =

The current gem version

Returns:

  • (String) —

    the current gem version

'5.0.0.beta.3'
BRANCH_REFNAME_REGEXP =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Note:

This regex is similar to Git::Branch::BRANCH_NAME_REGEXP but uses \A/\z anchors instead of ^/$ for stricter matching. As part of the architectural redesign, Git::Branch will eventually be refactored to use BranchInfo internally, at which point this will become the single source of truth for branch name parsing.

Note:

This regex assumes remote names do not contain '/'. If a remote name contains '/', parsing will be incorrect. For example, 'remotes/team/upstream/main' would parse as remote_name='team' instead of 'team/upstream'. This is an inherent ambiguity in git refnames that can only be resolved with knowledge of configured remotes. See: https://github.com/ruby-git/ruby-git/issues/919

Regular expression for parsing branch refnames

Captures:

  • remote_name: the remote name (e.g., 'origin') for remote branches, nil for local
  • branch_name: the branch name without the remote prefix

Examples:

'main' => { remote_name: nil, branch_name: 'main' }
'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
'feature/foo' => { remote_name: nil, branch_name: 'feature/foo' }
'remotes/origin/feature/bar' => { remote_name: 'origin', branch_name: 'feature/bar' }
%r{
  \A                              # start of string
  (?:(?:refs/)?remotes/(?<remote_name>[^/]+)/)? # optional 'refs?/remotes/<remote_name>/'
  (?<branch_name>.+)                   # branch name (everything else)
  \z                              # end of string
}x
Deprecation =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

ActiveSupport::Deprecation.new('5.0.0', 'Git')
CommandLineResult =

Backward-compatible alias for Git::CommandLine::Result

Git::CommandLine::Result

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

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

Open a bare repository

Opens a bare repository located in the git_dir directory. Since there is no working copy, you can not checkout or commit but you can do most read operations.

Examples:

Open a bare repository and retrieve the first commit SHA

repository = Git.bare('ruby-git.git')
puts repository.log[0].sha #=> "64c6fa011d3287bab9158049c85f3e85718854a0"

Parameters:

  • git_dir (Pathname) —

    The path to the bare repository directory containing an initialized Git repository. If a relative path is given, it is converted to an absolute path using File.expand_path.

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

    The options for this command (see list of valid options below)

Options Hash (options):

  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (Git::Repository) —

    an object that can execute git commands in the context of the bare repository.

See Also:



162
163
164
 
# File 'lib/git.rb', line 162

def self.bare(git_dir, options = {})
  Git::Repository.bare(git_dir, options)
end

.binary_version(binary_path = nil) ⇒ Array<Integer>

Deprecated.

Use git_version instead, which returns a Version (not an Array)

For the legacy array shape, call: Git.git_version.to_a. The optional binary_path argument is preserved: Git.git_version(binary_path).

Return the version of the git binary

Examples:

Basic usage

Git.binary_version  # => [2, 46, 0]

Parameters:

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

    path to the git binary; defaults to Git::Config.instance.binary_path

Returns:

  • (Array<Integer>) —

    the version of the git binary



630
631
632
633
634
635
636
637
638
639
 
# File 'lib/git.rb', line 630

def self.binary_version(binary_path = nil)
  binary_path ||= Git::Config.instance.binary_path
  Git::Deprecation.warn(
    'Git.binary_version is deprecated and will be removed in 6.0. ' \
    'Use Git.git_version instead, which returns a Git::Version ' \
    '(not an Array). For the legacy array shape, call: Git.git_version.to_a. ' \
    'The optional binary_path argument is preserved: Git.git_version(binary_path).'
  )
  git_version(binary_path).to_a
end

.cached_git_version(binary_path, &block)

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. 



511
512
513
514
515
 
# File 'lib/git.rb', line 511

def self.cached_git_version(binary_path, &block)
  @git_version_cache_mutex.synchronize do
    @git_version_cache[binary_path] ||= block.call
  end
end

.clear_git_version_cache

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. 



518
519
520
521
522
 
# File 'lib/git.rb', line 518

def self.clear_git_version_cache
  @git_version_cache_mutex.synchronize do
    @git_version_cache.clear
  end
end

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

Clone a repository into an empty or newly created directory

Examples:

Clone into the default directory ruby-git

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

Clone and then checkout the development branch

git = Git.clone('https://github.com/ruby-git/ruby-git.git', branch: 'development')

Clone into a different directory my-ruby-git

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

Clone into a specific parent directory

git = Git.clone('https://github.com/ruby-git/ruby-git.git', chdir: '/path/to/projects')
# clones into /path/to/projects/ruby-git

Create a bare repository in the directory ruby-git.git

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

Clone a repository and set a single config option

git = Git.clone(
  'https://github.com/ruby-git/ruby-git.git',
  config: 'submodule.recurse=true'
)

Clone a repository and set multiple config options

git = Git.clone(
  'https://github.com/ruby-git/ruby-git.git',
  config: ['user.name=John Doe', 'user.email=john@doe.com']
)

Clone using a specific SSH key

git = Git.clone(
  'git@github.com:ruby-git/ruby-git.git',
  'local-dir',
  git_ssh: 'ssh -i /path/to/private_key'
)

Parameters:

  • repository_url (URI, Pathname) —

    The (possibly remote) repository url to clone from. See GIT URLS for more information.

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

    The directory to clone into

    If directory is a relative path it is relative to the :chdir option if given. If :chdir is not given, directory is relative to the current working directory.

    If nil, directory will be set to the basename of the last component of the path from the repository_url. For example, for the URL: https://github.com/org/repo.git, directory will be set to repo.

    If the last component of the path is .git, the next-to-last component of the path is used. For example, for the URL /Users/me/foo/.git, directory will be set to foo.

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

    The options for this command (see list of valid options below)

Options Hash (options):

  • :bare (Boolean) —

    Make a bare Git repository. See what is a bare repository?.

  • :branch (String) —

    The name of a branch or tag to checkout instead of the default branch.

  • :config (Array, String) —

    A list of configuration options to set on the newly created repository.

  • :depth (Integer) —

    Create a shallow clone with a history truncated to the specified number of commits.

  • :filter (String) —

    Request that the server send a partial clone according to the given filter

  • :single_branch (Boolean, nil) —

    Control whether the clone limits fetch refspecs to a single branch.

    • If nil (default), no flag is passed and the Git default is used.
    • If true, --single-branch is passed to limit the refspec to the checkout branch.
    • If false, --no-single-branch is passed to broaden the refspec (useful for shallow clones that should include all branches).
  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

  • :mirror (Boolean) —

    Set up a mirror of the source repository.

  • :origin (String) —

    Use the value instead origin to track the upstream repository.

  • :chdir (Pathname) —

    Run git clone from within this directory.

    The directory parameter (or the repository basename when directory is nil) is resolved relative to :chdir, just as if you had cd'd into it before running git clone. The returned path is the join of :chdir and the cloned directory path.

  • :path (Pathname) —

    Deprecated — use :chdir instead.

  • :recursive (Boolean) —

    After the clone is created, initialize all submodules within, using their default settings.

Returns:

  • (Git::Repository) —

    an object that can execute git commands in the context of the cloned local working copy or cloned repository.

See Also:



280
281
282
 
# File 'lib/git.rb', line 280

def self.clone(repository_url, directory = nil, options = {})
  Git::Repository.clone(repository_url, directory, options)
end

.config ⇒ Git::Config

Returns the process-wide Config singleton

Examples:

Read the configured binary path

Git.config.binary_path  #=> "git"

Returns:



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

def self.config
  Git::Config.instance
end

.configure {|config| ... }

This method returns an undefined value.

Configures the gem by yielding Git::Config.instance to the block

Examples:

Set the global git binary path

Git.configure { |c| c.binary_path = '/usr/local/bin/git' }

Yields:

  • (config) —

    yields the singleton config object

Yield Parameters:

Yield Returns:

  • (void) 


100
101
102
103
 
# File 'lib/git.rb', line 100

def self.configure
  yield Git::Config.instance
  nil
end

.default_branch(repository, options = {}) ⇒ String

Returns the name of the default branch of the given repository

Examples:

with a URI string

Git.default_branch('https://github.com/ruby-git/ruby-git') # => 'master'
Git.default_branch('https://github.com/rspec/rspec-core') # => 'main'

with a URI object

repository_uri = URI('https://github.com/ruby-git/ruby-git')
Git.default_branch(repository_uri) # => 'master'

with a local repository

Git.default_branch('.') # => 'master'

with a local repository Pathname

repository_path = Pathname('.')
Git.default_branch(repository_path) # => 'master'

with the logging option

logger = Logger.new(STDOUT, level: Logger::INFO)
Git.default_branch('.', log: logger) # => 'master'
I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true'
  '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1

Parameters:

  • repository (URI, Pathname, String) —

    The (possibly remote) repository to get the default branch name for

    See GIT URLS for more information.

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

    The options for this command (see list of valid options below)

Options Hash (options):

  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (String) —

    the name of the default branch



321
322
323
324
325
 
# File 'lib/git.rb', line 321

def self.default_branch(repository, options = {})
  context = Git::ExecutionContext::Global.new(logger: options[:log])
  output = Git::Commands::LsRemote.new(context).call(repository, 'HEAD', symref: true).stdout
  Git::Parsers::LsRemote.parse_default_branch(output)
end

.export(repository, name, options = {})

Export the current HEAD (or a branch, if options[:branch] is specified) into the +name+ directory, then remove all traces of git from the directory.

See +clone+ for options. Does not obey the :remote option, since the .git info will be deleted anyway; always uses the default remote, 'origin.'



334
335
336
337
338
339
 
# File 'lib/git.rb', line 334

def self.export(repository, name, options = {})
  options.delete(:remote)
  repo = clone(repository, name, { depth: 1 }.merge(options))
  repo.checkout("origin/#{options[:branch]}") if options[:branch]
  FileUtils.rm_r File.join(repo.dir.to_s, '.git')
end

.git_version(binary_path = nil) ⇒ Git::Version

Return the version of a git binary as a Version

Examples:

Default binary

Git.git_version #=> #<Git::Version 2.42.0>

Explicit binary path

Git.git_version('/opt/homebrew/bin/git') #=> #<Git::Version 2.42.0>

Parameters:

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

    path to the git binary; defaults to Git::Config.instance.binary_path

Returns:

Raises:



543
544
545
546
 
# File 'lib/git.rb', line 543

def self.git_version(binary_path = nil)
  path = binary_path || Git::Config.instance.binary_path
  cached_git_version(path) { run_git_version(path) }
end

.global_config(name = nil, value = nil)

Same as g.config, but forces it to be at the global level

g.config('user.name', 'Scott Chacon') # sets value g.config('user.email', 'email@email.com') # sets value g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash



347
348
349
 
# File 'lib/git.rb', line 347

def self.global_config(name = nil, value = nil)
  run_config_utility(name, value, global: true)
end

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

Create an empty Git repository or reinitialize an existing Git repository

Examples:

Initialize a repository in the current directory

git = Git.init

Initialize a repository in some other directory

git = Git.init '~/code/ruby-git'

Initialize a bare repository

git = Git.init '~/code/ruby-git.git', bare: true

Initialize a repository in a non-default location (outside of the working copy)

git = Git.init '~/code/ruby-git', repository: '~/code/ruby-git.git'

Parameters:

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

    If the :bare option is NOT given or is not true, the repository will be created in "#{directory}/.git". Otherwise, the repository is created in "#{directory}".

    All directories along the path to directory are created if they do not exist.

    A relative path is referenced from the current working directory of the process and converted to an absolute path using File.expand_path.

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

    The options for this command (see list of valid options below)

Options Hash (options):

  • :bare (Boolean) —

    Instead of creating a repository at "#{directory}/.git", create a bare repository at "#{directory}". See what is a bare repository?.

  • :initial_branch (String) —

    Use the specified name for the initial branch in the newly created repository.

  • :repository (Pathname) —

    the path to put the newly initialized Git repository. The default for non-bare repository is "#{directory}/.git".

    A relative path is referenced from the current working directory of the process and converted to an absolute path using File.expand_path.

  • :separate_git_dir (Pathname) —

    Alias for :repository.

  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :binary_path (String, :use_global_config) —

    path to the git binary; defaults to Git::Config.instance.binary_path when not specified. Raises ArgumentError if set to nil.

  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (Git::Repository) —

    an object that can execute git commands in the context of the newly initialized repository

See Also:



413
414
415
 
# File 'lib/git.rb', line 413

def self.init(directory = '.', options = {})
  Git::Repository.init(directory, options)
end

.ls_remote(location = nil, options = {}) ⇒ {String=>Hash}

returns a Hash containing information about the references of the target repository

options :refs

Parameters:

  • location (String|NilClass) (defaults to: nil) —

    the target repository location or nil for '.'

Returns:

  • ({String=>Hash}) —

    the available references of the target repo.

Raises:

  • (ArgumentError) 


440
441
442
443
444
445
446
447
448
449
450
 
# File 'lib/git.rb', line 440

def self.ls_remote(location = nil, options = {})
  options = options.dup
  log = options.delete(:log)
  unknown = options.keys - LS_REMOTE_ALLOWED_OPTS
  raise ArgumentError, "Unknown options: #{unknown.join(', ')}" unless unknown.empty?

  context = Git::ExecutionContext::Global.new(logger: log)
  repository = location || '.'
  output_lines = Git::Commands::LsRemote.new(context).call(repository, **options).stdout.split("\n")
  Git::Parsers::LsRemote.parse_output(output_lines)
end

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

Open a an existing Git working directory

Git.open will most likely be the most common way to create a git reference, referring to an existing working directory.

If not provided in the options, the library will assume the repository and index are in the default places (.git/, .git/index).

Examples:

Open the Git working directory in the current directory

git = Git.open

Open a Git working directory in some other directory

git = Git.open('~/Projects/ruby-git')

Use a logger to see what is going on

logger = Logger.new(STDOUT)
git = Git.open('~/Projects/ruby-git', log: logger)

Open a working copy whose repository is in a non-standard directory

git = Git.open('~/Projects/ruby-git', repository: '~/Project/ruby-git.git')

Parameters:

  • working_dir (Pathname) —

    the path to the working directory to use for git commands.

    A relative path is referenced from the current working directory of the process and converted to an absolute path using File.expand_path.

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

    The options for this command (see list of valid options below)

Options Hash (options):

  • :repository (Pathname) —

    used to specify a non-standard path to the repository directory. The default is "#{working_dir}/.git".

  • :index (Pathname) —

    used to specify a non-standard path to an index file. The default is "#{working_dir}/.git/index"

  • :git_ssh (String, nil) —

    An optional custom SSH command

    • If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
    • If nil, disables SSH for this instance.
    • If a non-empty string, uses that value for this instance.
  • :log (Logger) —

    A logger to use for Git operations. Git commands are logged at the :info level. Additional logging is done at the :debug level.

Returns:

  • (Git::Repository) —

    an object that can execute git commands in the context of the opened working copy



502
503
504
 
# File 'lib/git.rb', line 502

def self.open(working_dir, options = {})
  Git::Repository.open(working_dir, options)
end

Instance Method Details

#config(name = nil, value = nil)

Deprecated.

Mixing in the Git module is deprecated and will be removed in v6.0.0. Use Git.config_get(name), Git.config_set(name, value), or Git.config_list instead.



79
80
81
82
83
84
85
 
# File 'lib/git.rb', line 79

def config(name = nil, value = nil)
  Git::Deprecation.warn(
    'Git#config is deprecated and will be removed in v6.0.0. ' \
    'Use Git.config_get(name), Git.config_set(name, value), or Git.config_list instead.'
  )
  Git.__send__(:run_config_utility, name, value, global: false)
end

#global_config(name = nil, value = nil)

Deprecated.

Mixing in the Git module is deprecated and will be removed in v6.0.0. Use Git.config_get(name, global: true), Git.config_set(name, value, global: true), or Git.config_list(global: true) instead.



119
120
121
122
123
124
125
126
 
# File 'lib/git.rb', line 119

def global_config(name = nil, value = nil)
  Git::Deprecation.warn(
    'Git#global_config is deprecated and will be removed in v6.0.0. ' \
    'Use Git.config_get(name, global: true), Git.config_set(name, value, global: true), ' \
    'or Git.config_list(global: true) instead.'
  )
  Git.global_config(name, value)
end