Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

TomDoc #54

Merged
merged 1 commit into from

2 participants

@holman
Owner

Figured I'd start TomDoc'ing some of the more egregious files. Ruby doesn't even look like Ruby without it. Through doc'ing it I started finding some more edge cases that weren't covered by tests. Figured I'd start on those, too.

Probably will shoot through the whole codebase and do the rest of it when I get the time, too. I wonder what @mojombo would say about TomDoc'ing C-based files (where the methods won't actually be defined in that particular class file). Might be kind of nice to have docs for those methods in there regardless, perhaps.

@vmg vmg merged commit 40181a6 into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 23, 2012
  1. @holman

    repo docs

    holman authored
This page is out of date. Refresh to see the latest.
Showing with 124 additions and 8 deletions.
  1. +60 −7 lib/rugged/repository.rb
  2. +64 −1 test/repo_test.rb
View
67 lib/rugged/repository.rb
@@ -1,17 +1,30 @@
module Rugged
+ # Repository is an interface into a Git repository on-disk. It's the primary
+ # interface between your app and the main Git objects Rugged makes available
+ # to you.
class Repository
-
+ # Pretty formatting of a Repository.
+ #
+ # Returns a very pretty String.
def inspect
"#<Rugged::Repository:#{object_id} {path: #{path.inspect}}>"
end
- # Get the most recent commit from this repo
+ # Get the most recent commit from this repo.
#
- # Returns a Rugged::Commit object
+ # Returns a Rugged::Commit object.
def last_commit
self.lookup self.head.target
end
+ # Walks over a set of commits using Rugged::Walker.
+ #
+ # from - The String SHA1 to push onto Walker to begin our walk.
+ # sorting - The sorting order of the commits, as defined in the README.
+ # block - A block that we pass into walker#each.
+ #
+ # Returns nothing if called with a block, otherwise returns an instance of
+ # Enumerable::Enumerator containing Rugged::Commit objects.
def walk(from, sorting=Rugged::SORT_DATE, &block)
walker = Rugged::Walker.new(self)
walker.sorting(sorting)
@@ -19,20 +32,47 @@ def walk(from, sorting=Rugged::SORT_DATE, &block)
walker.each(&block)
end
+ # Find the HEAD of this repository.
+ #
+ # Returns a Reference.
def head
ref = Reference.lookup(self, "HEAD")
ref.resolve
end
+ # Look up a SHA1.
+ #
+ # Returns one of the four classes that inherit from Rugged::Object.
def lookup(oid)
Rugged::Object.lookup(self, oid)
end
- # Look up a single reference by name
+ # Look up a single reference by name.
+ #
+ # Example:
+ #
+ # repo.ref 'refs/heads/master'
+ # # => #<Rugged::Reference:2199125780 {name: "refs/heads/master",
+ # target: "25b5d3b40c4eadda8098172b26c68cf151109799"}>
+ #
+ # Returns a Rugged::Reference.
def ref(ref_name)
Rugged::Reference.lookup(self, ref_name)
end
+ # Retuns all the References that match a pattern.
+ #
+ # refs - A Regexp (or String) to search for. Optional.
+ #
+ # Examples:
+ #
+ # # All refs
+ # repo.refs
+ #
+ # # All remote refs
+ # repo.refs 'refs/remotes'
+ #
+ # Returns an Array of References.
def refs(pattern = nil)
r = []
ref_names.each do |ref_name|
@@ -46,18 +86,33 @@ def refs(pattern = nil)
r
end
+ # The names of all the refs.
+ #
+ # Returns an Enumerable::Enumerator containing all the String ref names.
def ref_names
Rugged::Reference.each(self)
end
+ # All of 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.
+ #
+ # Returns an Enumerable::Enumerator containing all the String remote names.
def remotes
Rugged::Remote.each(self)
end
+ # Get the content of a file at a specific revision.
+ #
+ # revision - The String SHA1.
+ # path - The String file path.
+ #
+ # Returns a String.
def file_at(revision, path)
tree = Rugged::Commit.lookup(self, revision).tree
subtree = tree.get_subtree(path)
@@ -65,7 +120,5 @@ def file_at(revision, path)
blob = Rugged::Blob.lookup(self, blob_data[:oid])
blob.content
end
-
end
-
-end
+end
View
65 test/repo_test.rb
@@ -58,19 +58,82 @@
rm_loose(oid)
end
- test "can use the builtin walk method" do
+ test "can walk in a block" do
oid = "a4a7dce85cf63874e984719f4fdd239f5145052f"
list = []
@repo.walk(oid) { |c| list << c }
assert list.map {|c| c.oid[0,5] }.join('.'), "a4a7d.c4780.9fd73.4a202.5b5b0.84960"
end
+ test "can walk without a block" do
+ commits = @repo.walk('a4a7dce85cf63874e984719f4fdd239f5145052f')
+
+ assert commits.kind_of?(Enumerable)
+ assert commits.count > 0
+ end
+
+ test "can lookup an object" do
+ object = @repo.lookup("8496071c1b46c854b31185ea97743be6a8774479")
+
+ assert object.kind_of?(Rugged::Commit)
+ end
+
+ test "can find a ref" do
+ ref = @repo.ref('refs/heads/master')
+
+ assert ref.kind_of?(Rugged::Reference)
+ assert_equal 'refs/heads/master', ref.name
+ end
+
+ test "can return all refs" do
+ refs = @repo.refs
+
+ assert_equal 4, refs.length
+ end
+
+ test "can return all refs that match" do
+ refs = @repo.refs 'refs/heads'
+
+ assert_equal 2, refs.length
+ end
+
+ test "can return the names of all refs" do
+ refs = @repo.ref_names
+
+ refs.each {|name| assert name.kind_of?(String)}
+ assert_equal 4, refs.count
+ end
+
+ test "can return all tags" do
+ tags = @repo.tags
+
+ assert_equal 2, tags.count
+ end
+
+ test "can return all tags that match" do
+ tags = @repo.tags 'v0.9'
+
+ assert_equal 1, tags.count
+ end
+
+ test "can return all remotes" do
+ remotes = @repo.remotes
+
+ assert_equal 1, remotes.count
+ end
+
test "can lookup head from repo" do
head = @repo.head
assert_equal "36060c58702ed4c2a40832c51758d5344201d89a", head.target
assert_equal :direct, head.type
end
+ test "can access a file" do
+ sha = '36060c58702ed4c2a40832c51758d5344201d89a'
+ content = @repo.file_at(sha, 'new.txt')
+ assert_equal "new file\n", content
+ end
+
test "garbage collection methods don't crash" do
Rugged::Repository.new(@path)
ObjectSpace.garbage_collect
Something went wrong with that request. Please try again.