Rugged

libgit2 bindings in Ruby

Rugged is a library for accessing libgit2 in Ruby. It gives you the speed and portability of libgit2 with the beauty of the Ruby language.

libgit2

libgit2 is a pure C implementation of the Git core methods. It's designed to be fast and portable. For more information about libgit2, check out libgit2's website or browse the libgit2 organization on GitHub.

Install

Rugged is a self-contained gem. You can install it by running:

$ gem install rugged

Prerequisites

You need to have CMake and pkg-config installed on your system to be able to build the included version of libgit2.

Debian, Including Ubuntu

All Debian-derived Linux distros provide apt:

$ sudo apt install libgit2-dev cmake pkg-config

Note that you only need libgit2-dev if you want to build with the system libgit2 rather than the vendored version. In this case, note that the major and minor versions of libgit2 and rugged must match.

Mac

On OS X, after installing Homebrew, you can get the required packages with:

$ brew install cmake pkg-config

Please follow the above in case installation of the gem fails with ERROR: CMake is required to build Rugged..

Options

If you want to build Rugged with HTTPS and SSH support, check out the list of optional libgit2 dependencies.

For SSH suport you have 2 options: libssh2 (recommended) or OpenSSH command execution (handy when you want to configure SSH behavior through .ssh/config):

1. To use Libssh2, ensure libssh2 library is present and either pass the required CMAKE_FLAGS:

CMAKE_FLAGS='-DUSE_SSH=ON' gem install rugged

or the --with-ssh build option:

gem install rugged -- --with-ssh

2. To execute external OpenSSH commands instead of libssh2, either pass the required CMAKE_FLAGS:

CMAKE_FLAGS='-DUSE_SSH=exec' gem install rugged

or the --with-ssh-exec build option:

gem install rugged -- --with-ssh-exec

If you're using bundler and want to bundle libgit2 with Rugged, you can use the :submodules option:

gem 'rugged', git: 'git://github.com/libgit2/rugged.git', submodules: true

If you would like to bundle rugged with SSH support add the --with-ssh or --with-ssh-exec build option to the bundler config:

bundle config build.rugged --with-ssh

Usage

To load Rugged, you'll usually want to add something like this:

require 'rugged'

Use the system provided libgit2

By default, Rugged builds and uses a bundled version of libgit2. If you want to use the system library instead, you can install rugged as follows:

gem install rugged -- --use-system-libraries

Or if you are using bundler:

bundle config build.rugged --use-system-libraries
bundle install

However, note that Rugged does only support specific versions of libgit2.

Usage

Rugged gives you access to the many parts of a Git repository. You can read and write objects, walk a tree, access the staging area, and lots more. Let's look at each area individually.

Repositories

Instantiation

The repository is naturally central to Git. Rugged has a Repository class that you can instantiate with a path to open an existing repository :

repo = Rugged::Repository.new('path/to/my/repository')
# => #<Rugged::Repository:2228536260 {path: "path/to/my/repository/.git/"}>

You can create a new repository with init_at. Add a second parameter :bare to make a bare repository:

Rugged::Repository.init_at('.', :bare)

You can also let Rugged discover the path to the .git directory if you give it a subdirectory.

Rugged::Repository.discover("/Users/me/projects/repo/lib/subdir/")
# => "/Users/me/projects/repo/.git/"

Once your Repository instantiated (in the following examples, as repo), you can access or modify it.

Accessing a Repository

# Does the given SHA1 exist in this repository?
repo.exists?('07b44cbda23b726e5d54e2ef383495922c024202')
# => true

# Boolean repository state values:
repo.bare?
# => false
repo.empty?
# => true
repo.head_unborn?
# => false
repo.head_detached?
# => false

# Path accessors
repo.path
# => "path/to/my/repository/.git/"
repo.workdir
# => "path/to/my/repository/"

# The HEAD of the repository.
ref = repo.head
# => #<Rugged::Reference:2228467240 {name: "refs/heads/master", target:  #<Rugged::Commit:2228467250 {message: "helpful message", tree: #<Rugged::Tree:2228467260 {oid: 5d6f29220a0783b8085134df14ec4d960b6c3bf2}>}>

# From the returned ref, you can also access the `name`, `target`, and target SHA:
ref.name
# => "refs/heads/master"
ref.target
# => #<Rugged::Commit:2228467250 {message: "helpful message", tree: #<Rugged::Tree:2228467260 {oid: 5d6f29220a0783b8085134df14ec4d960b6c3bf2}>}>
ref.target_id
# => "2bc6a70483369f33f641ca44873497f13a15cde5"

# Reading an object
object = repo.read('a0ae5566e3c8a3bddffab21022056f0b5e03ef07')
# => #<Rugged::OdbObject:0x109a64780>
object.len
# => 237
object.data
# => "tree 76f23f186076fc291742816721ea8c3e95567241\nparent 8e3c5c52b8f29da0adc7e8be8a037cbeaea6de6b\nauthor Vicent Mart\303\255 <tanoku@gmail.com> 1333859005 +0200\ncommitter Vicent Mart\303\255 <tanoku@gmail.com> 1333859005 +0200\n\nAdd `Repository#blob_at`\n"
object.type
# => :commit

