Class: Git::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/git/base.rb

Overview

The main public interface for interacting with Git commands

Instead of creating a Git::Base directly, obtain a Git::Base instance by calling one of the follow Git class methods: open, init, clone, or bare.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Git::Base

Create an object that executes Git commands in the context of a working copy or a bare repository.

Parameters:

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

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

Options Hash (options):

  • :working_dir (Pathname) —

    the path to the root of the working directory. Should be nil if executing commands on a bare repository.

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



111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/git/base.rb', line 111

def initialize(options = {})
  if working_dir = options[:working_directory]
    options[:repository] ||= File.join(working_dir, '.git')
    options[:index] ||= File.join(options[:repository], 'index')
  end
  @logger = (options[:log] || Logger.new(nil))
  @logger.info("Starting Git")

  @working_directory = options[:working_directory] ? Git::WorkingDirectory.new(options[:working_directory]) : nil
  @repository = options[:repository] ? Git::Repository.new(options[:repository]) : nil
  @index = options[:index] ? Git::Index.new(options[:index], false) : nil
end

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"

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

  • :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::Base) —

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

See Also:



15
16
17
18
 
# File 'lib/git/base.rb', line 15

def self.bare(git_dir, options = {})
  normalize_paths(options, default_repository: git_dir, bare: true)
  self.new(options)
end

.clone(repository_url, directory, 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]']
)

Parameters:

  • repository_url (URI, Pathname) —

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

  • directory (Pathname, nil) —

    The directory to clone into

    If directory is a relative directory it is relative to the path option if given. If path 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

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

Returns:

  • (Git::Base) —

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

See Also:



21
22
23
24
25
 
# File 'lib/git/base.rb', line 21

def self.clone(repository_url, directory, options = {})
  new_options = Git::Lib.new(nil, options[:log]).clone(repository_url, directory, options)
  normalize_paths(new_options, bare: options[:bare] || options[:mirror])
  new(new_options)
end

.config ⇒ Git::Config

Returns (and initialize if needed) a Git::Config instance

Returns:



35
36
37
 
# File 'lib/git/base.rb', line 35

def self.config
  @@config ||= Config.new
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'

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.

  • :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::Base) —

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

See Also:



40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/git/base.rb', line 40

def self.init(directory = '.', options = {})
  normalize_paths(options, default_working_directory: directory, default_repository: directory, bare: options[:bare])

  init_options = {
    :bare => options[:bare],
    :initial_branch => options[:initial_branch]
  }

  directory = options[:bare] ? options[:repository] : options[:working_directory]
  FileUtils.mkdir_p(directory) unless File.exist?(directory)

  # TODO: this dance seems awkward: this creates a Git::Lib so we can call
  #   init so we can create a new Git::Base which in turn (ultimately)
  #   creates another/different Git::Lib.
  #
  # TODO: maybe refactor so this Git::Bare.init does this:
  #   self.new(opts).init(init_opts) and move all/some of this code into
  #   Git::Bare#init. This way the init method can be called on any
  #   repository you have a Git::Base instance for.  This would not
  #   change the existing interface (other than adding to it).
  #
  Git::Lib.new(options).init(init_options)

  self.new(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')

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"

  • :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::Base) —

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

Raises:

  • (ArgumentError) 


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

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

  working_dir = root_of_worktree(working_dir) unless options[:repository]

  normalize_paths(options, default_working_directory: working_dir)

  self.new(options)
end

.repository_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



28
29
30
 
# File 'lib/git/base.rb', line 28

def self.repository_default_branch(repository, options = {})
  Git::Lib.new(nil, options[:log]).repository_default_branch(repository)
end

.root_of_worktree(working_dir)

Raises:

  • (ArgumentError) 


66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/git/base.rb', line 66

def self.root_of_worktree(working_dir)
  result = working_dir
  status = nil

  git_cmd = "#{Git::Base.config.binary_path} -c core.quotePath=true -c color.ui=false rev-parse --show-toplevel 2>&1"
  result, status = Open3.capture2(git_cmd, chdir: File.expand_path(working_dir))
  result = result.chomp

  raise ArgumentError, "'#{working_dir}' is not in a git working tree" unless status.success?
  result
end

Instance Method Details

#add(paths = '.', **options)

Update the index from the current worktree to prepare the for the next commit

Examples:

lib.add('path/to/file')
lib.add(['path/to/file1','path/to/file2'])
lib.add(all: true)

Parameters:

  • paths (String, Array<String>) (defaults to: '.') —

    a file or files to be added to the repository (relative to the worktree root)

  • options (Hash)

