github_api 0.11.3 → 0.12.0

data/lib/github_api/client/git_data/commits.rb

@@ -0,0 +1,99 @@
+# encoding: utf-8
+
+module Github
+  class Client::GitData::Commits < API
+
+    VALID_COMMIT_PARAM_NAMES = %w[
+      message
+      tree
+      parents
+      author
+      committer
+      name
+      email
+      date
+    ].freeze
+
+    REQUIRED_COMMIT_PARAMS = %w[
+      message
+      tree
+      parents
+    ].freeze
+
+    # Get a commit
+    #
+    # @example
+    #   github = Github.new
+    #   github.git_data.commits.get 'user-name', 'repo-name', 'sha'
+    #
+    # @example
+    #   commits = Github::Commits.new user: 'user-name', repo: 'repo-name'
+    #   commits.get sha: '...'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :sha])
+      params = arguments.params
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/git/commits/#{arguments.sha}", params)
+    end
+    alias :find :get
+
+    # Create a commit
+    #
+    # @param [Hash] params
+    # @input params [String] :message
+    #   The commit message
+    # @input params [String] :tree
+    #   String of the SHA of the tree object this commit points to
+    # @input params [Array[String]] :parents
+    #   Array of the SHAs of the commits that were the parents of this commit.
+    #   If omitted or empty, the commit will be written as a root commit.
+    #   For a single parent, an array of one SHA should be provided,
+    #   for a merge commit, an array of more than one should be provided.
+    #
+    # Optional Parameters
+    #
+    # You can provide an additional commiter parameter, which is a hash
+    # containing information about the committer. Or, you can provide an author
+    # parameter, which is a hash containing information about the author.
+    #
+    # The committer section is optional and will be filled with the author
+    # data if omitted. If the author section is omitted, it will be filled
+    # in with the authenticated users information and the current date.
+    #
+    # Both the author and commiter parameters have the same keys:
+    #
+    # @input params [String] :name
+    #   String of the name of the author (or commiter) of the commit
+    # @input params [String] :email
+    #   String of the email of the author (or commiter) of the commit
+    # @input params [Timestamp] :date
+    #   Indicates when this commit was authored (or committed).
+    #   This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
+    #
+    # @example
+    #   github = Github.new
+    #   github.git_data.commits.create 'user-name', 'repo-name',
+    #     message: "my commit message",
+    #     author: {
+    #       name: "Scott Chacon",
+    #       email: "schacon@gmail.com",
+    #       date: "2008-07-09T16:13:30+12:00"
+    #     },
+    #     parents: [
+    #       "7d1b31e74ee336d15cbd21741bc88a537ed063a0"
+    #     ],
+    #     tree: "827efc6d56897b048c772eb4087f854f46256132"]
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        permit VALID_COMMIT_PARAM_NAMES
+        assert_required REQUIRED_COMMIT_PARAMS
+      end
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/commits", arguments.params)
+    end
+  end # GitData::Commits
+end # Github

data/lib/github_api/client/git_data/references.rb

