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.

[View source]

138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/git/base.rb', line 138

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:

[View source]

17
18
19
20
 
# File 'lib/git/base.rb', line 17

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

.binary_version(binary_path)

[View source]

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

def self.binary_version(binary_path)
  result = nil
  status = nil

  begin
    result, status = Open3.capture2e(binary_path, "-c", "core.quotePath=true", "-c", "color.ui=false", "version")
    result = result.chomp
  rescue Errno::ENOENT
    raise RuntimeError, "Failed to get git version: #{binary_path} not found"
  end

  if status.success?
    version = result[/\d+(\.\d+)+/]
    version_parts = version.split('.').collect { |i| i.to_i }
    version_parts.fill(0, version_parts.length...3)
  else
    raise RuntimeError, "Failed to get git version: #{status}\n#{result}"
  end
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', 'user.email=john@doe.com']
)

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:

[View source]

23
24
25
26
27
 
# File 'lib/git/base.rb', line 23

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:

[View source]

37
38
39
 
# File 'lib/git/base.rb', line 37

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:

[View source]

62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/git/base.rb', line 62

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)
[View source]

106
107
108
109
110
111
112
113
114
 
# File 'lib/git/base.rb', line 106

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

[View source]

30
31
32
 
# File 'lib/git/base.rb', line 30

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)
[View source]

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/git/base.rb', line 88

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

  raise ArgumentError, "'#{working_dir}' does not exist" unless Dir.exist?(working_dir)

  begin
    result, status = Open3.capture2e(Git::Base.config.binary_path, "-c", "core.quotePath=true", "-c", "color.ui=false", "rev-parse", "--show-toplevel", chdir: File.expand_path(working_dir))
    result = result.chomp
  rescue Errno::ENOENT
    raise ArgumentError, "Failed to find the root of the worktree: git binary not found"
  end

  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

[View source]

164
165
166
 
# File 'lib/git/base.rb', line 164

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 =>

[View source]

178
179
180
181
182
 
# File 'lib/git/base.rb', line 178

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.

[View source]

202
203
204
205
 
# File 'lib/git/base.rb', line 202

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

#apply(file)

[View source]

571
572
573
574
575
 
# File 'lib/git/base.rb', line 571

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

#apply_mail(file)

[View source]

577
578
579
 
# File 'lib/git/base.rb', line 577

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

[View source]

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

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:

[View source]

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

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:

[View source]

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

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

#cat_file(objectish)

[View source]

679
680
681
 
# File 'lib/git/base.rb', line 679

def cat_file(objectish)
  self.lib.cat_file(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

[View source]

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

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

[View source]

425
426
427
 
# File 'lib/git/base.rb', line 425

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

#checkout_file(version, file)

checks out an old version of a file

[View source]

430
431
432
 
# File 'lib/git/base.rb', line 430

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

#checkout_index(opts = {})

[View source]

615
616
617
 
# File 'lib/git/base.rb', line 615

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

#clean(opts = {})

cleans the working directory

options: :force :d :ff

[View source]

371
372
373
 
# File 'lib/git/base.rb', line 371

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

[View source]

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

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.

[View source]

419
420
421
422
 
# File 'lib/git/base.rb', line 419

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:

[View source]

718
719
720
 
# File 'lib/git/base.rb', line 718

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@email.com') # sets value g.config('user.email', 'email@email.com', file: 'path/to/custom/config) # sets value in file g.config('user.name') # returns 'Scott Chacon' g.config # returns whole config hash

[View source]

227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/git/base.rb', line 227

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 ⇒ String

The name of the branch HEAD refers to or 'HEAD' if detached

Returns one of the following:

  • The branch name that HEAD refers to (even if it is an unborn branch)
  • 'HEAD' if in a detached HEAD state

Returns:

  • (String) —

    the name of the branch HEAD refers to or 'HEAD' if detached

[View source]

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

def current_branch
  self.lib.branch_current
end

#delete_tag(name)

deletes a tag

[View source]

553
554
555
 
# File 'lib/git/base.rb', line 553

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

[View source]

390
391
392
 
# File 'lib/git/base.rb', line 390

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

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

Returns a Git::Diff object.

Returns:

[View source]

723
724
725
 
# File 'lib/git/base.rb', line 723

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?

[View source]

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

def dir
  @working_directory
end

#each_conflict(&block)

iterates over the files which are unmerged

[View source]

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

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

[View source]

436
437
438
439
440
441
442
 
# File 'lib/git/base.rb', line 436

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:

[View source]

728
729
730
 
# File 'lib/git/base.rb', line 728

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