Options Hash (**options):

  • :all (Boolean) —

    Add, modify, and remove index entries to match the worktree

  • :force (Boolean) —

    Allow adding otherwise ignored files



137
138
139
 
# File 'lib/git/base.rb', line 137

def add(paths = '.', **options)
  self.lib.add(paths, options)
end

#add_remote(name, url, opts = {})

adds a new remote to this repository url can be a git url or a Git::Base object if it's a local reference

@git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git') @git.fetch('scotts_git') @git.merge('scotts_git/master')

Options: :fetch => true :track => 



151
152
153
154
155
 
# File 'lib/git/base.rb', line 151

def add_remote(name, url, opts = {})
  url = url.repo.path if url.is_a?(Git::Base)
  self.lib.remote_add(name, url, opts)
  Git::Remote.new(self, name)
end

#add_tag(name, *options)

Create a new git tag

Examples:

repo.add_tag('tag_name', object_reference)
repo.add_tag('tag_name', object_reference, {:options => 'here'})
repo.add_tag('tag_name', {:options => 'here'})

Parameters:

  • name (String) —

    The name of the tag to add

  • options (Hash) —

    Opstions to pass to git tag. See git-tag for more details.

Options Hash (*options):

  • :annotate (boolean) —

    Make an unsigned, annotated tag object

  • :a (boolean) —

    An alias for the :annotate option

  • :d (boolean) —

    Delete existing tag with the given names.

  • :f (boolean) —

    Replace an existing tag with the given name (instead of failing)

  • :message (String) —

    Use the given tag message

  • :m (String) —

    An alias for the :message option

  • :s (boolean) —

    Make a GPG-signed tag.



175
176
177
178
 
# File 'lib/git/base.rb', line 175

def add_tag(name, *options)
  self.lib.tag(name, *options)
  self.tag(name)
end

#apply(file) 



544
545
546
547
548
 
# File 'lib/git/base.rb', line 544

def apply(file)
  if File.exist?(file)
    self.lib.apply(file)
  end
end

#apply_mail(file) 



550
551
552
 
# File 'lib/git/base.rb', line 550

def apply_mail(file)
  self.lib.apply_mail(file) if File.exist?(file)
end

#archive(treeish, file = nil, opts = {})

creates an archive file of the given tree-ish



531
532
533
 
# File 'lib/git/base.rb', line 531

def archive(treeish, file = nil, opts = {})
  self.object(treeish).archive(file, opts)
end

#branch(branch_name = self.current_branch) ⇒ Git::Branch

Returns an object for branch_name.

Returns:



659
660
661
 
# File 'lib/git/base.rb', line 659

def branch(branch_name = self.current_branch)
  Git::Branch.new(self, branch_name)
end

#branches ⇒ Git::Branches

Returns a collection of all the branches in the repository. Each branch is represented as a Git::Branch.

Returns:



665
666
667
 
# File 'lib/git/base.rb', line 665

def branches
  Git::Branches.new(self)
end

#cat_file(objectish) 



649
650
651
 
# File 'lib/git/base.rb', line 649

def cat_file(objectish)
  self.lib.object_contents(objectish)
end

#chdir

changes current working directory for a block to the git working directory

example @git.chdir do # write files @git.add @git.commit('message') end



189
190
191
192
193
 
# File 'lib/git/base.rb', line 189

def chdir # :yields: the Git::Path
  Dir.chdir(dir.path) do
    yield dir.path
  end
end

#checkout(*args, **options)

checks out a branch as the new git working directory



398
399
400
 
# File 'lib/git/base.rb', line 398

def checkout(*args, **options)
  self.lib.checkout(*args, **options)
end

#checkout_file(version, file)

checks out an old version of a file



403
404
405
 
# File 'lib/git/base.rb', line 403

def checkout_file(version, file)
  self.lib.checkout_file(version,file)
end

#checkout_index(opts = {}) 



588
589
590
 
# File 'lib/git/base.rb', line 588

def checkout_index(opts = {})
  self.lib.checkout_index(opts)
end

#clean(opts = {})

cleans the working directory

options: :force :d :ff



344
345
346
 
# File 'lib/git/base.rb', line 344

def clean(opts = {})
  self.lib.clean(opts)
end

#commit(message, opts = {})

commits all pending changes in the index file to the git repository

options: :all :allow_empty :amend :author



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

def commit(message, opts = {})
  self.lib.commit(message, opts)
end

