gitlab 3.3.0 → 3.4.0

data/lib/gitlab/client.rb

@@ -6,14 +6,15 @@ module Gitlab
     include Branches
     include Groups
     include Issues
+    include Labels
     include MergeRequests
     include Milestones
     include Notes
     include Projects
     include Repositories
+    include RepositoryFiles
     include Snippets
     include SystemHooks
     include Users
-    include Labels
   end
 end

data/lib/gitlab/client/branches.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to repositories.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/branches.md
   module Branches
     # Gets a list of project repositiory branches.
     #
@@ -28,7 +29,7 @@ class Gitlab::Client
     def branch(project, branch)
       get("/projects/#{project}/repository/branches/#{branch}")
     end
-    
+
     alias_method :repo_branch, :branch
 
     # Protects a repository branch.
@@ -74,6 +75,20 @@ class Gitlab::Client
     end
     alias_method :repo_create_branch, :create_branch
 
+    # Deletes a repository branch.  Requires Gitlab >= 6.8.x
+    #
+    # @example
+    #   Gitlab.delete_branch(3, 'api')
+    #   Gitlab.repo_delete_branch(5, 'master')
+    #
+    # @param  [Integer] project The ID of a project.
+    # @param  [String] branch The name of the branch to delete
+    # @return [Gitlab::ObjectifiedHash]
+    def delete_branch(project, branch)
+      delete("/projects/#{project}/repository/branches/#{branch}")
+    end
+    alias_method :repo_delete_branch, :delete_branch
+
   end
 end
 

data/lib/gitlab/client/groups.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to groups.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/groups.md
   module Groups
     # Gets a list of groups.
     #

data/lib/gitlab/client/issues.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to issues.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/issues.md
   module Issues
     # Gets a list of user's issues.
     # Will return a list of project's issues if project ID passed.

data/lib/gitlab/client/labels.rb

@@ -1,4 +1,6 @@
 class Gitlab::Client
+  # Defines methods related to labels.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/labels.md
   module Labels
     # Gets a list of project's labels.
     #

data/lib/gitlab/client/merge_requests.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to merge requests.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/merge_requests.md
   module MergeRequests
     # Gets a list of project merge requests.
     #
@@ -42,10 +43,9 @@ class Gitlab::Client
     # @option options [String] :source_branch (required) The source branch name.
     # @option options [String] :target_branch (required) The target branch name.
     # @option options [Integer] :assignee_id (optional) The ID of a user to assign merge request.
+    # @option options [Integer] :target_project_id (optional) The target project ID.
     # @return [Gitlab::ObjectifiedHash] Information about created merge request.
     def create_merge_request(project, title, options={})
-      check_attributes!(options, [:source_branch, :target_branch])
-
       body = {:title => title}.merge(options)
       post("/projects/#{project}/merge_requests", :body => body)
     end
@@ -112,14 +112,16 @@ class Gitlab::Client
       get("/projects/#{project}/merge_request/#{id}/comments", :query => options)
     end
 
-    private
-
-    def check_attributes!(options, attrs)
-      attrs.each do |attr|
-        unless options.has_key?(attr) || options.has_key?(attr.to_s)
-          raise Gitlab::Error::MissingAttributes.new("Missing '#{attr}' parameter")
-        end
-      end
+    # Gets the changes of a merge request.
+    #
+    # @example
+    #   Gitlab.merge_request_changes(5, 1)
+    #
+    # @param  [Integer] project The ID of a project.
+    # @param  [Integer] id The ID of a merge request.
+    # @return [Gitlab::ObjectifiedHash] The merge request's changes.
+    def merge_request_changes(project, id)
+      get("/projects/#{project}/merge_request/#{id}/changes")
     end
   end
 end

data/lib/gitlab/client/milestones.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to milestones.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/milestones.md
   module Milestones
     # Gets a list of project's milestones.
     #
@@ -27,6 +28,20 @@ class Gitlab::Client
       get("/projects/#{project}/milestones/#{id}")
     end
 
+    # Gets the issues of a given milestone.
+    #
+    # @example
+    #   Gitlab.milestone_issues(5, 2)
+    #
+    # @param  [Integer, String] project The ID of a project.
+    # @param  [Integer, String] milestone The ID of a milestone.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def milestone_issues(project, milestone, options={})
+      get("/projects/#{project}/milestones/#{milestone}/issues", :query => options)
+    end
+
     # Creates a new milestone.
     #
     # @param  [Integer] project The ID of a project.

