octokit 1.4.0 → 1.5.0

data/lib/octokit/client.rb

@@ -9,7 +9,6 @@ require 'octokit/client/downloads'
 require 'octokit/client/gists'
 require 'octokit/client/issues'
 require 'octokit/client/labels'
-require 'octokit/client/network'
 require 'octokit/client/milestones'
 require 'octokit/client/objects'
 require 'octokit/client/organizations'
@@ -17,7 +16,6 @@ require 'octokit/client/pub_sub_hubbub'
 require 'octokit/client/pub_sub_hubbub/service_hooks'
 require 'octokit/client/pulls'
 require 'octokit/client/repositories'
-require 'octokit/client/timelines'
 require 'octokit/client/users'
 require 'octokit/client/events'
 require 'octokit/client/authorizations'
@@ -43,7 +41,6 @@ module Octokit
     include Octokit::Client::Gists
     include Octokit::Client::Issues
     include Octokit::Client::Labels
-    include Octokit::Client::Network
     include Octokit::Client::Milestones
     include Octokit::Client::Objects
     include Octokit::Client::Organizations
@@ -51,7 +48,6 @@ module Octokit
     include Octokit::Client::PubSubHubbub
     include Octokit::Client::PubSubHubbub::ServiceHooks
     include Octokit::Client::Repositories
-    include Octokit::Client::Timelines
     include Octokit::Client::Users
     include Octokit::Client::Events
     include Octokit::Client::Authorizations

data/lib/octokit/client/commits.rb

@@ -2,24 +2,82 @@ module Octokit
   class Client
     module Commits
 
-      def commits(repo, branch="master", options={})
-        options = { :per_page => 35, :sha => branch }.merge options
-        get("/repos/#{Repository.new(repo)}/commits", options, 3)
+      # List commits
+      #
+      # Optionally pass <tt>path => "path/to/file.rb"</tt> in <tt>options</tt> to
+      # only return commits containing the given file path.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param sha_or_branch [String] Commit SHA or branch name from which to start the list
+      # @return [Array] An array of hashes representing commits
+      # @see http://developer.github.com/v3/repos/commits/
+      def commits(repo, sha_or_branch="master", options={})
+        params = { :sha => sha_or_branch, :per_page => 35 }
+        get("/repos/#{Repository.new(repo)}/commits", options.merge(params), 3)
       end
       alias :list_commits :commits
 
+      # Get a single commit
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param sha [String] The SHA of the commit to fetch
+      # @return [Hashie::Mash] A hash representing the commit
+      # @see http://developer.github.com/v3/repos/commits/
       def commit(repo, sha, options={})
         get("/repos/#{Repository.new(repo)}/commits/#{sha}", options, 3)
       end
 
+      # Create a commit
+      #
+      # Optionally pass <tt>author</tt> and <tt>committer</tt> hashes in <tt>options</tt>
+      # if you'd like manual control over those parameters. If absent, details will be
+      # inferred from the authenticated user. See <a href="http://developer.github.com/v3/git/commits/">GitHub's documentation</a>
+      # for details about how to format committer identities.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param message [String] The commit message
+      # @param tree [String] The SHA of the tree object the new commit will point to
+      # @param parents [String, Array] One SHA (for a normal commit) or an array of SHAs (for a merge) of the new commit's parent commits. If ommitted or empty, a root commit will be created
+      # @return [Hashie::Mash] A hash representing the new commit
+      # @see http://developer.github.com/v3/git/commits/
+      # @example Create a commit
+      #   commit = Octokit.create_commit("octocat/Hello-World", "My commit message", "827efc6d56897b048c772eb4087f854f46256132", "7d1b31e74ee336d15cbd21741bc88a537ed063a0")
+      #   commit.sha # => "7638417db6d59f3c431d3e1f261cc637155684cd"
+      #   commit.tree.sha # => "827efc6d56897b048c772eb4087f854f46256132"
+      #   commit.message # => "My commit message"
+      #   commit.committer # => { "name" => "Wynn Netherland", "email" => "wynn@github.com", ... }
+      def create_commit(repo, message, tree, parents=nil, options={})
+        params = { :message => message, :tree => tree }.tap do |params|
+          params[:parents] = [parents].flatten if parents
+        end
+        post("/repos/#{Repository.new(repo)}/git/commits", options.merge(params), 3)
+      end
+
+      # List all commit comments
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @return [Array] An array of hashes representing comments
+      # @see http://developer.github.com/v3/repos/comments/
       def list_commit_comments(repo, options={})
         get("/repos/#{Repository.new(repo)}/comments", options, 3)
       end
 