#commit_all(message, opts = {})

commits all pending changes in the index file to the git repository, but automatically adds all modified files without having to explicitly calling @git.add() on them.



392
393
394
395
 
# File 'lib/git/base.rb', line 392

def commit_all(message, opts = {})
  opts = {:add_all => true}.merge(opts)
  self.lib.commit(message, opts)
end

#commit_tree(tree = nil, opts = {}) ⇒ Git::Object::Commit

Returns a commit object.

Returns:



681
682
683
 
# File 'lib/git/base.rb', line 681

def commit_tree(tree = nil, opts = {})
  Git::Object::Commit.new(self, self.lib.commit_tree(tree, opts))
end

#config(name = nil, value = nil, options = {})

g.config('user.name', 'Scott Chacon') # sets value g.config('user.email', '[email protected]') # sets value g.config('user.email', '[email protected]', file: 'path/to/custom/config) # sets value in file g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash



200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/git/base.rb', line 200

def config(name = nil, value = nil, options = {})
  if name && value
    # set value
    lib.config_set(name, value, options)
  elsif name
    # return value
    lib.config_get(name)
  else
    # return hash
    lib.config_list
  end
end

#current_branch

returns the name of the branch the working directory is currently on



654
655
656
 
# File 'lib/git/base.rb', line 654

def current_branch
  self.lib.branch_current
end

#delete_tag(name)

deletes a tag



526
527
528
 
# File 'lib/git/base.rb', line 526

def delete_tag(name)
  self.lib.tag(name, {:d => true})
end

#describe(committish = nil, opts = {})

returns the most recent tag that is reachable from a commit

options: :all :tags :contains :debug :exact_match :dirty :abbrev :candidates :long :always :match



363
364
365
 
# File 'lib/git/base.rb', line 363

def describe(committish=nil, opts={})
  self.lib.describe(committish, opts)
end

#diff(objectish = 'HEAD', obj2 = nil) ⇒ Git::Diff

Returns a Git::Diff object.

Returns:



686
687
688
 
# File 'lib/git/base.rb', line 686

def diff(objectish = 'HEAD', obj2 = nil)
  Git::Diff.new(self, objectish, obj2)
end

#dir

returns a reference to the working directory @git.dir.path @git.dir.writeable?



216
217
218
 
# File 'lib/git/base.rb', line 216

def dir
  @working_directory
end

#each_conflict(&block)

iterates over the files which are unmerged



447
448
449
 
# File 'lib/git/base.rb', line 447

def each_conflict(&block) # :yields: file, your_version, their_version
  self.lib.conflicts(&block)
end

#fetch(remote = 'origin', opts = {})

fetches changes from a remote branch - this does not modify the working directory, it just gets the changes from the remote if there are any



409
410
411
412
413
414
415
 
# File 'lib/git/base.rb', line 409

def fetch(remote = 'origin', opts = {})
  if remote.is_a?(Hash)
    opts = remote
    remote = nil
  end
  self.lib.fetch(remote, opts)
end

#gblob(objectish) ⇒ Git::Object

Returns a Git object.

Returns:



691
692
693
 
# File 'lib/git/base.rb', line 691

def gblob(objectish)
  Git::Object.new(self, objectish, 'blob')
end

#gc 



540
541
542
 
# File 'lib/git/base.rb', line 540

def gc
  self.lib.gc
end

#gcommit(objectish) ⇒ Git::Object

Returns a Git object.

Returns:



696
697
698
 
# File 'lib/git/base.rb', line 696

def gcommit(objectish)
  Git::Object.new(self, objectish, 'commit')
end

#grep(string, path_limiter = nil, opts = {}) ⇒ Hash<String, Array>

Run a grep for 'string' on the HEAD of the git repository

Examples:

Limit grep's scope by calling grep() from a specific object:

git.object("v2.3").grep('TODO')

Using grep results:

git.grep("TODO").each do |sha, arr|
  puts "in blob #{sha}:"
  arr.each do |line_no, match_string|
    puts "\t line #{line_no}: '#{match_string}'"
  end
end

Parameters:

  • string (String) —

    the string to search for

  • path_limiter (String, Array) (defaults to: nil) —

    a path or array of paths to limit the search to or nil for no limit

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

    options to pass to the underlying git grep command

Options Hash (opts):

  • :ignore_case (Boolean) — default: false —

    ignore case when matching

  • :invert_match (Boolean) — default: false —

    select non-matching lines

  • :extended_regexp (Boolean) — default: false —

    use extended regular expressions

  • :object (String) — default: HEAD —

    the object to search from

