rugged 0.18.0.gh.de28323 → 0.19.0

data/ext/rugged/rugged_blob.c

@@ -28,31 +28,26 @@
 extern VALUE rb_mRugged;
 extern VALUE rb_cRuggedObject;
 extern VALUE rb_cRuggedRepo;
+static ID id_read;
 
 VALUE rb_cRuggedBlob;
 
 /*
- *	call-seq:
- *		blob.text(max_lines = -1, encoding = Encoding.default_external) -> String
+ *  call-seq:
+ *    blob.text(max_lines = -1, encoding = Encoding.default_external) -> string
  *
- *	Return up to +max_lines+ of text from a blob as a +String+.
+ *  Return up to +max_lines+ of text from a blob as a +String+.
+ *  If +max_lines+ is less than 0, the full string is returned.
  *
- *	In Ruby 1.9.x, the string is created with the given +encoding+,
- *	defaulting to Encoding.default_external.
+ *  The string is created with the given +encoding+, defaulting to
+ *  Encoding.default_external.
  *
- *	In previous versions, the +encoding+ argument is dummy and has no
- *	effect on the returned string.
- *
- *	When limiting the size of the text with +max_lines+, the string is
- *	expected to have an ASCII-compatible encoding, and is checked
- *	for the newline +\n+ character.
+ *  When limiting the size of the text with +max_lines+, the string is
+ *  expected to have an ASCII-compatible encoding, and is checked
+ *  for the newline +\n+ character.
  */
 static VALUE rb_git_blob_text_GET(int argc, VALUE *argv, VALUE self)
 {
-#ifdef HAVE_RUBY_ENCODING_H
-	rb_encoding *encoding = rb_default_external_encoding();
-#endif
-
 	git_blob *blob;
 	size_t size;
 	const char *content;
@@ -76,32 +71,27 @@ static VALUE rb_git_blob_text_GET(int argc, VALUE *argv, VALUE self)
 				if (content[i++] == '\n')
 					lines++;
 			}
+			size = (size_t)i;
 		}
 
-		size = (size_t)i;
 	}
 
-#ifdef HAVE_RUBY_ENCODING_H
 	if (!NIL_P(rb_encoding)) {
-		encoding = rb_to_encoding(rb_encoding);
+		return rb_enc_str_new(content, size, rb_to_encoding(rb_encoding));
 	}
-#endif
 
-	if (size == 0)
-		return rugged_str_new("", 0, encoding);
-
-	return rugged_str_new(content, size, encoding);
+	return rb_external_str_new(content, size);
 }
 
 /*
- *	call-seq:
- *		blob.content(max_bytes=-1) -> String
+ *  call-seq:
+ *    blob.content(max_bytes=-1) -> string
  *
- *	Return up to +max_bytes+ from the contents of a blob as bytes +String+.
- *	If max_bytes is less than 0, the full string is returned.
+ *  Return up to +max_bytes+ from the contents of a blob as bytes +String+.
+ *  If +max_bytes+ is less than 0, the full string is returned.
  *
- *	In Ruby 1.9.x, this string is tagged with the ASCII-8BIT encoding: the
- *	bytes are returned as-is, since Git is encoding agnostic.
+ *  This string is tagged with the ASCII-8BIT encoding: the bytes are
+ *  returned as-is, since Git is encoding agnostic.
  */
 static VALUE rb_git_blob_content_GET(int argc, VALUE *argv, VALUE self)
 {
@@ -126,28 +116,20 @@ static VALUE rb_git_blob_content_GET(int argc, VALUE *argv, VALUE self)
 			size = (size_t)maxbytes;
 	}
 
-	if (size == 0)
-		return rugged_str_ascii("", 0);
-
 	/*
 	 * since we don't really ever know the encoding of a blob
 	 * lets default to the binary encoding (ascii-8bit)
-	 * If there is a way to tell, we should just pass 0/null here instead
-	 *
-	 * we're skipping the use of STR_NEW because we don't want our string to
-	 * eventually end up converted to Encoding.default_internal because this
-	 * string could very well be binary data
 	 */
