docs: commits API

Gauvain Pocentek · Gauvain Pocentek · commit 07c55943eebb · 2016-07-24T12:21:20.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -6,6 +6,7 @@ API objects manipulation
 
    gl_objects/branches
    gl_objects/builds
+   gl_objects/commits
    gl_objects/groups
    gl_objects/projects
    gl_objects/runners
diff --git a/docs/gl_objects/commits.py b/docs/gl_objects/commits.py
@@ -0,0 +1,50 @@
+# list
+commits = gl.project_commits.list(project_id=1)
+# or
+commits = project.commits.list()
+# end list
+
+# filter list
+commits = project.commits.list(ref_name='my_branch')
+commits = project.commits.list(since='2016-01-01T00:00:00Z')
+# end filter list
+
+# get
+commit = gl.project_commits.get('e3d5a71b', project_id=1)
+# or
+commit = project.commits.get('e3d5a71b')
+# end get
+
+# diff
+diff = commit.diff()
+# end diff
+
+# comments list
+comments = gl.project_commit_comments.list(project_id=1, commit_id='master')
+# or
+comments = project.commit_comments.list(commit_id='a5fe4c8')
+# or
+comments = commit.comments.list()
+# end comments list
+
+# comments create
+# Global comment
+commit = commit.comments.create({'note': 'This is a nice comment'})
+# Comment on a line in a file (on the new version of the file)
+commit = commit.comments.create({'note': 'This is another comment',
+                                 'line': 12,
+                                 'line_type': 'new',
+                                 'path': 'README.rst'})
+# end comments create
+
+# statuses list
+statuses = gl.project_commit_statuses.list(project_id=1, commit_id='master')
+# or
+statuses = project.commit_statuses.list(commit_id='a5fe4c8')
+# or
+statuses = commit.statuses.list()
+# end statuses list
+
+# statuses set
+commit.statuses.create({'state': 'success'})
+# end statuses set
diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst
@@ -0,0 +1,87 @@
+#######
+Commits
+#######
+
+Commits
+=======
+
+Use :class:`~gitlab.objects.ProjectCommit` objects to manipulate commits. The
+:attr:`gitlab.Gitlab.project_commits` and
+:attr:`gitlab.objects.Project.commits` manager objects provide helper
+functions.
+
+Examples
+--------
+
+List the commits for a project:
+
+.. literalinclude:: commits.py
+   :start-after: # list
+   :end-before: # end list
+
+You can use the ``ref_name``, ``since`` and ``until`` filters to limit the
+results:
+
+.. literalinclude:: commits.py
+   :start-after: # filter list
+   :end-before: # end filter list
+
+Get a commit detail:
+
+.. literalinclude:: commits.py
+   :start-after: # get
+   :end-before: # end get
+
+Get the diff for a commit:
+
+.. literalinclude:: commits.py
+   :start-after: # diff
+   :end-before: # end diff
+
+Commit comments
+===============
+
+Use :class:`~gitlab.objects.ProjectCommitStatus` objects to manipulate commits. The
+:attr:`gitlab.Gitlab.project_commit_comments` and
+:attr:`gitlab.objects.Project.commit_comments` and
+:attr:`gitlab.objects.ProjectCommit.comments` manager objects provide helper
+functions.
+
+Examples
+--------
+
+Get the comments for a commit:
+
+.. literalinclude:: commits.py
+   :start-after: # comments list
+   :end-before: # end comments list
+
+Add a comment on a commit:
+
+.. literalinclude:: commits.py
+   :start-after: # comments create
+   :end-before: # end comments create
+
+Commit status
+=============
+
+Use :class:`~gitlab.objects.ProjectCommitStatus` objects to manipulate commits.
+The :attr:`gitlab.Gitlab.project_commit_statuses`,
+:attr:`gitlab.objects.Project.commit_statuses` and
+:attr:`gitlab.objects.ProjectCommit.statuses` manager objects provide helper
+functions.
+
+Examples
+--------
+
+Get the statuses for a commit:
+
+.. literalinclude:: commits.py
+   :start-after: # statuses list
+   :end-before: # end statuses list
+
+Change the status of a commit:
+
+.. literalinclude:: commits.py
+   :start-after: # statuses set
+   :end-before: # end statuses set