Returns:

  • (Hash<String, Array>) —

    a hash of arrays

    {
   'tree-ish1' => [[line_no1, match_string1], ...],
   'tree-ish2' => [[line_no1, match_string1], ...],
   ...
}



308
309
310
 
# File 'lib/git/base.rb', line 308

def grep(string, path_limiter = nil, opts = {})
  self.object('HEAD').grep(string, path_limiter, opts)
end

#gtree(objectish) ⇒ Git::Object

Returns a Git object.

Returns:



701
702
703
 
# File 'lib/git/base.rb', line 701

def gtree(objectish)
  Git::Object.new(self, objectish, 'tree')
end

#ignored_files ⇒ Array<String>

List the files in the worktree that are ignored by git

Returns:

  • (Array<String>) —

    the list of ignored files relative to teh root of the worktree



315
316
317
 
# File 'lib/git/base.rb', line 315

def ignored_files
  self.lib.ignored_files
end

#index

returns reference to the git index file



221
222
223
 
# File 'lib/git/base.rb', line 221

def index
  @index
end

#is_branch?(branch) ⇒ Boolean

returns +true+ if the branch exists

Returns:

  • (Boolean) 


265
266
267
268
 
# File 'lib/git/base.rb', line 265

def is_branch?(branch)
  branch_names = self.branches.map {|b| b.name}
  branch_names.include?(branch)
end

#is_local_branch?(branch) ⇒ Boolean

returns +true+ if the branch exists locally

Returns:

  • (Boolean) 


253
254
255
256
 
# File 'lib/git/base.rb', line 253

def is_local_branch?(branch)
  branch_names = self.branches.local.map {|b| b.name}
  branch_names.include?(branch)
end

#is_remote_branch?(branch) ⇒ Boolean

returns +true+ if the branch exists remotely

Returns:

  • (Boolean) 


259
260
261
262
 
# File 'lib/git/base.rb', line 259

def is_remote_branch?(branch)
  branch_names = self.branches.remote.map {|b| b.name}
  branch_names.include?(branch)
end

#lib

this is a convenience method for accessing the class that wraps all the actual 'git' forked system calls. At some point I hope to replace the Git::Lib class with one that uses native methods or libgit C bindings



273
274
275
 
# File 'lib/git/base.rb', line 273

def lib
  @lib ||= Git::Lib.new(self, @logger)
end

#log(count = 30) ⇒ Git::Log

Returns a log with the specified number of commits.

Returns:

  • (Git::Log) —

    a log with the specified number of commits



706
707
708
 
# File 'lib/git/base.rb', line 706

def log(count = 30)
  Git::Log.new(self, count)
end

#ls_files(location = nil) 



610
611
612
 
# File 'lib/git/base.rb', line 610

def ls_files(location=nil)
  self.lib.ls_files(location)
end

#ls_tree(objectish) 



645
646
647
 
# File 'lib/git/base.rb', line 645

def ls_tree(objectish)
  self.lib.ls_tree(objectish)
end

#merge(branch, message = 'merge', opts = {})

merges one or more branches into the current working branch

you can specify more than one branch to merge by passing an array of branches



442
443
444
 
# File 'lib/git/base.rb', line 442

def merge(branch, message = 'merge', opts = {})
  self.lib.merge(branch, message, opts)
end

#merge_base(*args) ⇒ Array<Git::Object::Commit>

Find as good common ancestors as possible for a merge example: g.merge_base('master', 'some_branch', 'some_sha', octopus: true)

Returns:



743
744
745
746
 
# File 'lib/git/base.rb', line 743

def merge_base(*args)
  shas = self.lib.merge_base(*args)
  shas.map { |sha| gcommit(sha) }
end

#object(objectish) ⇒ Git::Object

returns a Git::Object of the appropriate type you can also call @git.gtree('tree'), but that's just for readability. If you call @git.gtree('HEAD') it will still return a Git::Object::Commit object.

object calls a method that will run a rev-parse on the objectish and determine the type of the object and return an appropriate object for that type

Returns:

  • (Git::Object) —

    an instance of the appropriate type of Git::Object



720
721
722
 
# File 'lib/git/base.rb', line 720

def object(objectish)
  Git::Object.new(self, objectish)
end

#pull(remote = nil, branch = nil, opts = {}) ⇒ Void

Pulls the given branch from the given remote into the current branch

Examples:

pulls from origin/master

@git.pull

pulls from upstream/master

@git.pull('upstream')