Writing to a Repository

There's a few ways to write to a repository. To write directly from your instantiated repository object:

sha = repo.write(content, type)

You can also use the Commit object directly to craft a commit; this is a bit more high-level, so it may be preferable:

oid = repo.write("This is a blob.", :blob)
index = repo.index
index.read_tree(repo.head.target.tree)
index.add(:path => "README.md", :oid => oid, :mode => 0100644)

options = {}
options[:tree] = index.write_tree(repo)

options[:author] = { :email => "testuser@github.com", :name => 'Test Author', :time => Time.now }
options[:committer] = { :email => "testuser@github.com", :name => 'Test Author', :time => Time.now }
options[:message] ||= "Making a commit via Rugged!"
options[:parents] = repo.empty? ? [] : [ repo.head.target ].compact
options[:update_ref] = 'HEAD'

Rugged::Commit.create(repo, options)

---

Objects

Object is the main object class - it shouldn't be created directly, but all of these methods should be useful in their derived classes.

obj = repo.lookup(sha)
obj.oid  # object sha
obj.type # One of :commit, :tree, :blob or :tag

robj = obj.read_raw
str  = robj.data
int  = robj.len

There are four base object types in Git: blobs, commits, tags, and trees. Each of these object types have a corresponding class within Rugged.

Commit Objects

commit = repo.lookup('a0ae5566e3c8a3bddffab21022056f0b5e03ef07')
# => #<Rugged::Commit:2245304380>

commit.message
# => "Add `Repository#blob_at`\n"

commit.time
# => Sat Apr 07 21:23:25 -0700 2012

commit.author
# => {:email=>"tanoku@gmail.com", :name=>"Vicent Mart\303\255", :time=>Sun Apr 08 04:23:25 UTC 2012}

commit.tree
# => #<Rugged::Tree:2245269740>

commit.parents
# => [#<Rugged::Commit:2245264600 {message: "Merge pull request #47 from isaac/remotes\n\nAdd Rugged::Repository#remotes", tree: #<Rugged::Tree:2245264240 {oid: 6a2aee58a41fa007d07aa55565e2231f9b39b4a9}>]

You can also write new objects to the database this way:

author = {:email=>"tanoku@gmail.com", :time=>Time.now, :name=>"Vicent Mart\303\255"}

Rugged::Commit.create(r,
	:author => author,
	:message => "Hello world\n\n",
	:committer => author,
	:parents => ["2cb831a8aea28b2c1b9c63385585b864e4d3bad1"],
	:tree => some_tree,
	:update_ref => "HEAD") #=> "f148106ca58764adc93ad4e2d6b1d168422b9796"

Tag Objects

tag  = repo.lookup(tag_sha)

object = tag.target
sha    = tag.target.oid
str    = tag.target_type # :commit, :tag, :blob
str    = tag.name        # "v1.0"
str    = tag.message
person = tag.tagger

Tree Objects

tree = repo.lookup('779fbb1e17e666832773a9825875300ea736c2da')
# => #<Rugged::Tree:2245194360>

# number of tree entries
tree.count

tree[0]           # or...
tree.first        # or...
tree.get_entry(0)
# => {:type=>:blob, :oid=>"99e7edb53db9355f10c6f2dfaa5a183f205d93bf", :filemode=>33188, :name=>".gitignore"}

The tree object is an Enumerable, so you can also do stuff like this:

tree.each { |e| puts e[:oid] }
tree.sort { |a, b| a[:oid] <=> b[:oid] }.map { |e| e[:name] }.join(':')

And there are some Rugged-specific methods, too:

tree.each_tree { |entry| puts entry[:name] }  # list subdirs
tree.each_blob { |entry| puts entry[:name] }  # list only files

You can also write trees with the TreeBuilder:

oid = repo.write("This is a blob.", :blob)
builder = Rugged::Tree::Builder.new(repo)
builder << { :type => :blob, :name => "README.md", :oid => oid, :filemode => 0100644 }

options = {}
options[:tree] = builder.write

options[:author] = { :email => "testuser@github.com", :name => 'Test Author', :time => Time.now }
options[:committer] = { :email => "testuser@github.com", :name => 'Test Author', :time => Time.now }
options[:message] ||= "Making a commit via Rugged!"
options[:parents] = repo.empty? ? [] : [ repo.head.target ].compact
options[:update_ref] = 'HEAD'

Rugged::Commit.create(repo, options)

Blob Objects

Blob objects represent the data in the files of a Tree Object.

blob = repo.lookup('e1253910439ea902cf49be8a9f02f3c08d89ac73')
blob.content # => Gives you the content of the blob.

Streaming Blob Objects

There is currently no way to stream data from a blob, because libgit2 i