+      # List comments for a single commit
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param sha [String] The SHA of the commit whose comments will be fetched
+      # @return [Array] An array of hashes representing comments
+      # @see http://developer.github.com/v3/repos/comments/
       def commit_comments(repo, sha, options={})
         get("/repos/#{Repository.new(repo)}/commits/#{sha}/comments", options, 3)
       end
 
+      # Get a single commit comment
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param id [String] The ID of the comment to fetch
+      # @return [Hashie::Mash] A hash representing the comment
+      # @see http://developer.github.com/v3/repos/comments/
       def commit_comment(repo, id, options={})
         get("/repos/#{Repository.new(repo)}/comments/#{id}", options, 3)
       end

data/lib/octokit/client/issues.rb

@@ -11,7 +11,6 @@ module Octokit
       # @see http://develop.github.com/p/issues.html
       # @example Search for 'test' in the open issues for sferik/rails_admin
       #   Octokit.search_issues("sferik/rails_admin", 'test', 'open')
-      # @deprecated Please use `list_issues` instead
       def search_issues(repo, search_term, state='open', options={})
         get("/legacy/issues/search/#{Repository.new(repo)}/#{state}/#{search_term}", options, 3)['issues']
       end

data/lib/octokit/client/objects.rb

@@ -1,34 +1,79 @@
 module Octokit
   class Client
     module Objects
+      # Get a single tree, fetching information about its root-level objects
+      #
+      # Pass <tt>:recursive => true</tt> in <tt>options</tt> to fetch information about all of the tree's objects, including those in subdirectories.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param tree_sha [String] The SHA of the tree to fetch
+      # @return [Hashie::Mash] A hash representing the fetched tree
+      # @see http://developer.github.com/v3/git/trees/
+      # @example Fetch a tree and inspect the path of one of its files
+      #   tree = Octokit.tree("octocat/Hello-World", "9fb037999f264ba9a7fc6274d15fa3ae2ab98312")
+      #   tree.tree.first.path # => "file.rb"
+      # @example Fetch a tree recursively
+      #   tree = Octokit.tree("octocat/Hello-World", "fc6274d15fa3ae2ab983129fb037999f264ba9a7")
+      #   tree.tree.first.path # => "subdir/file.txt"
       def tree(repo, tree_sha, options={})
         get("repos/#{Repository.new(repo)}/git/trees/#{tree_sha}", options)
       end
 
-      def blob(repo, tree_sha, options={})
-        get("repos/#{Repository.new(repo)}/git/blobs/#{tree_sha}", options)
+      # Create a tree
+      #
+      # Pass <tt>:base_tree => "827efc6..."</tt> in <tt>options</tt> to update an existing tree with new data.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param tree [Array] An array of hashes representing a tree structure
+      # @return [Hashie::Mash] A hash representing the new tree
+      # @see http://developer.github.com/v3/git/trees/
+      # @example Create a tree containing one file
+      #   tree = Octokit.create_tree("octocat/Hello-World", [ { :path => "file.rb", :mode => "100644", :type => "blob", :sha => "44b4fc6d56897b048c772eb4087f854f46256132" } ])
+      #   tree.sha # => "cd8274d15fa3ae2ab983129fb037999f264ba9a7"
+      #   tree.tree.first.path # => "file.rb"
+      def create_tree(repo, tree, options={})
+        parameters = { :tree => tree }
+        post("/repos/#{Repository.new(repo)}/git/trees", options.merge(parameters), 3)
       end
 
-      def blobs(repo, tree_sha, options={})
-        warn 'DEPRECATED: Please use Octokit.tree instead.'
-        get("/api/v2/json/blob/all/#{Repository.new(repo)}/#{tree_sha}", options, 2)['blobs']
+      # Get a single blob, fetching its content and encoding
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param blob_sha [String] The SHA of the blob to fetch
+      # @return [Hashie::Mash] A hash representing the fetched blob
+      # @see http://developer.github.com/v3/git/blobs/
+      # @example Fetch a blob and inspect its contents
+      #   blob = Octokit.blob("octocat/Hello-World", "827efc6d56897b048c772eb4087f854f46256132")
+      #   blob.encoding # => "utf-8"
+      #   blob.content # => "Foo bar baz"
+      # @example Fetch a base64-encoded blob and inspect its contents
+      #   require "base64"
+      #   blob = Octokit.blob("octocat/Hello-World", "827efc6d56897b048c772eb4087f854f46256132")
+      #   blob.encoding # => "base64"
+      #   blob.content # => "Rm9vIGJhciBiYXo="
+      #   Base64.decode64(blob.content) # => "Foo bar baz"
+      def blob(repo, blob_sha, options={})
+        get("repos/#{Repository.new(repo)}/git/blobs/#{blob_sha}", options)
       end
 
