ruby bindings to libgit2
Clone or download
Pull request Compare This branch is 2192 commits behind libgit2:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Rugged - libgit2 bindings in Ruby

Rugged is a Ruby bindings to the libgit2 linkable C Git library. This is for testing and using the libgit2 library in a language that is awesome.


This is a self-contained gem and you should be able to easily install it by using Rubygems:

$ gem install rugged


Here are some of the ways you can use Rugged:

General Methods

There is a general library for some basic Gitty methods. So far, just converting a raw sha (20 bytes) into a readable hex sha (40 char).

raw = Rugged.hex_to_raw(hex_sha)
hex = Rugged.raw_to_hex(20_byte_raw_sha)

Repository Access

There is a Repository class that you can instantiate with a path. This lets you check for objects, read raw object data, write raw object data and get a hash (SHA1 checksum) of what contents would be without writing them out. You also use it to lookup Git objects from it.

Repository is the main repository object that everything else will emanate from.

repo =
  bool   = repo.exists(sha)
  rawobj =
    len    = rawobj.len
    data   =
             rawobj.type (Rugged::OBJ_COMMIT)
  sha    = repo.hash(content, type)
  sha    = repo.write(content, type)
  ref    = repo.head
    sha    =
             ref.type ("commit")
  bool   = repo.bare?
  bool   = repo.empty?
  bool   = repo.head_detatched?
  bool   = repo.head_orphan?
  path   = repo.workdir
  path   = repo.path

  Rugged::Repository.init_at(path, true) # 2nd param means "whether it's a bare repo""/Users/schacon/projects/work/repo/lib/subdir/")
  => "/Users/schacon/projects/work/repo/.git/"

The 'path' argument must point to an actual git repository folder. The library will automatically guess if it's a bare repository or a '.git' folder inside a working repository, and locate the working path accordingly.

Object Access

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

obj = @repo.lookup(sha)
  obj.oid  # object sha

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

The next classes are for consuming and creating the 4 base git object types.

Commit Objects

gobjc = @repo.lookup(commit_sha)
  str   = gobjc.message
  time  = gobjc.time       # author time
  prsn  =
     str   = prsn[:name]
     str   = prsn[:time]
     str   = prsn[:email]
  prsn  = gobjc.committer
  gobjr = gobjc.tree
  sha   = gobjc.tree.oid
  arr   = gobjc.parents

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

person ='Scott', '',

gobjc =
gobjc.message = "my message" = person
gobjc.tree = gobjt

Tag Objects

gobtg = @repo.lookup(tag_sha)
  gobj  =
  sha   =
  str   = gobtg.target_type # "commit", "tag", "blob"
  str   =        # "v1.0"
  str   = gobtg.message
  prsn  = gobtg.tagger
     str   = prsn[:name]
     str   = prsn[:time]
     str   = prsn[:email]

Tree Objects

gobtr = @repo.lookup(tree_sha)
  int   = gobtr.count        # number of tree entries
  ent   = gobtr[0]           # get object of first entry
  ent   = gobtr.get_entry(0) # get object of first entry
      str  = ent[:name]      # "README.txt"
      str  = ent[:type]      # :blob
      sha  = ent[:oid]       # object sha

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

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

And there are some Rugged specific methods, too:

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

You can also write trees with the TreeBuilder:

entry = {:type => :blob,
         :name => "README.txt",
         :oid  => "1385f264afb75a56a5bec74243be9b367ba4ca08",
         :attributes => 33188}

builder =
builder << entry
sha = builder.write(@repo)

Commit Walker

There is also a Walker class that currently takes a repo object. You can push head SHAs onto the walker, then call next to get a list of the reachable commit objects, one at a time. You can also hide() commits if you are not interested in anything beneath them (useful for a git log master ^origin/master type deal).

walker =
     walker.sorting(Rugged::SORT_TOPO | Rugged::SORT_REVERSE) # optional
     walker.each { |c| puts c.inspect }

Index/Staging Area

We can inspect and manipulate the Git Index as well. To work with the index inside of an existing repository, instantiate it by using the Repository.index method instead of manually opening the Index by its path.

index =
        index.reload              # re-read the index file from disk
  int = index.count # count of index entries
        index.entries # collection of index entries
        index.each { |i| puts i.inspect }
  ent = index.get_entry(i/path)
        index.add(ientry)    # also updates existing entry if there is one
        index.add(path)      # create ientry from file in path, update index

Ref Management

The RefList class allows you to list, create and delete packed and loose refs.

ref = @repo.head

ref = Rugged::Reference.lookup(@repo, "refs/heads/master")
  sha =
  str = ref.type   # "commit"
  str =   # "refs/heads/master"

You can also easily get an array of references:

@repo.refs.each do |ref|

Or with a pattern (regex):

@repo.refs(/tags/).each do |ref|

It is also easy to create, update, rename or delete a reference:

ref = Rugged::Reference.create(@repo, "refs/heads/unit_test", some_commit_sha) = new_sha



Finally, you can access the reflog for any branch:

ref = Rugged::Reference.lookup(@repo, "refs/heads/master")
entry = ref.log.first
  sha   = entry[:oid_old]
  sha   = entry[:oid_new]
  str   = entry[:message]
  prsn  = entry[:committer]

Git Config Files

It is very easy to read and manipulate the Git config file data with Rugged.

config = @repo.config
str    = config['core.bare']
         config[''] = true


Fork libgit2/rugged on GitHub, make it awesomer (preferably in a branch named for the topic), send a pull request.


First you need to install libgit2:

$ git clone git://
$ cd libgit2
$ mkdir build && cd build
$ cmake ..
$ make
$ make install

Now that those are installed, you can install Rugged:

$ git clone git://
$ cd rugged
$ bundle install
$ rake compile
$ rake test



MIT. See LICENSE file.