@@ -0,0 +1,146 @@
+# encoding: utf-8
+
+module Github
+  class Client::GitData::References < API
+
+    VALID_REF_PARAM_NAMES = %w[ ref sha force ].freeze
+
+    REQUIRED_REF_PARAMS = %w[ ref sha ].freeze
+
+    VALID_REF_PARAM_VALUES = {
+      'ref' => %r{^refs\/\w+(\/\w+)*} # test fully qualified reference
+    }
+
+    # Get all references
+    #
+    # This will return an array of all the references on the system,
+    # including things like notes and stashes if they exist on the server.
+    # Anything in the namespace, not just <tt>heads</tt> and <tt>tags</tt>,
+    # though that would be the most common.
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.list 'user-name', 'repo-name'
+    #
+    # @example
+    #  github.git_data.references.list 'user-name', 'repo-name', ref:'tags'
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:user, :repo])
+      params = arguments.params
+      user = arguments.user
+      repo = arguments.repo
+
+      response = if (ref = params.delete('ref'))
+        validate_reference ref
+        get_request("/repos/#{user}/#{repo}/git/refs/#{ref}", params)
+      else
+        get_request("/repos/#{user}/#{repo}/git/refs", params)
+      end
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Get a reference
+    #
+    # The ref in the URL must be formatted as <tt>heads/branch</tt>,
+    # not just branch. For example, the call to get the data for a
+    # branch named sc/featureA would be formatted as heads/sc/featureA
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.get 'user-name', 'repo-name', 'heads/branch'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :ref])
+      validate_reference arguments.ref
+      params = arguments.params
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs/#{arguments.ref}", params)
+    end
+    alias :find :get
+
+    # Create a reference
+    #
+    # @param [Hash] params
+    # @input params [String] :ref
+    #   The name of the fully qualified reference (ie: refs/heads/master).
+    #   If it doesn’t start with ‘refs’ and have at least two slashes,
+    #   it will be rejected.
+    # @input params [String] :sha
+    #   The SHA1 value to set this reference to
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.create 'user-name', 'repo-name',
+    #    ref: "refs/heads/master",
+    #    sha:  "827efc6d56897b048c772eb4087f854f46256132"
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        permit VALID_REF_PARAM_NAMES
+        assert_required REQUIRED_REF_PARAMS
+      end
+      params = arguments.params
+      validate_reference params['ref']
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs", params)
+    end
+
+    # Update a reference
+    #
+    # @param [Hash] params
+    # @input params [String] :sha
+    #   The SHA1 value to set this reference to
+    # @input params [Boolean] :force
+    #   Indicates whether to force the update or to make sure the update
+    #   is a fast-forward update. Leaving this out or setting it to false
+    #   will make sure you’re not overwriting work. Default: false
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.update 'user-name', 'repo-name', 'heads/master',
+    #    sha:  "827efc6d56897b048c772eb4087f854f46256132",
+    #    force: true
+    #
+    # @api public
+    def update(*args)
+      arguments(args, required: [:user, :repo, :ref]) do
+        permit VALID_REF_PARAM_NAMES
+        assert_required %w[ sha ]
+      end
+
+      patch_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs/#{arguments.ref}", arguments.params)
+    end
+
+    # Delete a reference
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.references.delete 'user-name', 'repo-name',
+    #    ref: "refs/heads/master"
+    #
+    # @api public
+    def delete(*args)
+      arguments(args, required: [:user, :repo, :ref])
+      params = arguments.params
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/git/refs/#{arguments.ref}", params)
+    end
+    alias :remove :delete
+
+    private
+
+    def validate_reference(ref)
+      refs = (ref =~ (/^(\/)?refs.*/) ? ref : "refs/#{ref}").gsub(/(\/)+/, '/')
+      refs.gsub!(/^\//, '')
+      unless VALID_REF_PARAM_VALUES['ref'] =~ refs
+        raise ArgumentError, "Provided 'reference' is invalid"
+      end
+    end
+  end # GitData::References
+end # Github

data/lib/github_api/client/git_data/tags.rb

@@ -0,0 +1,94 @@
+# encoding: utf-8
+
+module Github
+  class Client::GitData::Tags < API
+    # This tags api only deals with tag objects -
+    # so only annotated tags, not lightweight tags.
+
+    VALID_TAG_PARAM_NAMES = %w[
+      tag
+      message
+      object
+      type
+      name
+      email
+      date
+      sha
+      url
+      tagger
+    ].freeze
+
+    VALID_TAG_PARAM_VALUES = {
+      'type' => %w[ blob tree commit ]
+    }
+
+    # Get a tag
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.tags.get 'user-name', 'repo-name', 'sha'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :sha])
+      params = arguments.params
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/git/tags/#{arguments.sha}", params)
+    end
+    alias :find :get
+
+    # Create a tag object
+    #
+    # Note that creating a tag object does not create the reference that
+    # makes a tag in Git. If you want to create an annotated tag in Git,
+    # you have to do this call to create the tag object, and then create
+    # the refs/tags/[tag] reference. If you want to create a lightweight
+    # tag, you simply have to create the reference -
+    # this call would be unnecessary.
+    #
+    # @param [Hash] params
+    # @input params [String] :tag
+    #   The tag
+    # @input params [String] :message
+    #   The tag message
+    # @input params [String] :object
+    #   The SHA of the git object this is tagging
+    # @input params [String] :type
+    #   The type of the object we're tagging.
+    #   Normally this is a commit but it can also be a tree or a blob
+    # @input params [Hash] :tagger
+    #   A hash with information about the individual creating the tag.
+    #
+    # The tagger hash contains the following keys:
+    # @input tagger [String] :name
+    #   The name of the author of the tag
+    # @input tagger [String] :email
+    #   The email of the author of the tag
+    # @input tagger [String] :date
+    #   When this object was tagged. This is a timestamp in ISO 8601
+    #   format: YYYY-MM-DDTHH:MM:SSZ.
+    #
+    # @xample
+    #  github = Github.new
+    #  github.git_data.tags.create 'user-name', 'repo-name',
+    #     tag: "v0.0.1",
+    #     message: "initial version\n",
+    #     type: "commit",
+    #     object: "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
+    #     tagger: {
+    #       name: "Scott Chacon",
+    #       email: "schacon@gmail.com",
+    #       date: "2011-06-17T14:53:3"
+    #     }
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        permit VALID_TAG_PARAM_NAMES
+        assert_values VALID_TAG_PARAM_VALUES
+      end
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/tags", arguments.params)
+    end
+  end # GitData::Tags
+end # Github