data/lib/gitlab/client/notes.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to notes.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/notes.md
   module Notes
     # Gets a list of projects notes.
     #
@@ -7,9 +8,11 @@ class Gitlab::Client
     #   Gitlab.notes(5)
     #
     # @param [Integer] project The ID of a project.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
     # @return [Array<Gitlab::ObjectifiedHash>]
-    def notes(project)
-      get("/projects/#{project}/notes")
+    def notes(project, options={})
+      get("/projects/#{project}/notes", :query => options)
     end
 
     # Gets a list of notes for a issue.
@@ -19,9 +22,11 @@ class Gitlab::Client
     #
     # @param [Integer] project The ID of a project.
     # @param [Integer] issue The ID of an issue.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
     # @return [Array<Gitlab::ObjectifiedHash>]
-    def issue_notes(project, issue)
-      get("/projects/#{project}/issues/#{issue}/notes")
+    def issue_notes(project, issue, options={})
+      get("/projects/#{project}/issues/#{issue}/notes", :query => options)
     end
 
     # Gets a list of notes for a snippet.
@@ -31,9 +36,11 @@ class Gitlab::Client
     #
     # @param [Integer] project The ID of a project.
     # @param [Integer] snippet The ID of a snippet.
+    # @option options [Integer] :page The page number.
+    # @option options [Integer] :per_page The number of results per page.
     # @return [Array<Gitlab::ObjectifiedHash>]
-    def snippet_notes(project, snippet)
-      get("/projects/#{project}/snippets/#{snippet}/notes")
+    def snippet_notes(project, snippet, options={})
+      get("/projects/#{project}/snippets/#{snippet}/notes", :query => options)
     end
 
     # Gets a single wall note.
@@ -102,5 +109,14 @@ class Gitlab::Client
     def create_snippet_note(project, snippet, body)
       post("/projects/#{project}/snippets/#{snippet}/notes", :body => {:body => body})
     end
+
+    # Creates a new note for a single merge request.
+    #
+    # @param [Integer] project The ID of a project.
+    # @param [Integer] merge_request The ID of a merge request.
+    # @param [String] body The content of a note.
+    def create_merge_request_note(project, merge_request, body)
+      post("/projects/#{project}/merge_requests/#{merge_request}/notes", :body => {:body => body})
+    end
   end
 end

data/lib/gitlab/client/projects.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to projects.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/projects.md
   module Projects
     # Gets a list of projects owned by the authenticated user.
     #
@@ -19,6 +20,23 @@ class Gitlab::Client
       end
     end
 
+    # Search for projects by name
+    #
+    # @example
+    #   Gitlab.project_search('gitlab')
+    #   Gitlab.project_search('gitlab', :order_by => 'last_activity_at')
+    #
+    # @param  [Hash] options A customizable set of options.
+    # @option options [String] :per_page Number of projects to return per page
+    # @option options [String] :page The page to retrieve
+    # @option options [String] :order_by Return requests ordered by id, name, created_at or last_activity_at fields
+    # @option options [String] :sort Return requests sorted in asc or desc order
+    # @return [Array<Gitlab::ObjectifiedHash>]
+    def project_search(query, options={})
+      get("/projects/search/#{query}", :query => options)
+    end
+
+
     # Gets information about a project.
     #
     # @example

data/lib/gitlab/client/repositories.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to repositories.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/repositories.md
   module Repositories
     # Gets a list of project repository tags.
     #
@@ -19,7 +20,8 @@ class Gitlab::Client
     # Creates a new project repository tag.
     #
     # @example
-    #   Gitlab.create_tag(42,'new_tag','master')
+    #   Gitlab.create_tag(42, 'new_tag', 'master')
+    #   Gitlab.create_tag(42, 'v1.0', 'master', 'Release 1.0')
     #
     # @param  [Integer] project The ID of a project.
     # @param  [String]  tag_name The name of the new tag.
@@ -87,6 +89,7 @@ class Gitlab::Client
     # @param  [String] ref The name of a repository branch or tag or if not given the default branch.
     # @return [String]
     def file_contents(project, filepath, ref = 'master')
+      ref = URI.encode(ref, /\W/)
       get "/projects/#{project}/repository/blobs/#{ref}?filepath=#{filepath}",
         format: nil,
         headers: { Accept: 'text/plain' },

data/lib/gitlab/client/repository_files.rb