-	return rugged_str_ascii(content, size);
+	return rb_str_new(content, size);
 }
 
 /*
- *	call-seq:
- *		blob.rawsize -> int
+ *  call-seq:
+ *    blob.rawsize -> int
  *
- *	Return the size in bytes of the blob. This is the real,
- *	uncompressed size and the length of +blob.content+, not
- *	the compressed size.
+ *  Return the size in bytes of the blob. This is the real,
+ *  uncompressed size and the length of +blob.content+, not
+ *  the compressed size.
  */
 static VALUE rb_git_blob_rawsize(VALUE self)
 {
@@ -158,14 +140,14 @@ static VALUE rb_git_blob_rawsize(VALUE self)
 }
 
 /*
- *	call-seq:
- *		Blob.create(repository, bytes) -> oid
+ *  call-seq:
+ *    Blob.from_buffer(repository, bytes) -> oid
  *
- *	Write a blob to +repository+ with the contents specified
- *	in +buffer+. In Ruby 1.9.x, the encoding of +buffer+ is
- *	ignored and bytes are copied as-is.
+ *  Write a blob to +repository+ with the contents specified
+ *  in +buffer+. In Ruby 1.9.x, the encoding of +buffer+ is
+ *  ignored and bytes are copied as-is.
  */
-static VALUE rb_git_blob_create(VALUE self, VALUE rb_repo, VALUE rb_buffer)
+static VALUE rb_git_blob_from_buffer(VALUE self, VALUE rb_repo, VALUE rb_buffer)
 {
 	int error;
 	git_oid oid;
@@ -183,13 +165,14 @@ static VALUE rb_git_blob_create(VALUE self, VALUE rb_repo, VALUE rb_buffer)
 }
 
 /*
- *	call-seq:
- *		Blob.from_workdir(repository, file_path) -> oid
+ *  call-seq:
+ *    Blob.from_workdir(repository, file_path) -> oid
  *
- *	Write the file specified in +file_path+ to a blob in +repository+.
- *	+file_path+ must be relative to the repository's working folder.
+ *  Write the file specified in +file_path+ to a blob in +repository+.
+ *  +file_path+ must be relative to the repository's working folder.
+ *  The repository cannot be bare.
  *
- *		Blob.from_workdir(repo, 'src/blob.h') #=> '9d09060c850defbc7711d08b57def0d14e742f4e'
+ *    Blob.from_workdir(repo, 'src/blob.h') #=> '9d09060c850defbc7711d08b57def0d14e742f4e'
  */
 static VALUE rb_git_blob_from_workdir(VALUE self, VALUE rb_repo, VALUE rb_path)
 {
@@ -209,11 +192,127 @@ static VALUE rb_git_blob_from_workdir(VALUE self, VALUE rb_repo, VALUE rb_path)
 }
 
 /*
- *	call-seq:
- *		blob.sloc -> Integer
+ *  call-seq:
+ *    Blob.from_disk(repository, file_path) -> oid
+ *
+ *  Write the file specified in +file_path+ to a blob in +repository+.
+ *  The repository can be bare or not.
+ *
+ *  Example:
+ *
+ *    Blob.from_disk(repo, '/var/repos/blob.h') #=> '5b5b025afb0b4c913b4c338a42934a3863bf3643'
+ */
+static VALUE rb_git_blob_from_disk(VALUE self, VALUE rb_repo, VALUE rb_path)
+{
+	int error;
+	git_oid oid;
+	git_repository *repo;
+
+	Check_Type(rb_path, T_STRING);
+	rugged_check_repo(rb_repo);
+
+	Data_Get_Struct(rb_repo, git_repository, repo);
+
+	error = git_blob_create_fromdisk(&oid, repo, StringValueCStr(rb_path));
+	rugged_exception_check(error);
+
+	return rugged_create_oid(&oid);
+}
+
+static VALUE rb_read_check(VALUE *args) {
+	return rb_funcall(args[0], id_read, 1, args[1]);
+}
+
+static VALUE rb_read_failed(void) {
+	return Qnil;
+}
+
+static int cb_blob__get__chunk(char *content, size_t max_length, void *rb_io)
+{
+	VALUE rb_buffer, args[2];
+	size_t str_len, safe_len;
+
+	args[0] = (VALUE)rb_io;
+	args[1] = INT2FIX(max_length);
+
+	rb_buffer = rb_rescue(rb_read_check, (VALUE)args, rb_read_failed, 0);
+
+	if (NIL_P(rb_buffer) || TYPE(rb_buffer) != T_STRING )
+		return 0;
+
+	str_len = (size_t)RSTRING_LEN(rb_buffer);
+	safe_len = str_len > max_length ? max_length : str_len;
+	memcpy(content, StringValuePtr(rb_buffer), safe_len);
+
+	return (int)safe_len;
+}
+
+/*
+ *  call-seq:
+ *    Blob.from_chunks(repository, io [, hint_path]) -> oid
+ *
+ *  Write a loose blob to the +repository+ from a provider
+ *  of chunks of data.
+ *
+ *  The repository can be bare or not.
+ *
+ *  The data provider +io+ should respond to a <code>read(size)</code>
+ *  method. Generally any instance of a class based on Ruby's +IO+ class
+ *  should work(ex. +File+). On each +read+ call it should
+ *  return a +String+ with maximum size of +size+.
+ *
+ *  *NOTE:* If an exception is raised in the +io+ object's
+ *  +read+ method, a blob will be created with the data up to that point
+ *  and the exception will be rescued.
+ *  It's recommended to compare the +blob.size+ with the expected data size
+ *  to check if all the data was written.
+ *
+ *  Provided the +hint_path+ parameter is given, its value
+ *  will help to determine what git filters should be applied
+ *  to the object before it can be placed to the object database.
+ *
+ *    File.open('/path/to/file') do |file|
+ *      Blob.from_chunks(repo, file, 'hint/blob.h') #=> '42cab3c0cde61e2b5a2392e1eadbeffa20ffa171'
+ *    end
+ */
+static VALUE rb_git_blob_from_chunks(int argc, VALUE *argv, VALUE klass)
+{
+	VALUE rb_repo, rb_io, rb_hint_path;
+	const char * hint_path = NULL;
+
+	int error;
+	git_oid oid;
+	git_repository *repo;
+
+	rb_scan_args(argc, argv, "21", &rb_repo, &rb_io, &rb_hint_path);
+
+	rugged_check_repo(rb_repo);
+	Data_Get_Struct(rb_repo, git_repository, repo);
+
+	if (!NIL_P(rb_hint_path)) {
+		Check_Type(rb_hint_path, T_STRING);
+		hint_path = StringValueCStr(rb_hint_path);
+	}
+
+	error = git_blob_create_fromchunks(
+			&oid,
+			repo,
+			hint_path,
+			cb_blob__get__chunk,
+			(void *)rb_io);
+
+	rugged_exception_check(error);
+
+	return rugged_create_oid(&oid);
+}
+
+
+/*
+ *  call-seq:
+ *    blob.sloc -> int
  *
- *	Return the number of non-empty code lines for the blob,
- *	assuming the blob is plaintext (i.e. not binary)
+ *  Return the number of non-empty code lines for the blob,
+ *  assuming the blob is plaintext (i.e. not binary)
  */
 static VALUE rb_git_blob_sloc(VALUE self)
 {
@@ -247,15 +346,144 @@ static VALUE rb_git_blob_sloc(VALUE self)
 	return INT2FIX(sloc);
 }
 
