Module: RubyGit

Defined in:
lib/ruby_git.rb,
lib/ruby_git/errors.rb,
lib/ruby_git/status.rb,
lib/ruby_git/version.rb,
lib/ruby_git/worktree.rb,
lib/ruby_git/repository.rb,
lib/ruby_git/command_line.rb,
lib/ruby_git/status/entry.rb,
lib/ruby_git/status/stash.rb,
lib/ruby_git/status/branch.rb,
lib/ruby_git/status/parser.rb,
lib/ruby_git/status/report.rb,
lib/ruby_git/option_validators.rb,
lib/ruby_git/command_line/result.rb,
lib/ruby_git/command_line/runner.rb,
lib/ruby_git/command_line/options.rb,
lib/ruby_git/status/ignored_entry.rb,
lib/ruby_git/status/renamed_entry.rb,
lib/ruby_git/status/ordinary_entry.rb,
lib/ruby_git/status/unmerged_entry.rb,
lib/ruby_git/status/untracked_entry.rb,
lib/ruby_git/status/submodule_status.rb,
lib/ruby_git/command_line/encoding_normalizer.rb

Overview

The RubyGit module provides a Ruby API that is an object-oriented wrapper around the git command line. It is intended to make automating both simple and complex Git interactions easier. To accomplish this, it ties each action you can do with git to the type of object that action operates on.

There are three main objects in RubyGit:

  • Worktree: The directory tree of actual checked out files. The working tree normally contains the contents of the HEAD commit's tree, plus any local changes that you have made but not yet committed.
  • Index: The index is used as a staging area between your working tree and your repository. You can use the index to build up a set of changes that you want to commit together. When you create a commit, what is committed is what is currently in the index, not what is in your working directory.
  • Repository: The repository stores the files in a project, their history, and other meta data like commit information, tags, and branches.

Defined Under Namespace

Modules: CommandLine, OptionValidators, Status Classes: ArgumentError, CommandLineError, Error, FailedError, ProcessIOError, Repository, SignaledError, SpawnError, TimeoutError, UnexpectedResultError, Worktree

Constant Summary collapse

VERSION =

The ruby_git gem version

'0.4.0'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.binary_path ⇒ String

The path to the git binary used by the RubyGit gem

  • If the path is a command name, the command is search for in the PATH.

  • If the path is a relative path, it relative to the current directory (not recommended as this will change as the current directory is changed).

  • If the path is an absolute path, it is used as is.

Examples:

RubyGit.binary_path
 => "git"

Returns:

  • (String) 


72
73
74
 
# File 'lib/ruby_git.rb', line 72

def binary_path
  @binary_path
end

.logger ⇒ Logger

The logger used by the RubyGit gem (Logger.new(nil) by default)

Examples:

Using the logger

RubyGit.logger.debug('Debug message')

Setting the logger

require 'logger'
require 'stringio'
log_device = StringIO.new
RubyGit.logger = Logger.new(log_device, level: Logger::DEBUG)
RubyGit.logger.debug('Debug message')
log_device.string.include?('Debug message')
 => true

Returns:

  • (Logger) —

    the logger used by the RubyGit gem



51
52
53
 
# File 'lib/ruby_git.rb', line 51

def logger
  @logger
end

Class Method Details

.binary_version ⇒ Array<Integer>

The version of git referred to by the path

Examples:

for version 2.28.0

RubyGit.binary_version #=> [2, 28, 0]

Returns:

  • (Array<Integer>) —

    an array of integers representing the version.

Raises:

  • (RuntimeError) —

    if path was not set via path= and either PATH is not set or git was not found on the path.



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

def self.binary_version
  version_string = RubyGit::CommandLine.run('version').stdout[/\d+\.\d+(\.\d+)+/]
  version_string.split('.').collect(&:to_i)
end

.clone(repository_url, to_path: '') ⇒ RubyGit::Worktree

Copy the remote repository and checkout the default branch

Clones the repository referred to by repository_url into a newly created directory, creates remote-tracking branches for each branch in the cloned repository, and checks out the default branch in the worktree whose root directory is to_path.

to_path will be created if it does not exist. An error is raised if to_path exists and not an empty directory.

Examples:

Using default for Worktree path

FileUtils.pwd
 => "/Users/jsmith"
worktree = Worktree.clone('https://github.com/main-branch/ruby_git.git')
worktree.path
 => "/Users/jsmith/ruby_git"

Using a specified worktree_path

FileUtils.pwd
 => "/Users/jsmith"
worktree_path = '/tmp/project'
worktree = Worktree.clone('https://github.com/main-branch/ruby_git.git', to_path: worktree_path)
worktree.path
 => "/tmp/project"

Parameters:

  • repository_url (String) —

    a reference to a Git repository

  • to_path (String) (defaults to: '') —

    where to put the checked out working tree once the repository is cloned

Returns:

Raises:

  • (RubyGit::Error) —

    if (1) repository_url is not valid or does not point to a valid repository OR (2) to_path is not an empty directory.

See Also:



148
149
150
 
# File 'lib/ruby_git.rb', line 148

def self.clone(repository_url, to_path: '')
  RubyGit::Worktree.clone(repository_url, to_path:)
end

.init(worktree_path, initial_branch:) ⇒ RubyGit::Worktree

Create an empty Git repository under the root working tree path

If the repository already exists, it will not be overwritten.

Examples:

worktree = Worktree.init(worktree_path, initial_branch: 'main')

Parameters:

  • worktree_path (String) —

    the root path of a worktree

  • initial_branch (String) —

    the initial branch in the newly created repository

Returns:

Raises:

See Also:



91
92
93
 
# File 'lib/ruby_git.rb', line 91

def self.init(worktree_path, initial_branch:)
  RubyGit::Worktree.init(worktree_path, initial_branch:)
end

.open(worktree_path) ⇒ RubyGit::Worktree

Open an existing Git working tree that contains worktree_path

Examples:

worktree = Worktree.open(worktree_path)

Parameters:

  • worktree_path (String) —

    the root path of a worktree

Returns:

Raises:

  • (RubyGit::Error) —

    if worktree_path does not exist, is not a directory, or is not within a Git worktree.

See Also:



109
110
111
 
# File 'lib/ruby_git.rb', line 109

def self.open(worktree_path)
  RubyGit::Worktree.open(worktree_path)
end