#gc

[View source]

567
568
569
 
# File 'lib/git/base.rb', line 567

def gc
  self.lib.gc
end

#gcommit(objectish) ⇒ Git::Object

Returns a Git object.

Returns:

[View source]

733
734
735
 
# File 'lib/git/base.rb', line 733

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], ...],
   ...
}
[View source]

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

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:

[View source]

738
739
740
 
# File 'lib/git/base.rb', line 738

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

[View source]

342
343
344
 
# File 'lib/git/base.rb', line 342

def ignored_files
  self.lib.ignored_files
end

#index

returns reference to the git index file

[View source]

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

def index
  @index
end

#is_branch?(branch) ⇒ Boolean

returns +true+ if the branch exists

Returns:

  • (Boolean)
[View source]

292
293
294
295
 
# File 'lib/git/base.rb', line 292

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)
[View source]

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

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)
[View source]

286
287
288
289
 
# File 'lib/git/base.rb', line 286

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

[View source]

300
301
302
 
# File 'lib/git/base.rb', line 300

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

[View source]

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

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

#ls_files(location = nil)

[View source]

637
638
639
 
# File 'lib/git/base.rb', line 637

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

#ls_tree(objectish, opts = {})

[View source]

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

def ls_tree(objectish, opts = {})
  self.lib.ls_tree(objectish, opts)
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

[View source]

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

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:

[View source]

780
781
782
783
 
# File 'lib/git/base.rb', line 780

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

[View source]

757
758
759
 
# File 'lib/git/base.rb', line 757

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

[View source]

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

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

[View source]

462
463
464
 
# File 'lib/git/base.rb', line 462

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

#read_tree(treeish, opts = {})

[View source]

619
620
621
 
# File 'lib/git/base.rb', line 619

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:

[View source]

762
763
764
 
# File 'lib/git/base.rb', line 762

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

#remotes

returns an array of Git:Remote objects

[View source]

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

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

[View source]

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

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

#repack

repacks the repository

[View source]

563
564
565
 
# File 'lib/git/base.rb', line 563

def repack
  self.lib.repack
end

#repo

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

[View source]

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

def repo
  @repository
end

#repo_size

returns the repository size in bytes

[View source]

259
260
261
262
263
264
265
266
267
 
# File 'lib/git/base.rb', line 259

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

[View source]

354
355
356
 
# File 'lib/git/base.rb', line 354

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'

[View source]

359
360
361
362
 
# File 'lib/git/base.rb', line 359

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

#rev_parse(objectish) Also known as: revparse

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

Examples:

git.rev_parse("HEAD^^")
git.rev_parse('v2.4^{tree}')
git.rev_parse('v2.4:/doc/index.html')
[View source]

668
669
670
 
# File 'lib/git/base.rb', line 668

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

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

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

options: :no_edit

[View source]

400
401
402
 
# File 'lib/git/base.rb', line 400

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

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

removes file(s) from the git repository

[View source]

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

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

#set_index(index_file, check = true)

[View source]

269
270
271
272
 
# File 'lib/git/base.rb', line 269

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

[View source]

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

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)

[View source]

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

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

[View source]

586
587
588
 
# File 'lib/git/base.rb', line 586

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

#status ⇒ Git::Status

Returns a status object.

Returns:

[View source]

767
768
769
 
# File 'lib/git/base.rb', line 767

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

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

Returns a tag object.

Returns:

[View source]

772
773
774
 
# File 'lib/git/base.rb', line 772

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

[View source]

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

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

#update_ref(branch, commit)

[View source]

632
633
634
 
# File 'lib/git/base.rb', line 632

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

#with_index(new_index)

LOWER LEVEL INDEX OPERATIONS ##

[View source]

592
593
594
595
596
597
598
 
# File 'lib/git/base.rb', line 592

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)

[View source]

600
601
602
603
604
605
606
607
608
609
610
611
612
613
 
# File 'lib/git/base.rb', line 600

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)

[View source]

652
653
654
655
656
657
658
659
 
# File 'lib/git/base.rb', line 652

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

[View source]

641
642
643
644
645
646
647
648
649
650
 
# File 'lib/git/base.rb', line 641

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

[View source]

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

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

[View source]

713
714
715
 
# File 'lib/git/base.rb', line 713

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

#write_and_commit_tree(opts = {})

[View source]

627
628
629
630
 
# File 'lib/git/base.rb', line 627

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

#write_tree

[View source]

623
624
625
 
# File 'lib/git/base.rb', line 623

def write_tree
  self.lib.write_tree
end