@@ -0,0 +1,72 @@
+require 'base64'
+
+class Gitlab::Client
+  # Defines methods related to repository files.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/repository_files.md
+  module RepositoryFiles
+    # Creates a new repository file.
+    #
+    # @example
+    #   Gitlab.create_file(42, "path", "branch", "content", "commit message")
+    #
+    # @param  [Integer] project The ID of a project.
+    # @param  [String] full path to new file.
+    # @param  [String] the name of the branch.
+    # @param  [String] file content.
+    # @param  [String] commit message.
+    # @return [Gitlab::ObjectifiedHash]
+    def create_file(project, path, branch, content, commit_message)
+      post("/projects/#{project}/repository/files", body: {
+        file_path: path,
+        branch_name: branch,
+        commit_message: commit_message,
+      }.merge(encoded_content_attributes(content)))
+    end
+
+    # Edits an existing repository file.
+    #
+    # @example
+    #   Gitlab.edit_file(42, "path", "branch", "content", "commit message")
+    #
+    # @param  [Integer] project The ID of a project.
+    # @param  [String] full path to new file.
+    # @param  [String] the name of the branch.
+    # @param  [String] file content.
+    # @param  [String] commit message.
+    # @return [Gitlab::ObjectifiedHash]
+    def edit_file(project, path, branch, content, commit_message)
+      put("/projects/#{project}/repository/files", body: {
+        file_path: path,
+        branch_name: branch,
+        commit_message: commit_message,
+      }.merge(encoded_content_attributes(content)))
+    end
+
+    # Removes an existing repository file.
+    #
+    # @example
+    #   Gitlab.remove_file(42, "path", "branch", "commit message")
+    #
+    # @param  [Integer] project The ID of a project.
+    # @param  [String] full path to new file.
+    # @param  [String] the name of the branch.
+    # @param  [String] commit message.
+    # @return [Gitlab::ObjectifiedHash]
+    def remove_file(project, path, branch, commit_message)
+      delete("/projects/#{project}/repository/files", body: {
+        file_path: path,
+        branch_name: branch,
+        commit_message: commit_message,
+      })
+    end
+
+    private
+
+    def encoded_content_attributes(content)
+      {
+        encoding: 'base64',
+        content: Base64.encode64(content),
+      }
+    end
+  end
+end

data/lib/gitlab/client/snippets.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to snippets.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/project_snippets.md
   module Snippets
     # Gets a list of project's snippets.
     #
@@ -40,7 +41,6 @@ class Gitlab::Client
     # @option options [String] :lifetime (optional) The expiration date of a snippet.
     # @return [Gitlab::ObjectifiedHash] Information about created snippet.
     def create_snippet(project, options={})
-      check_attributes!(options, [:title, :file_name, :code])
       post("/projects/#{project}/snippets", :body => options)
     end
 
@@ -72,15 +72,5 @@ class Gitlab::Client
     def delete_snippet(project, id)
       delete("/projects/#{project}/snippets/#{id}")
     end
-
-    private
-
-    def check_attributes!(options, attrs)
-      attrs.each do |attr|
-        unless options.has_key?(attr) || options.has_key?(attr.to_s)
-          raise Gitlab::Error::MissingAttributes.new("Missing '#{attr}' parameter")
-        end
-      end
-    end
   end
 end

data/lib/gitlab/client/system_hooks.rb

@@ -1,5 +1,6 @@
 class Gitlab::Client
   # Defines methods related to system hooks.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/system_hooks.md
   module SystemHooks
     # Gets a list of system hooks.
     #

data/lib/gitlab/client/users.rb

@@ -1,5 +1,7 @@
 class Gitlab::Client
   # Defines methods related to users.
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/users.md
+  # @see https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/session.md
   module Users
     # Gets a list of users.
     #

data/lib/gitlab/configuration.rb

@@ -9,6 +9,8 @@ module Gitlab
 
     # @private
     attr_accessor(*VALID_OPTIONS_KEYS)
+    # @private
+    alias_method :auth_token=, :private_token=
 
     # Sets all configuration options to their default values
     # when this module is extended.
@@ -31,7 +33,7 @@ module Gitlab
     # Resets all configuration options to the defaults.
     def reset
       self.endpoint       = ENV['GITLAB_API_ENDPOINT']
