Module: Git

Defined in:

lib/git.rb,
lib/git/lib.rb,
lib/git/log.rb,
lib/git/url.rb,
lib/git/base.rb,
lib/git/diff.rb,
lib/git/path.rb,
lib/git/index.rb,
lib/git/stash.rb,
lib/git/author.rb,
lib/git/branch.rb,
lib/git/config.rb,
lib/git/object.rb,
lib/git/remote.rb,
lib/git/status.rb,
lib/git/stashes.rb,
lib/git/version.rb,
lib/git/branches.rb,
lib/git/worktree.rb,
lib/git/worktrees.rb,
lib/git/repository.rb,
lib/git/base/factory.rb,
lib/git/escaped_path.rb,
lib/git/encoding_utils.rb,
lib/git/working_directory.rb

Overview

The Git module provides the basic functions to open a git reference to work with. You can open a working directory, open a bare repository, initialize a new repo or clone an existing remote repository.

Author:

• Scott Chacon (schacon@gmail.com)

Defined Under Namespace

Modules: EncodingUtils Classes: Author, Base, Branch, Branches, Config, Diff, EscapedPath, GitAltURI, GitExecuteError, GitTagNameDoesNotExist, Index, Lib, Log, Object, Path, Remote, Repository, Stash, Stashes, Status, URL, WorkingDirectory, Worktree, Worktrees

Constant Summary

VERSION =

The current gem version

Returns:

• (String) —

  the current gem version.

'1.12.0'

Class Method Summary

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

  Open a bare repository.

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

  Clone a repository into an empty or newly created directory.

• .config ⇒ Object
• .configure {|Base.config| ... } ⇒ Object
• .export(repository, name, options = {}) ⇒ Object

  Export the current HEAD (or a branch, if options[:branch] is specified) into the name directory, then remove all traces of git from the directory.

• .global_config(name = nil, value = nil) ⇒ Object

  Same as g.config, but forces it to be at the global level.

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

  Create an empty Git repository or reinitialize an existing Git repository.

• .ls_remote(location = nil, options = {}) ⇒ {String=>Hash}

  returns a Hash containing information about the references of the target repository.

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

  Open a an existing Git working directory.

Instance Method Summary

• #config(name = nil, value = nil) ⇒ Object

  g.config(‘user.name’, ‘Scott Chacon’) # sets value g.config(‘user.email’, ‘email@email.com’) # sets value g.config(‘user.name’) # returns ‘Scott Chacon’ g.config # returns whole config hash.

• #global_config(name = nil, value = nil) ⇒ Object

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](www.rubydoc.info/stdlib/core/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:

• What is a bare repository?

# File 'lib/git.rb', line 101

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

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

Clone a repository into an empty or newly created directory

Examples:

Clone into the default directory ‘ruby-git`

git = Git.clone('https://github.com/ruby-git/ruby-git.git')

Clone and then checkout the ‘development` branch

git = Git.clone('https://github.com/ruby-git/ruby-git.git', branch: 'development')

Clone into a different directory ‘my-ruby-git`

git = Git.clone('https://github.com/ruby-git/ruby-git.git', 'my-ruby-git')
# or:
git = Git.clone('https://github.com/ruby-git/ruby-git.git', path: 'my-ruby-git')

Create a bare repository in the directory ‘ruby-git.git`

git = Git.clone('https://github.com/ruby-git/ruby-git.git', bare: true)

Parameters:

• repository_url (URI, Pathname) —

  The (possibly remote) repository url to clone from. See [GIT URLS](git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) for more information.

• directory (Pathname, nil) (defaults to: 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: `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?](git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository).

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

Returns:

• (Git::Base) —

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

See Also:

• git clone
• GIT URLs

# File 'lib/git.rb', line 173

def self.clone(repository_url, directory = nil, options = {})
  clone_to_options = options.select { |key, _value| i[bare mirror].include?(key) }
  directory ||= Git::URL.clone_to(repository_url, **clone_to_options)
  Base.clone(repository_url, directory, options)
end

.config ⇒ Object

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

def self.config
  return Base.config
end

.configure {|Base.config| ... } ⇒ Object

Yields:

• (Base.config)

# File 'lib/git.rb', line 61

def self.configure
  yield Base.config
end

.export(repository, name, options = {}) ⇒ Object

Export the current HEAD (or a branch, if options[:branch] is specified) into the name directory, then remove all traces of git from the directory.

See clone for options. Does not obey the :remote option, since the .git info will be deleted anyway; always uses the default remote, ‘origin.’

# File 'lib/git.rb', line 186

def self.export(repository, name, options = {})
  options.delete(:remote)
  repo = clone(repository, name, {:depth => 1}.merge(options))
  repo.checkout("origin/#{options[:branch]}") if options[:branch]
  Dir.chdir(repo.dir.to_s) { FileUtils.rm_r '.git' }
end

.global_config(name = nil, value = nil) ⇒ Object

Same as g.config, but forces it to be at the global level

g.config(‘user.name’, ‘Scott Chacon’) # sets value g.config(‘user.email’, ‘email@email.com’) # sets value g.config(‘user.name’) # returns ‘Scott Chacon’ g.config # returns whole config hash

# File 'lib/git.rb', line 199

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

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

Create an empty Git repository or reinitialize an existing Git repository

Examples:

Initialize a repository in the current directory

git = Git.init

Initialize a repository in some other directory

git = Git.init '~/code/ruby-git'

Initialize a bare repository

git = Git.init '~/code/ruby-git.git', bare: true

Initialize a repository in a non-default location (outside of the working copy)

git = Git.init '~/code/ruby-git', repository: '~/code/ruby-git.git'

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](www.rubydoc.info/stdlib/core/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?](git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository).

• :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](www.rubydoc.info/stdlib/core/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:

• git init

# File 'lib/git.rb', line 263

def self.init(directory = '.', options = {})
  Base.init(directory, options)
end

.ls_remote(location = nil, options = {}) ⇒ {String=>Hash}

returns a Hash containing information about the references of the target repository

options

:refs

Parameters:

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

  the target repository location or nil for ‘.’

Returns:

• ({String=>Hash}) —

  the available references of the target repo.

# File 'lib/git.rb', line 275

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

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

Open a an existing Git working directory

Git.open will most likely be the most common way to create a git reference, referring to an existing working directory.

If not provided in the options, the library will assume the repository and index are in the default places (‘.git/`, `.git/index`).

Examples:

Open the Git working directory in the current directory

git = Git.open

Open a Git working directory in some other directory

git = Git.open('~/Projects/ruby-git')

Use a logger to see what is going on

logger = Logger.new(STDOUT)
git = Git.open('~/Projects/ruby-git', log: logger)

Open a working copy whose repository is in a non-standard directory

git = Git.open('~/Projects/ruby-git', repository: '~/Project/ruby-git.git')

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](www.rubydoc.info/stdlib/core/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

# File 'lib/git.rb', line 323

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

Instance Method Details

#config(name = nil, value = nil) ⇒ Object

g.config(‘user.name’, ‘Scott Chacon’) # sets value g.config(‘user.email’, ‘email@email.com’) # sets value g.config(‘user.name’) # returns ‘Scott Chacon’ g.config # returns whole config hash

# File 'lib/git.rb', line 47

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

#global_config(name = nil, value = nil) ⇒ Object

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

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