Module: Git

Defined in:
lib/git.rb,
lib/git.rb,
lib/git/lib.rb,
lib/git/log.rb,
lib/git/url.rb,
lib/git/base.rb,
lib/git/diff.rb,
lib/git/path.rb,
lib/git/index.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/worktree.rb,
lib/git/worktrees.rb,
lib/git/diff_stats.rb,
lib/git/repository.rb,
lib/git/args_builder.rb,
lib/git/command_line.rb,
lib/git/escaped_path.rb,
lib/git/encoding_utils.rb,
lib/git/diff_path_status.rb,
lib/git/working_directory.rb,
lib/git/command_line_result.rb

Overview

These would be required by the main git.rb file

Defined Under Namespace

Modules: EncodingUtils Classes: ArgsBuilder, Author, Base, Branch, Branches, CommandLine, CommandLineError, CommandLineResult, Config, Diff, DiffPathStatus, DiffStats, Error, EscapedPath, FailedError, GitAltURI, Index, Lib, Log, Object, Path, ProcessIOError, Remote, Repository, SignaledError, Stash, Stashes, Status, TimeoutError, URL, UnexpectedResultError, WorkingDirectory, Worktree, Worktrees

Constant Summary collapse

Deprecation = 
ActiveSupport::Deprecation.new('5.0.0', 'Git')
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

'4.0.6'

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

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

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"

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.

See Also:



103
104
105
 
# File 'lib/git.rb', line 103

def self.bare(git_dir, options = {})
  Base.bare(git_dir, options)
end

.binary_version(binary_path = Git::Base.config.binary_path) ⇒ Array<Integer>

Return the version of the git binary

Examples:

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



395
396
397
 
# File 'lib/git.rb', line 395

def self.binary_version(binary_path = Git::Base.config.binary_path)
  Base.binary_version(binary_path)
end

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

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')
# or:
git = Git.clone('https://github.com/ruby-git/ruby-git.git', path: 'my-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', '[email protected]']
)

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

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

  • :path (Pathname) —

    The directory to clone into. May be used as an alternative to the directory parameter. If specified, the path option is used instead of the directory parameter.

  • :recursive (Boolean) —

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

See Also:



193
194
195
196
197
 
# File 'lib/git.rb', line 193

def self.clone(repository_url, directory = nil, options = {})
  clone_to_options = options.slice(:bare, :mirror)
  directory ||= Git::URL.clone_to(repository_url, **clone_to_options)
  Base.clone(repository_url, directory, options)
end

.config 



67
68
69
 
# File 'lib/git.rb', line 67

def self.config
  Base.config
end

.configure {|Base.config| ... }

Yields:



63
64
65
 
# File 'lib/git.rb', line 63

def self.configure
  yield Base.config
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

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.



236
237
238
 
# File 'lib/git.rb', line 236

def self.default_branch(repository, options = {})
  Base.repository_default_branch(repository, options)
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.'



247
248
249
250
251
252
 
# File 'lib/git.rb', line 247

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

.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 protected]') # sets value g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash



260
261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/git.rb', line 260

def self.global_config(name = nil, value = nil)
  lib = Git::Lib.new(nil, nil)
  if name && value
    # set value
    lib.global_config_set(name, value)
  elsif name
    # return value
    lib.global_config_get(name)
  else
    # return hash
    lib.global_config_list
  end
end

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

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'

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.

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

See Also:



324
325
326
 
# File 'lib/git.rb', line 324

def self.init(directory = '.', options = {})
  Base.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



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

def self.ls_remote(location = nil, options = {})
  Git::Lib.new.ls_remote(location, options)
end

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

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')

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"

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



384
385
386
 
# File 'lib/git.rb', line 384

def self.open(working_dir, options = {})
  Base.open(working_dir, options)
end

Instance Method Details

#config(name = nil, value = nil)

g.config('user.name', 'Scott Chacon') # sets value g.config('user.email', '[email protected]') # sets value g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash



49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/git.rb', line 49

def config(name = nil, value = nil)
  lib = Git::Lib.new
  if name && value
    # set value
    lib.config_set(name, value)
  elsif name
    # return value
    lib.config_get(name)
  else
    # return hash
    lib.config_list
  end
end

#global_config(name = nil, value = nil) 



71
72
73
 
# File 'lib/git.rb', line 71

def global_config(name = nil, value = nil)
  self.class.global_config(name, value)
end