-      self.private_token  = ENV['GITLAB_API_PRIVATE_TOKEN']
+      self.private_token  = ENV['GITLAB_API_PRIVATE_TOKEN'] || ENV['GITLAB_API_AUTH_TOKEN']
       self.sudo           = nil
       self.user_agent     = DEFAULT_USER_AGENT
     end

data/lib/gitlab/error.rb

@@ -3,9 +3,6 @@ module Gitlab
     # Custom error class for rescuing from all Gitlab errors.
     class Error < StandardError; end
 
-    # Raise when attributes are missing.
-    class MissingAttributes < Error; end
-
     # Raised when API endpoint credentials not configured.
     class MissingCredentials < Error; end
 

data/lib/gitlab/help.rb

@@ -4,41 +4,87 @@ require 'gitlab/cli_helpers'
 module Gitlab::Help
   extend Gitlab::CLI::Helpers
 
-  def self.get_help(methods,cmd=nil)
-    help = ''
-
-    if cmd.nil? || cmd == 'help'
-      help = actions_table
-    else
-      ri_cmd = `which ri`.chomp
-
-      if $? == 0
-        namespace = methods.select {|m| m[:name] === cmd }.map {|m| m[:owner]+'.'+m[:name] }.shift
-
-        if namespace
-          begin
-            ri_output = `#{ri_cmd} -T #{namespace} 2>&1`.chomp
-
-            if $? == 0
-              ri_output.gsub!(/#{cmd}\((.*?)\)/m, cmd+' \1')
-              ri_output.gsub!(/Gitlab\./, 'gitlab> ')
-              ri_output.gsub!(/Gitlab\..+$/, '')
-              ri_output.gsub!(/\,[\s]*/, ' ')
-              help = ri_output
-            else
-              help = "Ri docs not found for #{namespace}, please install the docs to use 'help'"
-            end
-          rescue => e
-            puts e.message
-          end
+  class << self
+
+    # Returns the (modified) help from the 'ri' command or returns an error.
+    #
+    # @return [String]
+    def get_help(cmd)
+      cmd_namespace = namespace cmd
+
+      if cmd_namespace
+        ri_output = `#{ri_cmd} -T #{cmd_namespace} 2>&1`.chomp
+
+        if $? == 0
+          change_help_output! cmd, ri_output
+          yield ri_output if block_given?
+
+          ri_output
         else
-          help = "Unknown command: #{cmd}"
+          "Ri docs not found for #{cmd}, please install the docs to use 'help'."
         end
       else
-        help = "'ri' tool not found in your PATH, please install it to use the help."
+        "Unknown command: #{cmd}."
+      end
+    end
+
+    # Finds the location of 'ri' on a system.
+    #
+    # @return [String]
+    def ri_cmd
+      which_ri = `which ri`.chomp
+      if which_ri.empty?
+        raise "'ri' tool not found in $PATH. Please install it to use the help."
       end
+
+      which_ri
     end
 
-    puts help
-  end
+    # A hash map that contains help topics (Branches, Groups, etc.)
+    # and a list of commands that are defined under a topic (create_branch,
+    # branches, protect_branch, etc.).
+    #
+    # @return [Hash<Array>]
+    def help_map
+      @help_map ||= begin
+          actions.each_with_object({}) do |action, hsh|
+            key = client.method(action).
+                         owner.to_s.gsub(/Gitlab::(?:Client::)?/, '')
+            hsh[key] ||= []
+            hsh[key] << action.to_s
+          end
+      end
+    end
+
+    # Table with available commands.
+    #
+    # @return [Terminal::Table]
+    def actions_table(topic = nil)
+      rows = topic ? help_map[topic] : help_map.keys
+      table do |t|
+        t.title = topic || "Help Topics"
+
+        # add_row expects an array and we have strings hence the map.
+        rows.sort.map { |r| [r] }.each_with_index do |row, index|
+          t.add_row row
+          t.add_separator unless rows.size - 1 == index
+        end
+      end
+    end
+
+    # Returns full namespace of a command (e.g. Gitlab::Client::Branches.cmd)
+    def namespace(cmd)
+      method_owners.select { |method| method[:name] === cmd }.
+                    map    { |method| method[:owner] + '.' + method[:name] }.
+                    shift
+    end
+
+    # Massage output from 'ri'.
+    def change_help_output!(cmd, output_str)
+      output_str.gsub!(/#{cmd}\((.*?)\)/m, cmd+' \1')
+      output_str.gsub!(/\,[\s]*/, ' ')
+    end
+
+  end # class << self
 end
+