-      def blob_metadata(repo, tree_sha, options={})
-        warn 'DEPRECATED: Please use Octokit.blob instead.'
-        get("/api/v2/json/blob/full/#{Repository.new(repo)}/#{tree_sha}", options, 2)['blobs']
-      end
-      alias :blob_meta :blob_metadata
-
-      def tree_metadata(repo, tree_sha, options={})
-        warn 'DEPRECATED: Please use Octokit.tree instead.'
-        get("/api/v2/json/tree/full/#{Repository.new(repo)}/#{tree_sha}", options, 2)['tree']
-      end
-      alias :tree_meta :tree_metadata
-
-      def raw(repo, sha, options={})
-        warn 'DEPRECATED: Please use Octokit.blob instead.'
-        get("/api/v2/json/blob/show/#{Repository.new(repo)}/#{sha}", options, 2, true, true).body
+      # Create a blob
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository
+      # @param content [String] Content of the blob
+      # @param encoding [String] The content's encoding. <tt>utf-8</tt> and <tt>base64</tt> are accepted. If your data cannot be losslessly sent as a UTF-8 string, you can base64 encode it
+      # @return [String] The new blob's SHA, e.g. <tt>827efc6d56897b048c772eb4087f854f46256132</tt>
+      # @see http://developer.github.com/v3/git/blobs/
+      # @example Create a blob containing <tt>foo bar baz</tt>
+      #   Octokit.create_blob("octocat/Hello-World", "foo bar baz")
+      # @example Create a blob containing <tt>foo bar baz</tt>, encoded using base64
+      #   require "base64"
+      #   Octokit.create_blob("octocat/Hello-World", Base64.encode64("foo bar baz"), "base64")
+      def create_blob(repo, content, encoding="utf-8", options={})
+        parameters = {
+          :content => content,
+          :encoding => encoding
+        }
+        post("/repos/#{Repository.new(repo)}/git/blobs", options.merge(parameters), 3).sha
       end
     end
   end

data/lib/octokit/client/organizations.rb

@@ -23,12 +23,7 @@ module Octokit
       alias :orgs :organizations
 
       def organization_repositories(org=nil, options={})
-        if org.nil?
-          warn 'DEPRECATED: Please pass org name to list repos.'
-          get("/api/v2/json/organizations/repositories", options, 2)
-        else
-          get("orgs/#{org}/repos", options, 3)
-        end
+        get("orgs/#{org}/repos", options, 3)
       end
       alias :org_repositories :organization_repositories
       alias :org_repos :organization_repositories

data/lib/octokit/client/repositories.rb

@@ -90,11 +90,6 @@ module Octokit
       end
       alias :remove_collab :remove_collaborator
 
-      def pushable(options={})
-        # There isn't a matching method in V3 of the api
-        get("/api/v2/json/repos/pushable", options, 2)['repositories']
-      end
-
       def repository_teams(repo, options={})
         get "/repos/#{Repository.new repo}/teams", options, 3
       end

data/lib/octokit/client/users.rb

@@ -2,14 +2,8 @@ module Octokit
   class Client
     module Users
 