pulls from upstream/develop

@git.pull('upstream', 'develop')

Parameters:

  • remote (String) (defaults to: nil) —

    the remote repository to pull from

  • branch (String) (defaults to: nil) —

    the branch to pull from

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

    options to pass to the pull command

Options Hash (opts):

  • :allow_unrelated_histories (Boolean) — default: false —

    Merges histories of two projects that started their lives independently

Returns:

  • (Void)

Raises:

  • (Git::FailedError) —

    if the pull fails

  • (ArgumentError) —

    if a branch is given without a remote



470
471
472
 
# File 'lib/git/base.rb', line 470

def pull(remote = nil, branch = nil, opts = {})
  self.lib.pull(remote, branch, opts)
end

#push(remote = nil, branch = nil, options = {}) ⇒ Void

Push changes to a remote repository

Parameters:

  • remote (String) (defaults to: nil) —

    the remote repository to push to

  • branch (String) (defaults to: nil) —

    the branch to push

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

    options to pass to the push command

Returns:

  • (Void)

Raises:

  • (Git::FailedError) —

    if the push fails

  • (ArgumentError) —

    if a branch is given without a remote



435
436
437
 
# File 'lib/git/base.rb', line 435

def push(*args, **options)
  self.lib.push(*args, **options)
end

#read_tree(treeish, opts = {}) 



592
593
594
 
# File 'lib/git/base.rb', line 592

def read_tree(treeish, opts = {})
  self.lib.read_tree(treeish, opts)
end

#remote(remote_name = 'origin') ⇒ Git::Remote

Returns a remote of the specified name.

Returns:



725
726
727
 
# File 'lib/git/base.rb', line 725

def remote(remote_name = 'origin')
  Git::Remote.new(self, remote_name)
end

#remotes

returns an array of Git:Remote objects



475
476
477
 
# File 'lib/git/base.rb', line 475

def remotes
  self.lib.remotes.map { |r| Git::Remote.new(self, r) }
end

#remove_remote(name)

removes a remote from this repository

@git.remove_remote('scott_git')



493
494
495
 
# File 'lib/git/base.rb', line 493

def remove_remote(name)
  self.lib.remote_remove(name)
end

#repack

repacks the repository



536
537
538
 
# File 'lib/git/base.rb', line 536

def repack
  self.lib.repack
end

#repo

returns reference to the git repository directory @git.dir.path



227
228
229
 
# File 'lib/git/base.rb', line 227

def repo
  @repository
end

#repo_size

returns the repository size in bytes



232
233
234
235
236
237
238
239
240
 
# File 'lib/git/base.rb', line 232

def repo_size
  Dir.glob(File.join(repo.path, '**', '*'), File::FNM_DOTMATCH).reject do |f|
    f.include?('..')
  end.map do |f|
    File.expand_path(f)
  end.uniq.map do |f|
    File.stat(f).size.to_i
  end.reduce(:+)
end

#reset(commitish = nil, opts = {})

resets the working directory to the provided commitish



327
328
329
 
# File 'lib/git/base.rb', line 327

def reset(commitish = nil, opts = {})
  self.lib.reset(commitish, opts)
end

#reset_hard(commitish = nil, opts = {})

resets the working directory to the commitish with '--hard'



332
333
334
335
 
# File 'lib/git/base.rb', line 332

def reset_hard(commitish = nil, opts = {})
  opts = {:hard => true}.merge(opts)
  self.lib.reset(commitish, opts)
end

#revert(commitish = nil, opts = {})

reverts the working directory to the provided commitish. Accepts a range, such as comittish..HEAD

options: :no_edit



373
374
375
 
# File 'lib/git/base.rb', line 373

def revert(commitish = nil, opts = {})
  self.lib.revert(commitish, opts)
end

#revparse(objectish)

runs git rev-parse to convert the objectish to a full sha

Examples:

git.revparse("HEAD^^")
git.revparse('v2.4^{tree}')
git.revparse('v2.4:/doc/index.html')


641
642
643
 
# File 'lib/git/base.rb', line 641

def revparse(objectish)
  self.lib.revparse(objectish)
end

#rm(path = '.', opts = {}) Also known as: remove

removes file(s) from the git repository



320
321
322
 
# File 'lib/git/base.rb', line 320

def rm(path = '.', opts = {})
  self.lib.rm(path, opts)
end

#set_index(index_file, check = true) 



242
243
244
245
 
# File 'lib/git/base.rb', line 242

