Class: Git::Base

Inherits:
Object
  • Object
show all
Includes:
Factory
Defined in:
lib/git/base.rb,
lib/git/base/factory.rb

Overview

Git::Base is 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.

Defined Under Namespace

Modules: Factory

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Factory

#branch, #branches, #commit_tree, #diff, #gblob, #gcommit, #gtree, #log, #merge_base, #object, #remote, #status, #tag, #worktree, #worktrees

Constructor Details

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

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

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.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/git/base.rb', line 106

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

  @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"

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:



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

def self.bare(git_dir, options = {})
  self.new({:repository => git_dir}.merge(options))
end

.clone(repository, name, 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)

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.

  • :depth (Integer) —

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

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



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

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

.config ⇒ Git::Config

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



26
27
28
 
# File 'lib/git/base.rb', line 26

def self.config
  return @@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'

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

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



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/git/base.rb', line 31

def self.init(directory, options = {})
  options[:working_directory] ||= directory
  options[:repository] ||= File.join(options[:working_directory], '.git')

  FileUtils.mkdir_p(options[:working_directory]) if options[:working_directory] && !File.directory?(options[:working_directory])

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

  options.delete(:working_directory) if options[:bare]

  # Submodules have a .git *file* not a .git folder.
  # This file's contents point to the location of
  # where the git refs are held (In the parent repo)
  if options[:working_directory] && File.file?(File.join(options[:working_directory], '.git'))
    git_file = File.open('.git').read[8..-1].strip
    options[:repository] = git_file
    options[:index] = git_file + '/index'
  end

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

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.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/git/base.rb', line 66

def self.open(working_dir, options={})
   # TODO: move this to Git.open?

  options[:working_directory] ||= working_dir
  options[:repository] ||= File.join(options[:working_directory], '.git')

   # Submodules have a .git *file* not a .git folder.
  # This file's contents point to the location of
  # where the git refs are held (In the parent repo)
  if options[:working_directory] && File.file?(File.join(options[:working_directory], '.git'))
    git_file = File.open('.git').read[8..-1].strip
    options[:repository] = git_file
    options[:index] = git_file + '/index'
  end

  self.new(options)
end

Instance Method Details

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

updates the repository index using the working directory content

options: :all => true

Examples:

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

Options Hash (**options):

  • :all (boolean) —

    Update the index not only where the working tree has a file matching but also where the index already has an entry. See the --all option to git-add for more details.



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

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



408
409
410
411
412
 
# File 'lib/git/base.rb', line 408

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)

Creates a new git tag (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'})

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.



458
459
460
461
 
# File 'lib/git/base.rb', line 458

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

#apply(file) 



482
483
484
485
486
 
# File 'lib/git/base.rb', line 482

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

#apply_mail(file) 



488
489
490
 
# File 'lib/git/base.rb', line 488

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



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

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

#cat_file(objectish) 



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

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



132
133
134
135
136
 
# File 'lib/git/base.rb', line 132

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

#checkout(branch = 'master', opts = {})

checks out a branch as the new git working directory



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

def checkout(branch = 'master', opts = {})
  self.lib.checkout(branch, opts)
end

#checkout_file(version, file)

checks out an old version of a file



349
350
351
 
# File 'lib/git/base.rb', line 349

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

#checkout_index(opts = {}) 



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

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

#clean(opts = {})

cleans the working directory

options: :force :d



290
291
292
 
# File 'lib/git/base.rb', line 290

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



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

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.



338
339
340
341
 
# File 'lib/git/base.rb', line 338

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

#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



142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/git/base.rb', line 142

def config(name = nil, value = nil)
  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

#current_branch

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



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

def current_branch
  self.lib.branch_current
end

#delete_tag(name)

deletes a tag



464
465
466
 
# File 'lib/git/base.rb', line 464

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



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

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

#dir

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



158
159
160
 
# File 'lib/git/base.rb', line 158

def dir
  @working_directory
end

#each_conflict(&block)

iterates over the files which are unmerged



379
380
381
 
# File 'lib/git/base.rb', line 379

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



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

def fetch(remote = 'origin', opts={})
  self.lib.fetch(remote, opts)
end

#gc 



478
479
480
 
# File 'lib/git/base.rb', line 478

def gc
  self.lib.gc
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



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

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

#index

returns reference to the git index file



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

def index
  @index
end

#is_branch?(branch) ⇒ Boolean

returns +true+ if the branch exists



207
208
209
210
 
# File 'lib/git/base.rb', line 207

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



195
196
197
198
 
# File 'lib/git/base.rb', line 195

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



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

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



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

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

#ls_files(location = nil) 



548
549
550
 
# File 'lib/git/base.rb', line 548

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

#ls_tree(objectish) 



584
585
586
 
# File 'lib/git/base.rb', line 584

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



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

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

#pull(remote = 'origin', branch = 'master')

pulls the given branch from the given remote into the current branch

@git.pull # pulls from origin/master @git.pull('upstream') # pulls from upstream/master @git.pull('upstream', 'develope') # pulls from upstream/develop



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

def pull(remote='origin', branch='master')
  self.lib.pull(remote, branch)
end

#push(remote = 'origin', branch = 'master', opts = {})

pushes changes to a remote repository - easiest if this is a cloned repository, otherwise you may have to run something like this first to setup the push parameters:

@git.config('remote.remote-name.push', 'refs/heads/master:refs/heads/master')



364
365
366
367
368
369
 
# File 'lib/git/base.rb', line 364

def push(remote = 'origin', branch = 'master', opts = {})
  # Small hack to keep backwards compatibility with the 'push(remote, branch, tags)' method signature.
  opts = {:tags => opts} if [true, false].include?(opts)

  self.lib.push(remote, branch, opts)
end

#read_tree(treeish, opts = {}) 



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

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

#remotes

returns an array of Git:Remote objects



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

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

#remove(path = '.', opts = {})

removes file(s) from the git repository



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

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

#remove_remote(name)

removes a remote from this repository

@git.remove_remote('scott_git')



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

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

#repack

repacks the repository



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

def repack
  self.lib.repack
end

#repo

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



169
170
171
 
# File 'lib/git/base.rb', line 169

def repo
  @repository
end

#repo_size

returns the repository size in bytes



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

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



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

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'



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

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



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

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



580
581
582
 
# File 'lib/git/base.rb', line 580

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

#set_index(index_file, check = true) 



184
185
186
187
 
# File 'lib/git/base.rb', line 184

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

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

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

accepts options: :push

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



422
423
424
425
426
 
# File 'lib/git/base.rb', line 422

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

#set_working(work_dir, check = true) 



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

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



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

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

#tags

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



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

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

#update_ref(branch, commit) 



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

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

#with_index(new_index)

LOWER LEVEL INDEX OPERATIONS ##



503
504
505
506
507
508
509
 
# File 'lib/git/base.rb', line 503

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) 



511
512
513
514
515
516
517
518
519
520
521
522
523
524
 
# File 'lib/git/base.rb', line 511

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) 



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

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



552
553
554
555
556
557
558
559
560
561
 
# File 'lib/git/base.rb', line 552

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

#write_and_commit_tree(opts = {}) 



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

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

#write_tree 



534
535
536
 
# File 'lib/git/base.rb', line 534

def write_tree
  self.lib.write_tree
end