data/lib/github_api/client/git_data/trees.rb

@@ -0,0 +1,111 @@
+# encoding: utf-8
+
+module Github
+  class Client::GitData::Trees < API
+
+    VALID_TREE_PARAM_NAMES = %w[
+      base_tree
+      tree
+      path
+      mode
+      type
+      sha
+      content
+      url
+    ].freeze
+
+    VALID_TREE_PARAM_VALUES = {
+      'mode' => %w[ 100644 100755 040000 160000 120000 ],
+      'type' => %w[ blob tree commit ]
+    }
+
+    # Get a tree
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.trees.get 'user-name', 'repo-name', 'sha'
+    #  github.git_data.trees.get 'user-name', 'repo-name', 'sha' do |file|
+    #    file.path
+    #  end
+    #
+    # Get a tree recursively
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.trees.get 'user-name', 'repo-name', 'sha', recursive: true
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :sha])
+      user   = arguments.user
+      repo   = arguments.repo
+      sha    = arguments.sha
+      params = arguments.params
+
+      response = if params['recursive']
+        params['recursive'] = 1
+        get_request("/repos/#{user}/#{repo}/git/trees/#{sha}", params)
+      else
+        get_request("/repos/#{user}/#{repo}/git/trees/#{sha.to_s}", params)
+      end
+      return response unless block_given?
+      response.tree.each { |el| yield el }
+    end
+    alias :find :get
+
+    # Create a tree
+    #
+    # The tree creation API will take nested entries as well.
+    # If both a tree and a nested path modifying that tree are specified,
+    # it will overwrite the contents of that tree with the new path contents
+    # and write a new tree out.
+    #
+    # @param [Hash] params
+    # @input params [String] :base_tree
+    #   The SHA1 of the tree you want to update with new data
+    # @input params [Array[Hash]] :tree
+    #   Required. Objects (of path, mode, type, and sha)
+    #   specifying a tree structure
+    #
+    # The tree parameter takes the following keys:
+    # @input tree [String] :path
+    #   The file referenced in the tree
+    # @input tree [String] :mode
+    #   The file mode; one of 100644 for file (blob), 100755 for
+    #   executable (blob), 040000 for subdirectory (tree), 160000 for
+    #   submodule (commit), or 120000 for a blob that specifies
+    #   the path of a symlink
+    # @input tree [String] :type
+    #   Either blob, tree, or commit
+    # @input tree [String] :sha
+    #   The SHA1 checksum ID of the object in the tree
+    # @input tree [String] :content
+    #   The content you want this file to have - GitHub will write
+    #   this blob out and use the SHA for this entry.
+    #   Use either this or <tt>tree.sha</tt>
+    #
+    # @example
+    #  github = Github.new
+    #  github.git_data.trees.create 'user-name', 'repo-name',
+    #    tree: [
+    #      {
+    #        path: "file.rb",
+    #        mode: "100644",
+    #        type: "blob",
+    #        sha: "44b4fc6d56897b048c772eb4087f854f46256132"
+    #      },
+    #      ...
+    #    ]
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo]) do
+        assert_required %w[ tree ]
+        permit VALID_TREE_PARAM_NAMES, 'tree', { recursive: true }
+        assert_values VALID_TREE_PARAM_VALUES, 'tree'
+      end
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/git/trees", arguments.params)
+    end
+  end # GitData::Trees
+end # Github