Merge pull request libgit2#307 from libgit2/arthur/collections

Introduce Collections

README.md

@@ -317,49 +317,51 @@ index.add(path)
 
 ### Refs
 
-The `Rugged::Reference` class allows you to list, create and delete packed and loose refs.
+You can access references through the `Rugged::ReferenceCollection` object returned by `Repository#references`.
 
 ```ruby
-ref = repo.head # or...
-ref = Rugged::Reference.lookup(repo, "refs/heads/master")
+ref = repo.references["refs/heads/master"]
 
-sha = ref.target
+sha = ref.target_id
 str = ref.type   # :direct
 str = ref.name   # "refs/heads/master"
 ```
 
-You can also easily get an array of references:
+You can also easily iterate over all references:
 
 ```ruby
-repo.refs.each do |ref|
+repo.references.each do |ref|
   puts ref.name
 end
 ```
 
-Or use a pattern (regex):
+Or only over references that match the given pattern (glob):
 
 ```ruby
-repo.refs(/tags/).each do |ref|
+repo.references.each("refs/tags/*") 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 = repo.references.create("refs/heads/unit_test", some_commit_sha)
 
-ref.set_target(new_sha)
+repo.references.update(ref, new_sha) # or...
+repo.references.update("refs/heads/unit_test", new_sha)
 
-ref.rename("refs/heads/blead")
+repo.references.rename(ref, "refs/heads/blead") # or...
+repo.references.rename("refs/heads/unit_test", "refs/heads/blead")
 
-ref.delete!
+repo.references.delete(ref) # or...
+repo.references.delete("refs/heads/unit_test") # or...
 ```
 
 Finally, you can access the reflog for any branch:
 
 ```ruby
-ref = Rugged::Reference.lookup(repo, "refs/heads/master")
+ref = repo.references["refs/heads/master"]
 entry = ref.log.first
 sha   = entry[:id_old]
 sha   = entry[:id_new]
@@ -371,42 +373,49 @@ prsn  = entry[:committer]
 
 ### Branches
 
-`Rugged::Branch` will help you with all of your branch-related needs.
+The `Rugged::BranchCollection` object returned by `Repository#branches` will help
+you with all of your branch-related needs.
 
 Iterate over all branches:
 
 ```ruby
-Rugged::Branch.each_name(repo).sort
+repo.branches.each_name().sort
 # => ["master", "origin/HEAD", "origin/master", "origin/packed"]
 
-Rugged::Branch.each_name(repo, :local).sort
+repo.branches.each_name(:local).sort
 # => ["master"]
 
-Rugged::Branch.each_name(repo, :remote).sort
+Rugged::Branch.each_name(:remote).sort
 # => ["origin/HEAD", "origin/master", "origin/packed"]
 ```
 
 Look up branches and get attributes:
 
 ```ruby
-branch = Rugged::Branch.lookup(repo, "master")
+branch = repo.branches["master"]
 branch.name # => 'master'
 branch.canonical_name # => 'refs/heads/master'
 ```
 
-Look up the oid for the tip of a branch:
+Look up the id for the target of a branch:
 
 ```ruby
-Rugged::Branch.lookup(repo, "master").tip.oid
+repo.branches["master"].target_id
 # => "36060c58702ed4c2a40832c51758d5344201d89a"
 ```
 
 Creation and deletion:
 
 ```ruby
-branch = repo.create_branch("test_branch")
-branch.move("new_branch")
-branch.delete!
+branch = repo.branches.create("test_branch", "HEAD")
+
+repo.branches.rename("test_branch", "new_branch") # or...
+repo.branches.rename("refs/heads/test_branch", "new_branch") # or...
+repo.branches.rename(ref, "new_branch") # or...
+
+repo.branches.delete("test_branch") # or...
+repo.branches.delete("refs/heads/test_branch") # or...
+repo.branches.delete(ref) # or...
 ```
 
 ---

ext/rugged/rugged.c

@@ -384,17 +384,21 @@ void Init_rugged(void)
 	rb_define_module_function(rb_mRugged, "prettify_message", rb_git_prettify_message, 2);
 	rb_define_module_function(rb_mRugged, "__cache_usage__", rb_git_cache_usage, 0);
 
+	Init_rugged_reference();
+	Init_rugged_reference_collection();
+
 	Init_rugged_object();
 	Init_rugged_commit();
 	Init_rugged_tree();
 	Init_rugged_tag();
+	Init_rugged_tag_collection();
 	Init_rugged_blob();
 
 	Init_rugged_index();
 	Init_rugged_repo();
 	Init_rugged_revwalk();
-	Init_rugged_reference();
 	Init_rugged_branch();
+	Init_rugged_branch_collection();
 	Init_rugged_config();
 	Init_rugged_remote();
 	Init_rugged_notes();

ext/rugged/rugged.h

@@ -49,14 +49,17 @@
  */
 void Init_rugged_object(void);
 void Init_rugged_branch(void);
+void Init_rugged_branch_collection(void);
 void Init_rugged_commit(void);
 void Init_rugged_tree(void);
 void Init_rugged_tag(void);
+void Init_rugged_tag_collection(void);
 void Init_rugged_blob(void);
 void Init_rugged_index(void);
 void Init_rugged_repo(void);
 void Init_rugged_revwalk(void);
 void Init_rugged_reference(void);
+void Init_rugged_reference_collection(void);
 void Init_rugged_config(void);
 void Init_rugged_remote(void);
 void Init_rugged_notes(void);