# Commits

### Reference

- v4 API:
  - `gitlab.v4.objects.ProjectCommit`
  - `gitlab.v4.objects.ProjectCommitManager`
  - `gitlab.v4.objects.Project.commits`
- v3 API:
  - `gitlab.v3.objects.ProjectCommit`
  - `gitlab.v3.objects.ProjectCommitManager`
  - `gitlab.v3.objects.Project.commits`
  - `gitlab.Gitlab.project_commits`
- GitLab API: https://docs.gitlab.com/ce/api/commits.html

Warning

Pagination starts at page 0 in v3, but starts at page 1 in v4 (like all the v4 endpoints).

### Examples

List the commits for a project:

    commits = project.commits.list()

You can use the `ref_name`, `since` and `until` filters to limit the results:

    commits = project.commits.list(ref_name='my_branch')
    commits = project.commits.list(since='2016-01-01T00:00:00Z')

Create a commit:

    # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
    # for actions detail
    data = {
        'branch_name': 'master',  # v3
        'branch': 'master',  # v4
        'commit_message': 'blah blah blah',
        'actions': [
            {
                'action': 'create',
                'file_path': 'blah',
                'content': 'blah'
            }
        ]
    }

    commit = project.commits.create(data)

Get a commit detail:

    commit = project.commits.get('e3d5a71b')

Get the diff for a commit:

    diff = commit.diff()

Cherry-pick a commit into another branch:

    commit.cherry_pick(branch='target_branch')

## Commit comments

### Reference

- v4 API:
  - `gitlab.v4.objects.ProjectCommitComment`
  - `gitlab.v4.objects.ProjectCommitCommentManager`
  - `gitlab.v4.objects.Commit.comments`
- v3 API:
  - `gitlab.v3.objects.ProjectCommit`
  - `gitlab.v3.objects.ProjectCommitManager`
  - `gitlab.v3.objects.Commit.comments`
  - `gitlab.v3.objects.Project.commit_comments`
  - `gitlab.Gitlab.project_commit_comments`
- GitLab API: https://docs.gitlab.com/ce/api/commits.html

### Examples

Get the comments for a commit:

    comments = commit.comments.list()

Add a comment on a commit:

    # 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'})

## Commit status

### Reference

- v4 API:
  - `gitlab.v4.objects.ProjectCommitStatus`
  - `gitlab.v4.objects.ProjectCommitStatusManager`
  - `gitlab.v4.objects.Commit.statuses`
- v3 API:
  - `gitlab.v3.objects.ProjectCommit`
  - `gitlab.v3.objects.ProjectCommitManager`
  - `gitlab.v3.objects.Commit.statuses`
  - `gitlab.v3.objects.Project.commit_statuses`
  - `gitlab.Gitlab.project_commit_statuses`
- GitLab API: https://docs.gitlab.com/ce/api/commits.html

### Examples

Get the statuses for a commit:

    statuses = commit.statuses.list()

Change the status of a commit:

    commit.statuses.create({'state': 'success'})