Permalink
Browse files

Docstrings for Branch

  • Loading branch information...
1 parent a771f15 commit 02b47e69294804e6d8d1790763e6f0c23da13590 @vmg vmg committed Aug 29, 2012
Showing with 97 additions and 2 deletions.
  1. +74 −0 ext/rugged/rugged_branch.c
  2. +1 −0 ext/rugged/rugged_config.c
  3. +10 −0 lib/rugged/branch.rb
  4. +12 −2 lib/rugged/repository.rb
View
@@ -52,6 +52,22 @@ static int parse_branch_type(VALUE rb_filter)
}
}
+/*
+ * call-seq:
+ * Branch.create(repository, name, target, force = false) -> branch
+ *
+ * Create a new branch in +repository+, with the given +name+, and pointing
+ * to the +target+.
+ *
+ * +name+ needs to be a branch name, not an absolute reference path
+ * (e.g. 'development' instead of '/refs/heads/development')
+ *
+ * +target+ needs to be an existing object (of any type) in the given +repository+.
+ *
+ * If +force+ is +true+, any existing branches will be overwritten.
+ *
+ * Returns a Rugged::Branch object with the newly created branch.
+ */
static VALUE rb_git_branch_create(int argc, VALUE *argv, VALUE self)
{
git_reference *branch;
@@ -85,6 +101,20 @@ static VALUE rb_git_branch_create(int argc, VALUE *argv, VALUE self)
return rugged_branch_new(rb_repo, branch);
}
+/*
+ * call-seq:
+ * Branch.lookup(repository, name, branch_type = :local) -> branch
+ *
+ * Lookup a branch in +repository+, with the given +name+.
+ *
+ * +name+ needs to be a branch name, not an absolute reference path
+ * (e.g. 'development' instead of '/refs/heads/development')
+ *
+ * +branch_type+ specifies whether the looked up branch is a local branch
+ * or a remote one. It defaults to looking up local branches.
+ *
+ * Returns the looked up branch, or +nil+ if the branch doesn't exist.
+ */
static VALUE rb_git_branch_lookup(int argc, VALUE *argv, VALUE self)
{
git_reference *branch;
@@ -116,6 +146,13 @@ static VALUE rb_git_branch_lookup(int argc, VALUE *argv, VALUE self)
return rugged_branch_new(rb_repo, branch);
}
+/*
+ * call-seq:
+ * branch.delete!
+ *
+ * Remove a branch from the repository. The branch object will become invalidated
+ * and won't be able to be used for any other operations.
+ */
static VALUE rb_git_branch_delete(VALUE self)
{
git_reference *branch = NULL;
@@ -187,16 +224,53 @@ static VALUE each_branch(int argc, VALUE *argv, VALUE self, int branch_names_onl
return Qnil;
}
+/*
+ * call-seq:
+ * Branch.each_name(repository, filter = :all) { |branch_name| block }
+ * Branch.each_name(repository, filter = :all) -> Iterator
+ *
+ * Iterate through the names of the branches in +repository+. Iteration can be
+ * optionally filtered to yield only +:local+ or +:remote+ branches.
+ *
+ * The given block will be called once with the name of each branch as a +String+.
+ * If no block is given, an iterator will be returned.
+ */
static VALUE rb_git_branch_each_name(int argc, VALUE *argv, VALUE self)
{
return each_branch(argc, argv, self, 1);
}
+
+/*
+ * call-seq:
+ * Branch.each(repository, filter = :all) { |branch| block }
+ * Branch.each(repository, filter = :all) -> Iterator
+ *
+ * Iterate through the branches in +repository+. Iteration can be
+ * optionally filtered to yield only +:local+ or +:remote+ branches.
+ *
+ * The given block will be called once with a +Rugged::Branch+ object
+ * for each branch in the repository. If no block is given, an iterator
+ * will be returned.
+ */
static VALUE rb_git_branch_each(int argc, VALUE *argv, VALUE self)
{
return each_branch(argc, argv, self, 0);
}
+/*
+ * call-seq:
+ * branch.move(new_name, force = false)
+ * branch.rename(new_name, force = false)
+ *
+ * Rename a branch to +new_name+.
+ *
+ * +new_name+ needs to be a branch name, not an absolute reference path
+ * (e.g. 'development' instead of '/refs/heads/development')
+ *
+ * If +force+ is +true+, the branch will be renamed even if a branch
+ * with +new_name+ already exists.
+ */
static VALUE rb_git_branch_move(int argc, VALUE *argv, VALUE self)
{
VALUE rb_new_branch_name, rb_force;
@@ -285,6 +285,7 @@ static VALUE rb_git_config_to_hash(VALUE self)
/*
* call-seq:
* Config.global() -> new_config
+ * Config.open_global() -> new_config
*
* Open the default global config file as a new +Rugged::Config+ object.
* An exception will be raised if the global config file doesn't
View
@@ -1,5 +1,7 @@
module Rugged
class Branch < Rugged::Reference
+
+ # The object pointed at by the tip of this branch
def tip
@owner.lookup(self.resolve.target)
end
@@ -9,8 +11,16 @@ def ==(other)
other.canonical_name == self.canonical_name
end
+ # The full name of the branch, as a fully-qualified reference
+ # path.
+ #
+ # This is the same as calling Reference#name for the reference behind
+ # the path
alias_method 'canonical_name', 'name'
+ # The name of the branch, without a fully-qualified reference path
+ #
+ # E.g. 'master' instead of 'refs/heads/master'
def name
super.gsub(%r{^(refs/heads/|refs/remotes/)}, '')
end
View
@@ -107,24 +107,34 @@ def ref_names
Rugged::Reference.each(self)
end
- # All of the tags in the repository.
+ # All the tags in the repository.
#
# Returns an Enumerable::Enumerator containing all the String tag names.
def tags(pattern="")
Rugged::Tag.each(self, pattern)
end
- # All of the remotes in the repository.
+ # All the remotes in the repository.
#
# Returns an Enumerable::Enumerator containing all the String remote names.
def remotes
Rugged::Remote.each(self)
end
+ # All the branches in the repository
+ #
+ # Returns an Enumerable::Enumerator containing Rugged::Branch objects
def branches
Rugged::Branch.each(self)
end
+ # Create a new branch in the repository
+ #
+ # name - The name of the branch (without a full reference path)
+ # sha_or_ref - The target of the branch; either a String representing
+ # an OID or a reference name, or a Rugged::Object instance.
+ #
+ # Returns a Rugged::Branch object
def create_branch(name, sha_or_ref = "HEAD")
case sha_or_ref
when Rugged::Object

0 comments on commit 02b47e6

Please sign in to comment.