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.

INSTALLING AND RUNNING

First you need to install libgit2:

$ git clone git://github.com/libgit2/libgit2.git
$ cd libgit2
$ mdkir build && cd build
$ cmake ..
$ make
$ make install

Next, you need to install rake-compiler:

$ sudo gem install rake-compiler

Now that those are installed, you can install Rugged:

$ git clone git://github.com/libgit2/rugged.git
$ cd rugged
$ rake compile
$ rake test

API

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 =
Rugged::Repository.new(path)
ctnt, type = repo.read(sha)
gobj = repo.lookup(sha, type[?]) # optional type argument for checking
sha = repo.write(content, type)
sha = repo.hash(content, type)
bool = repo.exists(sha)
index = repo.index

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

object =
# Constructor is inherited by all the repository objects
# ‘sha’ is the ID of the object;
# ‘repo’ is the repository where the object resides
# If both ‘sha’ and ‘repo’ exist, the object will be looked up on
# the repository and instantiated
# If the ‘sha’ ID of the object is missing, the object will be
# created in memory and can be written later on to the repository
Rugged::Object.new(repo, sha)
obj.oid
obj.type

str = obj.read_raw # read the raw data of the object

The next classes are for consuming and creating the 4 base
git object types. Just about every method should be able to take
a parameter to change the value so the object can be re-written
slightly different or no parameter to simply read the current
value out.

gobjc = Rugged::Commit.new
# Rugged::Commit.new < Rugged::Object
str = gobjc.message
str = gobjc.message_short
str = gobjc.message_body # TODO
prsn = gobjc.author
prsn = gobjc.committer
gobjr = gobjc.tree
sha = gobjc.tree_sha
arr = gobjc.parents [*] # TODO: write

gobtg = Rugged::Tag.new
# Rugged::Tag.new < Rugged::Object
gobj = gobtg.target
int = gobtg.target_type
str = gobtg.name
prsn = gobtg.tagger
str = gobtg.message

gobtr = Rugged::Tree.new
# Rugged::Tree.new < Rugged::Object
gobtr.add(ent) # TODO
gobtr.remove(name) # TODO
int = gobtr.entry_count
ent = gobtr.get_entry

ent =
Rugged::TreeEntry.new(attributes, name, sha)
int = ent.attributes
str = ent.name
sha = ent.sha
gobj = ent.to_object

// * Person information is returned as a hash table

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 =
Rugged::Walker.new(repo)
walker.walk { |c| puts c.inspect } # walk is just an alias of each
walker.each { |c| puts c.inspect }
walker.push(hex_sha_interesting)
walker.hide(hex_sha_uninteresting)
walker.reset

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.

# TODO: the remove and add functions immediately flush to the index file on disk
index =
Rugged::Index.new(path)
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.remove(i/path)
index.add(ientry) # also updates existing entry if there is one
index.add(path) # create ientry from file in path, update index
#TODO index.read_tree(gobtr, path=‘/’)
#TODO index.write_tree

Index Status # TODO

#TODO index.status # how does the index differ from the work tree and the last commit

# >> pp stat
# [ [‘file1’, :staged],
# [‘file2’, :modified],
# [‘file3’, :deleted],
# [‘file4’, :untracked],
# [‘file4’, :unmerged],
# ]

Ref Management # TODO

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

list =
Rugged::RefList.new(repo)
ref = list.head # can retrieve and set HEAD with this - returns ref obj or commit obj if detatched
array = list.list([type]) # type is ‘heads’, ‘tags’, ‘remotes’, ‘notes’, et
list.add(oref)
list.pack
list.unpack

oref =
Rugged::Ref.new(ref, sha)
br.name # master
br.ref # refs/heads/master
br.type # heads
br.object
br.sha
br.delete
br.save

Config Management # TODO

conf =
Rugged::Config.new(repo)
hash = conf.list([section])
val = conf.get(key, [scope])
bool = conf.set(key, value, [scope]) # scope is ‘local’(default), ‘global’, ‘system’

Client Transport # TODO

client =
Rugged::Client.new(repo)
summry = client.fetch(url, [refs])
summry = client.push(url, refs)
refs = client.refs(url) # ls-remote

Remote Management # TODO

remlist =
Rugged::RemoteList.new(repo)
array = remlist.list
rem = remlist.add(alias, url)

rem =
Rugged::Remote.new(repo)
summry = rem.fetch([refs])
summry = rem.push(refs)
summry = rem.remove(refs)
bool = rem.delete
heads = rem.heads

Server Transport # TODO

server =
Rugged::Server.new
server.listen(port = 8080, ip = 0.0.0.0)
server.export_repo(path/repo)
server.export_path(path)

TODO

I will try to keep this up to date with the working public API available in
the libgit2 linkable library. Whatever is available there should be here
as well. The latest libgit2 commit known to link and build successfully will
be listed in the LIBGIT2_VERSION file.

CONTRIBUTING

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

AUTHORS

Scott Chacon
Vicent Marti

LICENSE

MIT. See LICENSE file.

Modules

Classes