-void Init_rugged_blob()
+/*
+ *  call-seq:
+ *    blob.binary? -> true or false
+ *
+ *  Determine if the blob content is most certainly binary or not.
+ *
+ *  The heuristic used to guess if a file is binary is taken from core git:
+ *  Searching for NUL bytes and looking for a reasonable ratio of printable
+ *  to non-printable characters among the first 4000 bytes.
+ *
+ */
+static VALUE rb_git_blob_is_binary(VALUE self)
 {
+	git_blob *blob;
+	Data_Get_Struct(self, git_blob, blob);
+	return git_blob_is_binary(blob) ? Qtrue : Qfalse;
+}
+
+/*
+ *  call-seq:
+ *    blob.diff(other, options = {}) -> patch
+ *
+ *  Directly generate a Rugged::Patch from the difference between +blob+ and +other+.
+ *
+ *  +other+ can either be another Rugged::Blob instance, a string,
+ *  or nil (treated as an empty blob).
+ *
+ *  The following options can be passed in the +options+ Hash:
+ *
+ *  :max_size ::
+ *    An integer specifying the maximum byte size of a blob before a it will
+ *    be treated as binary. The default value is 512MB.
+ *
+ *  :context_lines ::
+ *    The number of unchanged lines that define the boundary of a hunk (and
+ *    to display before and after the actual changes). The default is 3.
+ *
+ *  :interhunk_lines ::
+ *    The maximum number of unchanged lines between hunk boundaries before the hunks
+ *    will be merged into a one. The default is 0.
+ *
+ *  :reverse ::
+ *    If true, the sides of the diff will be reversed.
+ *
+ *  :force_text ::
+ *    If true, all files will be treated as text, disabling binary attributes & detection.
+ *
+ *  :ignore_whitespace ::
+ *    If true, all whitespace will be ignored.
+ *
+ *  :ignore_whitespace_change ::
+ *    If true, changes in amount of whitespace will be ignored.
+ *
+ *  :ignore_whitespace_eol ::
+ *    If true, whitespace at end of line will be ignored.
+ *
+ *  :patience ::
+ *    If true, the "patience diff" algorithm will be used (currently unimplemented).
+ *
+ *  :skip_binary_check ::
+ *    If true, diff deltas will be generated without spending time on binary
+ *    detection. This is useful to improve performance in cases where the actual
+ *    file content difference is not needed.
+ *
+ *  :old_path ::
+ *    An optional string to treat +blob+ as if it had this filename.
+ *
+ *  :new_path ::
+ *    An optional string to treat +other+ as if it had this filename.
+ */
+static VALUE rb_git_blob_diff(int argc, VALUE *argv, VALUE self)
+{
+	git_blob *blob;
+	git_diff_options opts = GIT_DIFF_OPTIONS_INIT;
+	git_diff_patch *patch;
+	const char *old_path = NULL, *new_path = NULL;
+	VALUE rb_other, rb_options;
+	int error;
+
+	rb_scan_args(argc, argv, "10:", &rb_other, &rb_options);
+	if (!NIL_P(rb_options)) {
+		VALUE rb_value;
+
+		rb_value = rb_hash_aref(rb_options, CSTR2SYM("old_path"));
+		if (!NIL_P(rb_value)) {
+			Check_Type(rb_value, T_STRING);
+			old_path = StringValueCStr(rb_value);
+		}
+
+		rb_value = rb_hash_aref(rb_options, CSTR2SYM("new_path"));
+		if (!NIL_P(rb_value)) {
+			Check_Type(rb_value, T_STRING);
+			new_path = StringValueCStr(rb_value);
+		}
+
+		rugged_parse_diff_options(&opts, rb_options);
+	}
+
+	Data_Get_Struct(self, git_blob, blob);
+
+	if (NIL_P(rb_other)) {
+		error = git_diff_patch_from_blobs(&patch, blob, old_path, NULL, new_path, &opts);
+	} else if (rb_obj_is_kind_of(rb_other, rb_cRuggedBlob)) {
+		git_blob *other_blob;
+
+		Data_Get_Struct(rb_other, git_blob, other_blob);
+
+		error = git_diff_patch_from_blobs(&patch, blob, old_path, other_blob, new_path, &opts);
+	} else if (TYPE(rb_other) == T_STRING) {
+		const char * buffer = StringValueCStr(rb_other);
+
+		error = git_diff_patch_from_blob_and_buffer(&patch, blob, old_path, buffer, RSTRING_LEN(rb_other), new_path, &opts);
+	} else {
+		rb_raise(rb_eTypeError, "wrong argument type %s (expected Rugged::Blob, String, or nil)",
+			rb_obj_classname(rb_other));
+	}
+
+	rugged_exception_check(error);
+
+	return rugged_diff_patch_new(self, patch);
+}
+
+void Init_rugged_blob(void)
+{
+	id_read = rb_intern("read");
+
 	rb_cRuggedBlob = rb_define_class_under(rb_mRugged, "Blob", rb_cRuggedObject);
 
 	rb_define_method(rb_cRuggedBlob, "size", rb_git_blob_rawsize, 0);
 	rb_define_method(rb_cRuggedBlob, "content", rb_git_blob_content_GET, -1);
 	rb_define_method(rb_cRuggedBlob, "text", rb_git_blob_text_GET, -1);
 	rb_define_method(rb_cRuggedBlob, "sloc", rb_git_blob_sloc, 0);
+	rb_define_method(rb_cRuggedBlob, "binary?", rb_git_blob_is_binary, 0);
+	rb_define_method(rb_cRuggedBlob, "diff", rb_git_blob_diff, -1);
 
-	rb_define_singleton_method(rb_cRuggedBlob, "create", rb_git_blob_create, 2);
+	rb_define_singleton_method(rb_cRuggedBlob, "from_buffer", rb_git_blob_from_buffer, 2);
 	rb_define_singleton_method(rb_cRuggedBlob, "from_workdir", rb_git_blob_from_workdir, 2);
+	rb_define_singleton_method(rb_cRuggedBlob, "from_disk", rb_git_blob_from_disk, 2);
+	rb_define_singleton_method(rb_cRuggedBlob, "from_chunks", rb_git_blob_from_chunks, -1);
+
 }

