rugged 0.16.0 → 0.17.0b1

data/README.md

@@ -1,279 +1,409 @@
-Rugged - libgit2 bindings in Ruby
-===================================
+# 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.
+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.
 
-INSTALLING AND RUNNING
-========================
+### libgit2
 
-First you need to install 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](http://libgit2.github.com) or browse the
+[libgit2 organization](https://github.com/libgit2) on GitHub.
 
-    $ git clone git://github.com/libgit2/libgit2.git
-    $ cd libgit2
-    $ mdkir build && cd build
-    $ cmake ..
-    $ make
-    $ make install
+## Install
 
-Next, you need to install rake-compiler:
+Rugged is a self-contained gem. You can install it by running:
 
-    $ sudo gem install rake-compiler
+    $ gem install rugged
 
-Now that those are installed, you can install Rugged:
+To load Rugged, you'll usually want to add something like this:
 
-    $ git clone git://github.com/libgit2/rugged.git
-    $ cd rugged
-    $ rake compile
-    $ rake test
+```ruby
+require 'rugged'
+```
+
+## 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:
+
+```ruby
+repo = Rugged::Repository.new('path/to/my/repository')
+# => #<Rugged::Repository:2228536260 {path: "path/to/my/repository/.git/"}>
+```
+
+If you're working against a bare repository, you'll need to indicate that:
+
+```ruby
+# Second parameter indicates whether the repo is a bare repository
+Rugged::Repository.init_at('.', true)
+```
+
+You can also let Rugged discover the path to the .git directory if you give it a
+subdirectory.
+
+```ruby
+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
+
+```ruby
+# Does the given SHA1 exist in this repository?
+repo.exists?('07b44cbda23b726e5d54e2ef383495922c024202')
+# => true
+
+# Boolean repository state values:
+repo.bare?
+# => false
+repo.empty?
+# => true
+repo.head_orphan?
+# => 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: "07b44cbda23b726e5d54e2ef383495922c024202"}>
+
+# From the returned ref, you can also access the `name` and `target`:
+ref.name
+# => "refs/heads/master"
+ref.target
+# => "07b44cbda23b726e5d54e2ef383495922c024202"
+
+# 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#file_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:
+
+```ruby
+sha = repo.hash(content, type)
+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.
+
+---
+
+### 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.
+
+```ruby
+obj = repo.lookup(sha)
+obj.oid  # object sha
+obj.type [OBJ_COMMIT, OBJ_TREE, OBJ_BLOB, OBJ_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
+
+```ruby
+commit = repo.lookup('a0ae5566e3c8a3bddffab21022056f0b5e03ef07')
+# => #<Rugged::Commit:2245304380>
+
+commit.message
+# => "Add `Repository#file_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:
+
+```ruby
+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) #=> "f148106ca58764adc93ad4e2d6b1d168422b9796"
+```
+
+### Tag Objects
+
+```ruby
+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
+
+```ruby
+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", :attributes=>33188, :name=>".gitignore"}
+```
 
+The tree object is an Enumerable, so you can also do stuff like this:
 
-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
-------------------------
+```ruby
+tree.each { |e| puts e[:oid] }
+tree.sort { |a, b| a[:oid] <=> b[:oid] }.map { |e| e[:name] }.join(':')
+```
 
-    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'
+And there are some Rugged-specific methods, too:
 
+```ruby
+tree.each_tree { |entry| puts entry[:name] }  # list subdirs
+tree.each_blob { |entry| puts entry[:name] }  # list only files
+```
 
-Client Transport # TODO
------------------------
+You can also write trees with the `TreeBuilder`:
 
-    client =
-    Rugged::Client.new(repo)
-    summry = client.fetch(url, [refs])
-    summry = client.push(url, refs)
-      refs = client.refs(url)  # ls-remote
+```ruby
+entry = {:type => :blob,
+         :name => "README.txt",
+         :oid  => "1385f264afb75a56a5bec74243be9b367ba4ca08",
+         :attributes => 33188}
 
+builder = Rugged::Tree::Builder.new
+builder << entry
+sha = builder.write(repo)
+```
 
-Remote Management # TODO
-------------------------
+---
 
-    remlist =
-    Rugged::RemoteList.new(repo)
-    array = remlist.list
-      rem = remlist.add(alias, url)
+### Commit Walker
 
-    rem =
-    Rugged::Remote.new(repo)
-    summry = rem.fetch([refs])
-    summry = rem.push(refs)
-    summry = rem.remove(refs)
-      bool = rem.delete
-     heads = rem.heads
+`Rugged::Walker` is a class designed to help you traverse a set of commits over
+a repository.
 
+You first push head SHAs onto the walker, and 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 in situations like when
+you're running something like `git log master ^origin/master`).
 
-Server Transport # TODO
-------------------------
+```ruby
+walker = Rugged::Walker.new(repo)
+walker.sorting(Rugged::SORT_TOPO | Rugged::SORT_REVERSE) # optional
+walker.push(hex_sha_interesting)
+walker.hide(hex_sha_uninteresting)
+walker.each { |c| puts c.inspect }
+walker.reset
+```
 
-    server =
-    Rugged::Server.new
-             server.listen(port = 8080, ip = 0.0.0.0)
-             server.export_repo(path/repo)
-             server.export_path(path)
+---
 
+### Index ("staging") area
 
-TODO
-==============
+We can inspect and manipulate the Git Index as well. To work with the index
+inside an existing repository, instantiate it by using the `Repository.index`
+method instead of manually opening the Index by its path.
 
-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.
+```ruby
+index = Rugged::Index.new(path)
 
+# Re-read the index file from disk.
+index.reload
 
-CONTRIBUTING
-==============
+# Count up index entries.
+count = index.count
+
+# The collection of index entries.
+index.entries
+
+# Iterating over index entries.
+index.each { |i| puts i.inspect }
+
+# Get a particular entry in the index.
+index.get_entry(path)
+
+# Unstage.
+index.remove(i/path)
+
+# Stage. Also updates existing entry if there is one.
+index.add(ientry)
+
+# Stage. Create ientry from file in path, updates the index.
+index.add(path)
+```
+
+---
+
+### Refs
+
+The `RefList` class allows you to list, create and delete packed and loose refs.
+
+```ruby
+ref = repo.head # or...
+ref = Rugged::Reference.lookup(repo, "refs/heads/master")
+
+sha = ref.target
+str = ref.type   # "commit"
+str = ref.name   # "refs/heads/master"
+```
+
+You can also easily get an array of references:
+
+```ruby
+repo.refs.each do |ref|
+  puts ref.name
+end
+```
+
+Or use a pattern (regex):
+
+```ruby
+repo.refs(/tags/).each do |ref|
+  puts ref.name
+end
+```
+
+It is also easy to create, update, rename or delete a reference:
+
+```ruby
+ref = Rugged::Reference.create(repo, "refs/heads/unit_test", some_commit_sha)
+
+ref.target = new_sha
+
+ref.rename("refs/heads/blead")
+
+ref.delete!
+```
+
+Finally, you can access the reflog for any branch:
+
+```ruby
+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]
+```
+
+---
+
+### Config files
+
+It's also easy to read and manipulate the Git config file data with Rugged.
+
+```ruby
+# Read values
+repo.config['core.bare']
+
+# Set values
+repo.config['user.name'] = true
+
+# Delete values
+repo.config.delete('user.name')
+```
+
+---
+
+### General methods
+
+Rugged also includes a general library for handling basic Git operations. One of
+these is converting a raw sha (20 bytes) into a readable hex sha (40
+characters).
+
+```ruby
+Rugged.hex_to_raw('bfde59cdd0dfac1d892814f66a95641abd8a1faf')
+# => "\277\336Y\315\320\337\254\035\211(\024\366j\225d\032\275\212\037\257"
+
+Rugged.raw_to_hex("\277\336Y\315\320\337\254\035\211(\024\366j\225d\032\275\212\037\257")
+=> "bfde59cdd0dfac1d892814f66a95641abd8a1faf"
+```
+
+---
+
+## Contributing
 
 Fork libgit2/rugged on GitHub, make it awesomer (preferably in a branch named
 for the topic), send a pull request.
 
 
-AUTHORS 
-==============
+## Development
 
-* Scott Chacon <schacon@gmail.com>
-* Vicent Marti <tanoku@gmail.com>
+First you need to install libgit2:
+
+    $ git clone https://github.com/libgit2/libgit2.git
+    $ cd libgit2
+    $ mkdir build && cd build
+    $ cmake ..
+    $ make
+    $ make install
 
+Now that those are installed, you can install Rugged:
+
+    $ git clone https://github.com/libgit2/rugged.git
+    $ cd rugged
+    $ bundle install
+    $ rake compile
+    $ rake test
+
+
+## Authors
+
+* Vicent Marti <tanoku@gmail.com>
+* Scott Chacon <schacon@gmail.com>
 
-LICENSE
-==============
 
-MIT.  See LICENSE file.
+## License
 
+MIT. See LICENSE file.

data/Rakefile

@@ -14,6 +14,17 @@ Rake::ExtensionTask.new('rugged') do |r|
   r.lib_dir = 'lib/rugged'
 end
 
+task :embedded_clean do
+  lib_path = File.expand_path '../ext/rugged/libgit2_embed.a', __FILE__
+  system "rm #{lib_path}"
+end
+Rake::Task[:clean].prerequisites << :embedded_clean
+
+desc "Open an irb session preloaded with Rugged"
+task :console do
+  sh "irb -rubygems -I lib -r ./lib/rugged"
+end
+
 #
 # Tests
 #
@@ -36,3 +47,14 @@ Rake::TestTask.new do |t|
   t.pattern = 'test/**/*_test.rb'
   t.verbose = false
 end
+
+begin
+  require 'rdoc/task'
+  Rake::RDocTask.new do |rdoc|
+      rdoc.rdoc_dir = 'rdoc'
+      rdoc.rdoc_files.include('ext/**/*.c')
+      rdoc.rdoc_files.include('lib/**/*.rb')
+  end
+rescue LoadError
+end
+

data/ext/rugged/extconf.rb

@@ -26,14 +26,17 @@ else
 
   LIBGIT2_DIST = 'libgit2-dist.tar.gz'
   LIBGIT2_DIR = File.basename(LIBGIT2_DIST, '.tar.gz')
+  LIBGIT2_LIB_PATH = "#{CWD}/libgit2_embed.a"
 
-  Dir.chdir("#{CWD}/vendor") do
-    FileUtils.rm_rf(LIBGIT2_DIR) if File.exists?(LIBGIT2_DIR)
+  if !File.exists?(LIBGIT2_LIB_PATH)
+    Dir.chdir("#{CWD}/vendor") do
+      FileUtils.rm_rf(LIBGIT2_DIR) if File.exists?(LIBGIT2_DIR)
 
-    sys("tar zxvf #{LIBGIT2_DIST}")
-    Dir.chdir(LIBGIT2_DIR) do
-      sys("make -f Makefile.embed")
-      FileUtils.cp "libgit2.a", "#{CWD}/libgit2_embed.a"
+      sys("tar zxvf #{LIBGIT2_DIST}")
+      Dir.chdir(LIBGIT2_DIR) do
+        sys("make -f Makefile.embed")
+        FileUtils.cp "libgit2.a", LIBGIT2_LIB_PATH
+      end
     end
   end