def set_index(index_file, check = true)
  @lib = nil
  @index = Git::Index.new(index_file.to_s, check)
end

#set_remote_url(name, url)

sets the url for a remote url can be a git url or a Git::Base object if it's a local reference

@git.set_remote_url('scotts_git', 'git://repo.or.cz/rubygit.git')



484
485
486
487
488
 
# File 'lib/git/base.rb', line 484

def set_remote_url(name, url)
  url = url.repo.path if url.is_a?(Git::Base)
  self.lib.remote_set_url(name, url)
  Git::Remote.new(self, name)
end

#set_working(work_dir, check = true) 



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

def set_working(work_dir, check = true)
  @lib = nil
  @working_directory = Git::WorkingDirectory.new(work_dir.to_s, check)
end

#show(objectish = nil, path = nil) ⇒ String

Shows objects

Parameters:

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

    the target object reference (nil == HEAD)

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

    the path of the file to be shown

Returns:

  • (String) —

    the object information



559
560
561
 
# File 'lib/git/base.rb', line 559

def show(objectish=nil, path=nil)
  self.lib.show(objectish, path)
end

#status ⇒ Git::Status

Returns a status object.

Returns:



730
731
732
 
# File 'lib/git/base.rb', line 730

def status
  Git::Status.new(self)
end

#tag(tag_name) ⇒ Git::Object::Tag

Returns a tag object.

Returns:



735
736
737
 
# File 'lib/git/base.rb', line 735

def tag(tag_name)
  Git::Object.new(self, tag_name, 'tag', true)
end

#tags

returns an array of all Git::Tag objects for this repository



498
499
500
 
# File 'lib/git/base.rb', line 498

def tags
  self.lib.tags.map { |r| tag(r) }
end

#update_ref(branch, commit) 



605
606
607
 
# File 'lib/git/base.rb', line 605

def update_ref(branch, commit)
  branch(branch).update_ref(commit)
end

#with_index(new_index)

LOWER LEVEL INDEX OPERATIONS ##



565
566
567
568
569
570
571
 
# File 'lib/git/base.rb', line 565

def with_index(new_index) # :yields: new_index
  old_index = @index
  set_index(new_index, false)
  return_value = yield @index
  set_index(old_index)
  return_value
end

#with_temp_index(&blk) 



573
574
575
576
577
578
579
580
581
582
583
584
585
586
 
# File 'lib/git/base.rb', line 573

def with_temp_index &blk
  # Workaround for JRUBY, since they handle the TempFile path different.
  # MUST be improved to be safer and OS independent.
  if RUBY_PLATFORM == 'java'
    temp_path = "/tmp/temp-index-#{(0...15).map{ ('a'..'z').to_a[rand(26)] }.join}"
  else
    tempfile = Tempfile.new('temp-index')
    temp_path = tempfile.path
    tempfile.close
    tempfile.unlink
  end

  with_index(temp_path, &blk)
end

#with_temp_working(&blk) 



625
626
627
628
629
630
631
632
 
# File 'lib/git/base.rb', line 625

def with_temp_working &blk
  tempfile = Tempfile.new("temp-workdir")
  temp_dir = tempfile.path
  tempfile.close
  tempfile.unlink
  Dir.mkdir(temp_dir, 0700)
  with_working(temp_dir, &blk)
end

#with_working(work_dir)

:yields: the Git::WorkingDirectory



614
615
616
617
618
619
620
621
622
623
 
# File 'lib/git/base.rb', line 614

def with_working(work_dir) # :yields: the Git::WorkingDirectory
  return_value = false
  old_working = @working_directory
  set_working(work_dir)
  Dir.chdir work_dir do
    return_value = yield @working_directory
  end
  set_working(old_working)
  return_value
end

#worktree(dir, commitish = nil)

returns a Git::Worktree object for dir, commitish



670
671
672
 
# File 'lib/git/base.rb', line 670

def worktree(dir, commitish = nil)
  Git::Worktree.new(self, dir, commitish)
end

#worktrees

returns a Git::worktrees object of all the Git::Worktrees objects for this repo



676
677
678
 
# File 'lib/git/base.rb', line 676

def worktrees
  Git::Worktrees.new(self)
end

#write_and_commit_tree(opts = {}) 



600
601
602
603
 
# File 'lib/git/base.rb', line 600

def write_and_commit_tree(opts = {})
  tree = write_tree
  commit_tree(tree, opts)
end

#write_tree 



596
597
598
 
# File 'lib/git/base.rb', line 596

def write_tree
  self.lib.write_tree
end