-      EMAIL_RE = /[\w.!#\$%+-]+@[\w-]+(?:\.[\w-]+)+/
       def search_users(search, options={})
-        if search.match(EMAIL_RE)
-          warn 'DEPRECATED: V3 of the API does not allow searching users by email'
-          get("/api/v2/json/user/email/#{search}", options, 2)['user']
-        else
-          get("/legacy/user/search/#{search}", options, 3)['users']
-        end
+        get("/legacy/user/search/#{search}", options, 3)['users']
       end
 
       # Get a single user

data/lib/octokit/version.rb

@@ -1,3 +1,3 @@
 module Octokit
-  VERSION = "1.4.0" unless defined?(Octokit::VERSION)
+  VERSION = "1.5.0" unless defined?(Octokit::VERSION)
 end

data/spec/fixtures/v3/blob_create.json

@@ -0,0 +1,3 @@
+{
+	"sha": "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15"
+}

data/spec/fixtures/v3/commit_create.json

@@ -0,0 +1,25 @@
+{
+  "sha": "7638417db6d59f3c431d3e1f261cc637155684cd",
+  "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7638417db6d59f3c431d3e1f261cc637155684cd",
+  "author": {
+    "date": "2012-06-06T16:13:30+12:00",
+    "name": "Wynn Netherland",
+    "email": "wynn@github.com"
+  },
+  "committer": {
+    "date": "2012-06-06T16:13:30+12:00",
+    "name": "Wynn Netherland",
+    "email": "wynn@github.com"
+  },
+  "message": "My commit message",
+  "tree": {
+    "url": "https://api.github.com/repos/octocat/Hello-World/git/trees/827efc6d56897b048c772eb4087f854f46256132",
+    "sha": "827efc6d56897b048c772eb4087f854f46256132"
+  },
+  "parents": [
+    {
+      "url": "https://api.github.com/repos/octocat/Hello-World/git/commits/7d1b31e74ee336d15cbd21741bc88a537ed063a0",
+      "sha": "7d1b31e74ee336d15cbd21741bc88a537ed063a0"
+    }
+  ]
+}

data/spec/fixtures/v3/tree_create.json

@@ -0,0 +1,14 @@
+{
+  "sha": "cd8274d15fa3ae2ab983129fb037999f264ba9a7",
+  "url": "https://api.github.com/repo/octocat/Hello-World/trees/cd8274d15fa3ae2ab983129fb037999f264ba9a7",
+  "tree": [
+    {
+      "path": "file.rb",
+      "mode": "100644",
+      "type": "blob",
+      "size": 132,
+      "sha": "7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b",
+      "url": "https://api.github.com/octocat/Hello-World/git/blobs/7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b"
+    }
+  ]
+}

data/spec/octokit/client/commits_spec.rb

@@ -29,6 +29,22 @@ describe Octokit::Client::Commits do
 
   end
 
+  describe ".create_commit" do
+    
+    it "should create a commit" do
+      stub_post("/repos/octocat/Hello-World/git/commits").
+        with(:body => { :message => "My commit message", :tree => "827efc6d56897b048c772eb4087f854f46256132", :parents => ["7d1b31e74ee336d15cbd21741bc88a537ed063a0"] },
+             :headers => { "Content-Type" => "application/json" }).
+        to_return(:body => fixture("v3/commit_create.json"))
+      commit = @client.create_commit("octocat/Hello-World", "My commit message", "827efc6d56897b048c772eb4087f854f46256132", "7d1b31e74ee336d15cbd21741bc88a537ed063a0")
+      commit.sha.should == "7638417db6d59f3c431d3e1f261cc637155684cd"
+      commit.message.should == "My commit message"
+      commit.parents.size.should == 1
+      commit.parents.first.sha.should == "7d1b31e74ee336d15cbd21741bc88a537ed063a0"
+    end
+
+  end
+
   describe ".list_commit_comments" do
 
     it "should return a list of all commit comments" do

data/spec/octokit/client/issues_spec.rb

@@ -11,7 +11,7 @@ describe Octokit::Client::Issues do
 
     it "should return matching issues" do
       stub_get("https://api.github.com/legacy/issues/search/sferik/rails_admin/open/activerecord").
-      to_return(:body => fixture("v2/issues.json"))
+      to_return(:body => fixture("legacy/issues.json"))
       issues = @client.search_issues("sferik/rails_admin", "activerecord")
       issues.first.number.should == 105
     end

data/spec/octokit/client/objects_spec.rb

@@ -19,6 +19,21 @@ describe Octokit::Client::Objects do
 
   end
 
+  describe ".create_tree" do
+
+    it "should create a tree" do
+      stub_post("/repos/octocat/Hello-World/git/trees").
+        with(:body => { :tree => [ { :path => "file.rb", "mode" => "100644", "type" => "blob", "sha" => "44b4fc6d56897b048c772eb4087f854f46256132" } ] },
+             :headers => { "Content-Type" => "application/json" }).
+        to_return(:body => fixture("v3/tree_create.json"))
+      response = @client.create_tree("octocat/Hello-World", [ { "path" => "file.rb", "mode" => "100644", "type" => "blob", "sha" => "44b4fc6d56897b048c772eb4087f854f46256132" } ])
+      response.sha.should == "cd8274d15fa3ae2ab983129fb037999f264ba9a7"
+      response.tree.size.should == 1
+      response.tree.first.sha.should == "7c258a9869f33c1e1e1f74fbb32f07c86cb5a75b"
+    end
+
+  end
+
   describe ".blob" do
 
     it "should return a blob" do
@@ -30,48 +45,15 @@ describe Octokit::Client::Objects do
 
   end
 
-  describe ".blobs" do
-
-    it "should return blobs" do
-      stub_get("https://github.com/api/v2/json/blob/all/sferik/rails_admin/3cdfabd973bc3caac209cba903cfdb3bf6636bcd").
-        to_return(:body => fixture("v2/blobs.json"))
-      blobs = @client.blobs("sferik/rails_admin", "3cdfabd973bc3caac209cba903cfdb3bf6636bcd")
-      blobs[".gitignore"].should == "5efe0eb47a773fa6ea84a0bf190ee218b6a31ead"
-    end
-
-  end
-
-  describe ".blob_metadata" do
-
-    it "should return blob metadata" do
-      stub_get("https://github.com/api/v2/json/blob/full/sferik/rails_admin/3cdfabd973bc3caac209cba903cfdb3bf6636bcd").
-        to_return(:body => fixture("v2/blob_metadata.json"))
-      blob_metadata = @client.blob_metadata("sferik/rails_admin", "3cdfabd973bc3caac209cba903cfdb3bf6636bcd")
-      blob_metadata.first.name.should == ".gitignore"
-    end
-
-  end
-
-  describe ".tree_metadata" do
-
-    it "should return tree metadata" do
-      stub_get("https://github.com/api/v2/json/tree/full/sferik/rails_admin/3cdfabd973bc3caac209cba903cfdb3bf6636bcd").
-        to_return(:body => fixture("v2/tree_metadata.json"))
-      tree_metadata = @client.tree_metadata("sferik/rails_admin", "3cdfabd973bc3caac209cba903cfdb3bf6636bcd")
-      tree_metadata.first.name.should == ".gitignore"
-    end
-
-  end
-
-  describe ".raw" do
+  describe ".create_blob" do
 
-    it "should return raw data" do
-      stub_get("https://github.com/api/v2/json/blob/show/sferik/rails_admin/3cdfabd973bc3caac209cba903cfdb3bf6636bcd").
-        to_return(:body => fixture("v2/raw.txt"))
-      raw = @client.raw("sferik/rails_admin", "3cdfabd973bc3caac209cba903cfdb3bf6636bcd")
-      lambda {
-        MultiJson.load(raw)
-      }.should raise_error
+    it "should create a blob" do
+      stub_post("/repos/octocat/Hello-World/git/blobs").
+        with(:body => { :content => "content", :encoding => "utf-8" },
+             :headers => { "Content-Type" => "application/json" }).
+        to_return(:body => fixture("v3/blob_create.json"))
+      blob = @client.create_blob("octocat/Hello-World", "content")
+      blob.should == "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15"
     end
 
   end

data/spec/octokit/client/organizations_spec.rb

@@ -58,26 +58,11 @@ describe Octokit::Client::Organizations do
 
   describe ".organization_repositories" do
 
-    context "with an org passed" do
-
-      it "should return all public repositories for an organization" do
-        stub_get("https://api.github.com/orgs/codeforamerica/repos").
-          to_return(:body => fixture("v3/organization-repositories.json"))
-        repositories = @client.organization_repositories("codeforamerica")
-        repositories.first.name.should == "cfahelloworld"
-      end
-
-    end
-
-    context "without an org passed" do
-
-      it "should return all organization repositories for a user" do
-        stub_get("https://github.com/api/v2/json/organizations/repositories").
-          to_return(:body => fixture("v2/repositories.json"))
-        repositories = @client.organization_repositories
-        repositories.repositories.first.name.should == "One40Proof"
-      end
-
+    it "should return all public repositories for an organization" do
+      stub_get("https://api.github.com/orgs/codeforamerica/repos").
+        to_return(:body => fixture("v3/organization-repositories.json"))
+      repositories = @client.organization_repositories("codeforamerica")
+      repositories.first.name.should == "cfahelloworld"
     end
 
   end