data/ext/rugged/rugged_branch.c

@@ -53,20 +53,20 @@ static int parse_branch_type(VALUE rb_filter)
 }
 
 /*
- *	call-seq:
- *		Branch.create(repository, name, target, force = false) -> branch
+ *  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+.
+ *  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')
+ *  +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 commit in the given +repository+.
+ *  +target+ needs to be an existing commit in the given +repository+.
  *
- *	If +force+ is +true+, any existing branches will be overwritten.
+ *  If +force+ is +true+, any existing branches will be overwritten.
  *
- *	Returns a Rugged::Branch object with the newly created branch.
+ *  Returns a Rugged::Branch object with the newly created branch.
  */
 static VALUE rb_git_branch_create(int argc, VALUE *argv, VALUE self)
 {
@@ -102,18 +102,18 @@ static VALUE rb_git_branch_create(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *	call-seq:
- *		Branch.lookup(repository, name, branch_type = :local) -> branch
+ *  call-seq:
+ *    Branch.lookup(repository, name, branch_type = :local) -> branch
  *
- *	Lookup a branch in +repository+, with the given +name+.
+ *  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')
+ *  +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.
+ *  +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.
+ *  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)
 {
@@ -133,7 +133,7 @@ static VALUE rb_git_branch_lookup(int argc, VALUE *argv, VALUE self)
 	Data_Get_Struct(rb_repo, git_repository, repo);
 
 	Check_Type(rb_name, T_STRING);
-	
+
 	if (!NIL_P(rb_type))
 		branch_type = parse_branch_type(rb_type);
 
@@ -146,11 +146,11 @@ static VALUE rb_git_branch_lookup(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *	call-seq:
- *		branch.delete!
+ *  call-seq:
+ *    branch.delete! -> nil
  *
- *	Remove a branch from the repository. The branch object will become invalidated
- *	and won't be able to be used for any other operations.
+ *  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)
 {
@@ -165,27 +165,29 @@ static VALUE rb_git_branch_delete(VALUE self)
 	return Qnil;
 }
 
-static int cb_branch__each_name(const char *branch_name, git_branch_t branch_type, void *payload)
+static int cb_branch__each_name(const char *branch_name, git_branch_t branch_type, void *data)
 {
-	rb_yield(rugged_str_new2(branch_name, rb_utf8_encoding()));
-	return GIT_OK;
+	struct rugged_cb_payload *payload = data;
+
+	rb_protect(rb_yield, rb_str_new_utf8(branch_name), &payload->exception);
+
+	return payload->exception ? GIT_ERROR : GIT_OK;
 }
 
-static int cb_branch__each_obj(const char *branch_name, git_branch_t branch_type, void *payload)
+static int cb_branch__each_obj(const char *branch_name, git_branch_t branch_type, void *data)
 {
-	VALUE rb_repo = (VALUE)payload;
-
 	git_reference *branch;
 	git_repository *repo;
+	struct rugged_cb_payload *payload = data;
 
-	Data_Get_Struct(rb_repo, git_repository, repo);
+	Data_Get_Struct(payload->rb_data, git_repository, repo);
 
 	rugged_exception_check(
 		git_branch_lookup(&branch, repo, branch_name, branch_type)
 	);
 
-	rb_yield(rugged_branch_new(rb_repo, branch));
-	return 0;
+	rb_protect(rb_yield, rugged_branch_new(payload->rb_data, branch), &payload->exception);
+	return payload->exception ? GIT_ERROR : GIT_OK;
 }
 
 static VALUE each_branch(int argc, VALUE *argv, VALUE self, int branch_names_only)
@@ -193,10 +195,14 @@ static VALUE each_branch(int argc, VALUE *argv, VALUE self, int branch_names_onl
 	VALUE rb_repo, rb_filter;
 	git_repository *repo;
 	int error;
+	struct rugged_cb_payload payload;
 	int filter = (GIT_BRANCH_LOCAL | GIT_BRANCH_REMOTE);
 
 	rb_scan_args(argc, argv, "11", &rb_repo, &rb_filter);
 
+	payload.exception = 0;
+	payload.rb_data = rb_repo;
+
 	if (!rb_block_given_p()) {
 		VALUE symbol = branch_names_only ? CSTR2SYM("each_name") : CSTR2SYM("each");
 		return rb_funcall(self, rb_intern("to_enum"), 3, symbol, rb_repo, rb_filter);
@@ -212,25 +218,28 @@ static VALUE each_branch(int argc, VALUE *argv, VALUE self, int branch_names_onl
 	Data_Get_Struct(rb_repo, git_repository, repo);
 
 	if (branch_names_only) {
-		error = git_branch_foreach(repo, filter, &cb_branch__each_name, NULL);
+		error = git_branch_foreach(repo, filter, &cb_branch__each_name, &payload);
 	} else {
-		error = git_branch_foreach(repo, filter, &cb_branch__each_obj, (void *)rb_repo);
+		error = git_branch_foreach(repo, filter, &cb_branch__each_obj, &payload);
 	}
 
+	if (payload.exception)
+		rb_jump_tag(payload.exception);
 	rugged_exception_check(error);
+
 	return Qnil;
 }
 
 /*
- *	call-seq:
- *		Branch.each_name(repository, filter = :all) { |branch_name| block }
- *		Branch.each_name(repository, filter = :all) -> Iterator
+ *  call-seq:
+ *    Branch.each_name(repository, filter = :all) { |branch_name| block }
+ *    Branch.each_name(repository, filter = :all) -> enumerator
  *
- *	Iterate through the names of the branches in +repository+. Iteration can be
- *	optionally filtered to yield only +:local+ or +:remote+ branches.
+ *  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.
+ *  The given block will be called once with the name of each branch as a +String+.
+ *  If no block is given, an enumerator will be returned.
  */
 static VALUE rb_git_branch_each_name(int argc, VALUE *argv, VALUE self)
 {
@@ -239,16 +248,16 @@ static VALUE rb_git_branch_each_name(int argc, VALUE *argv, VALUE self)
 
 
 /*
- *	call-seq:
- *		Branch.each(repository, filter = :all) { |branch| block }
- *		Branch.each(repository, filter = :all) -> Iterator
+ *  call-seq:
+ *    Branch.each(repository, filter = :all) { |branch| block }
+ *    Branch.each(repository, filter = :all) -> enumerator
  *
- *	Iterate through the branches in +repository+. Iteration can be
- *	optionally filtered to yield only +:local+ or +:remote+ branches.
+ *  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.
+ *  The given block will be called once with a +Rugged::Branch+ object
+ *  for each branch in the repository. If no block is given, an enumerator
+ *  will be returned.
  */
 static VALUE rb_git_branch_each(int argc, VALUE *argv, VALUE self)
 {
@@ -256,17 +265,19 @@ static VALUE rb_git_branch_each(int argc, VALUE *argv, VALUE self)
 }
 
 /*
- *	call-seq:
- *		branch.move(new_name, force = false)
- *		branch.rename(new_name, force = false)
+ *  call-seq:
+ *    branch.move(new_name, force = false) -> new_branch
+ *    branch.rename(new_name, force = false) -> new_branch
+ *
+ *  Rename a branch to +new_name+.
  *
- *	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+).
  *
- *	+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.
  *
- *	If +force+ is +true+, the branch will be renamed even if a branch
- *	with +new_name+ already exists.
+ *  A new Rugged::Branch object for the renamed branch will be returned.
  */
 static VALUE rb_git_branch_move(int argc, VALUE *argv, VALUE self)
 {
@@ -288,7 +299,20 @@ static VALUE rb_git_branch_move(int argc, VALUE *argv, VALUE self)
 	return rugged_branch_new(rugged_owner(self), new_branch);
 }
 
-void Init_rugged_branch()
+/*
+ *  call-seq:
+ *    branch.head? -> true or false
+ *
+ *  Returns +true+ if the branch is pointed at by +HEAD+, +false+ otherwise.
+ */
+static VALUE rb_git_branch_head_p(VALUE self)
+{
+	git_reference *branch;
+	Data_Get_Struct(self, git_reference, branch);
+	return git_branch_is_head(branch) ? Qtrue : Qfalse;
+}
+
+void Init_rugged_branch(void)
 {
 	rb_cRuggedBranch = rb_define_class_under(rb_mRugged, "Branch", rb_cRuggedReference);
 
@@ -300,4 +324,5 @@ void Init_rugged_branch()
 	rb_define_method(rb_cRuggedBranch, "delete!", rb_git_branch_delete, 0);
 	rb_define_method(rb_cRuggedBranch, "rename", rb_git_branch_move, -1);
 	rb_define_method(rb_cRuggedBranch, "move", rb_git_branch_move, -1);
+	rb_define_method(rb_cRuggedBranch, "head?", rb_git_branch_head_p, 0);
 }