1//
2// Copyright 2017, Sander van Harmelen
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8// http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15//
16
17package gitlab
18
19import (
20 "fmt"
21 "time"
22)
23
24// CommitsService handles communication with the commit related methods
25// of the GitLab API.
26//
27// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html
28type CommitsService struct {
29 client *Client
30}
31
32// Commit represents a GitLab commit.
33//
34// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html
35type Commit struct {
36 ID string `json:"id"`
37 ShortID string `json:"short_id"`
38 Title string `json:"title"`
39 AuthorName string `json:"author_name"`
40 AuthorEmail string `json:"author_email"`
41 AuthoredDate *time.Time `json:"authored_date"`
42 CommitterName string `json:"committer_name"`
43 CommitterEmail string `json:"committer_email"`
44 CommittedDate *time.Time `json:"committed_date"`
45 CreatedAt *time.Time `json:"created_at"`
46 Message string `json:"message"`
47 ParentIDs []string `json:"parent_ids"`
48 Stats *CommitStats `json:"stats"`
49 Status *BuildStateValue `json:"status"`
50 LastPipeline *PipelineInfo `json:"last_pipeline"`
51 ProjectID int `json:"project_id"`
52}
53
54// CommitStats represents the number of added and deleted files in a commit.
55//
56// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html
57type CommitStats struct {
58 Additions int `json:"additions"`
59 Deletions int `json:"deletions"`
60 Total int `json:"total"`
61}
62
63func (c Commit) String() string {
64 return Stringify(c)
65}
66
67// ListCommitsOptions represents the available ListCommits() options.
68//
69// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#list-repository-commits
70type ListCommitsOptions struct {
71 ListOptions
72 RefName *string `url:"ref_name,omitempty" json:"ref_name,omitempty"`
73 Since *time.Time `url:"since,omitempty" json:"since,omitempty"`
74 Until *time.Time `url:"until,omitempty" json:"until,omitempty"`
75 Path *string `url:"path,omitempty" json:"path,omitempty"`
76 All *bool `url:"all,omitempty" json:"all,omitempty"`
77 WithStats *bool `url:"with_stats,omitempty" json:"with_stats,omitempty"`
78}
79
80// ListCommits gets a list of repository commits in a project.
81//
82// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#list-commits
83func (s *CommitsService) ListCommits(pid interface{}, opt *ListCommitsOptions, options ...OptionFunc) ([]*Commit, *Response, error) {
84 project, err := parseID(pid)
85 if err != nil {
86 return nil, nil, err
87 }
88 u := fmt.Sprintf("projects/%s/repository/commits", pathEscape(project))
89
90 req, err := s.client.NewRequest("GET", u, opt, options)
91 if err != nil {
92 return nil, nil, err
93 }
94
95 var c []*Commit
96 resp, err := s.client.Do(req, &c)
97 if err != nil {
98 return nil, resp, err
99 }
100
101 return c, resp, err
102}
103
104// FileAction represents the available actions that can be performed on a file.
105//
106// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
107type FileAction string
108
109// The available file actions.
110const (
111 FileCreate FileAction = "create"
112 FileDelete FileAction = "delete"
113 FileMove FileAction = "move"
114 FileUpdate FileAction = "update"
115)
116
117// CommitAction represents a single file action within a commit.
118type CommitAction struct {
119 Action FileAction `url:"action" json:"action"`
120 FilePath string `url:"file_path" json:"file_path"`
121 PreviousPath string `url:"previous_path,omitempty" json:"previous_path,omitempty"`
122 Content string `url:"content,omitempty" json:"content,omitempty"`
123 Encoding string `url:"encoding,omitempty" json:"encoding,omitempty"`
124}
125
126// CommitRef represents the reference of branches/tags in a commit.
127//
128// GitLab API docs:
129// https://docs.gitlab.com/ce/api/commits.html#get-references-a-commit-is-pushed-to
130type CommitRef struct {
131 Type string `json:"type"`
132 Name string `json:"name"`
133}
134
135// GetCommitRefsOptions represents the available GetCommitRefs() options.
136//
137// GitLab API docs:
138// https://docs.gitlab.com/ce/api/commits.html#get-references-a-commit-is-pushed-to
139type GetCommitRefsOptions struct {
140 ListOptions
141 Type *string `url:"type,omitempty" json:"type,omitempty"`
142}
143
144// GetCommitRefs gets all references (from branches or tags) a commit is pushed to
145//
146// GitLab API docs:
147// https://docs.gitlab.com/ce/api/commits.html#get-references-a-commit-is-pushed-to
148func (s *CommitsService) GetCommitRefs(pid interface{}, sha string, opt *GetCommitRefsOptions, options ...OptionFunc) ([]*CommitRef, *Response, error) {
149 project, err := parseID(pid)
150 if err != nil {
151 return nil, nil, err
152 }
153 u := fmt.Sprintf("projects/%s/repository/commits/%s/refs", pathEscape(project), sha)
154
155 req, err := s.client.NewRequest("GET", u, opt, options)
156 if err != nil {
157 return nil, nil, err
158 }
159
160 var cs []*CommitRef
161 resp, err := s.client.Do(req, &cs)
162 if err != nil {
163 return nil, resp, err
164 }
165
166 return cs, resp, err
167}
168
169// GetCommit gets a specific commit identified by the commit hash or name of a
170// branch or tag.
171//
172// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#get-a-single-commit
173func (s *CommitsService) GetCommit(pid interface{}, sha string, options ...OptionFunc) (*Commit, *Response, error) {
174 project, err := parseID(pid)
175 if err != nil {
176 return nil, nil, err
177 }
178 u := fmt.Sprintf("projects/%s/repository/commits/%s", pathEscape(project), sha)
179
180 req, err := s.client.NewRequest("GET", u, nil, options)
181 if err != nil {
182 return nil, nil, err
183 }
184
185 c := new(Commit)
186 resp, err := s.client.Do(req, c)
187 if err != nil {
188 return nil, resp, err
189 }
190
191 return c, resp, err
192}
193
194// CreateCommitOptions represents the available options for a new commit.
195//
196// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
197type CreateCommitOptions struct {
198 Branch *string `url:"branch" json:"branch"`
199 CommitMessage *string `url:"commit_message" json:"commit_message"`
200 StartBranch *string `url:"start_branch,omitempty" json:"start_branch,omitempty"`
201 Actions []*CommitAction `url:"actions" json:"actions"`
202 AuthorEmail *string `url:"author_email,omitempty" json:"author_email,omitempty"`
203 AuthorName *string `url:"author_name,omitempty" json:"author_name,omitempty"`
204}
205
206// CreateCommit creates a commit with multiple files and actions.
207//
208// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
209func (s *CommitsService) CreateCommit(pid interface{}, opt *CreateCommitOptions, options ...OptionFunc) (*Commit, *Response, error) {
210 project, err := parseID(pid)
211 if err != nil {
212 return nil, nil, err
213 }
214 u := fmt.Sprintf("projects/%s/repository/commits", pathEscape(project))
215
216 req, err := s.client.NewRequest("POST", u, opt, options)
217 if err != nil {
218 return nil, nil, err
219 }
220
221 c := new(Commit)
222 resp, err := s.client.Do(req, &c)
223 if err != nil {
224 return nil, resp, err
225 }
226
227 return c, resp, err
228}
229
230// Diff represents a GitLab diff.
231//
232// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html
233type Diff struct {
234 Diff string `json:"diff"`
235 NewPath string `json:"new_path"`
236 OldPath string `json:"old_path"`
237 AMode string `json:"a_mode"`
238 BMode string `json:"b_mode"`
239 NewFile bool `json:"new_file"`
240 RenamedFile bool `json:"renamed_file"`
241 DeletedFile bool `json:"deleted_file"`
242}
243
244func (d Diff) String() string {
245 return Stringify(d)
246}
247
248// GetCommitDiffOptions represents the available GetCommitDiff() options.
249//
250// GitLab API docs:
251// https://docs.gitlab.com/ce/api/commits.html#get-the-diff-of-a-commit
252type GetCommitDiffOptions ListOptions
253
254// GetCommitDiff gets the diff of a commit in a project..
255//
256// GitLab API docs:
257// https://docs.gitlab.com/ce/api/commits.html#get-the-diff-of-a-commit
258func (s *CommitsService) GetCommitDiff(pid interface{}, sha string, opt *GetCommitDiffOptions, options ...OptionFunc) ([]*Diff, *Response, error) {
259 project, err := parseID(pid)
260 if err != nil {
261 return nil, nil, err
262 }
263 u := fmt.Sprintf("projects/%s/repository/commits/%s/diff", pathEscape(project), sha)
264
265 req, err := s.client.NewRequest("GET", u, opt, options)
266 if err != nil {
267 return nil, nil, err
268 }
269
270 var d []*Diff
271 resp, err := s.client.Do(req, &d)
272 if err != nil {
273 return nil, resp, err
274 }
275
276 return d, resp, err
277}
278
279// CommitComment represents a GitLab commit comment.
280//
281// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html
282type CommitComment struct {
283 Note string `json:"note"`
284 Path string `json:"path"`
285 Line int `json:"line"`
286 LineType string `json:"line_type"`
287 Author Author `json:"author"`
288}
289
290// Author represents a GitLab commit author
291type Author struct {
292 ID int `json:"id"`
293 Username string `json:"username"`
294 Email string `json:"email"`
295 Name string `json:"name"`
296 State string `json:"state"`
297 Blocked bool `json:"blocked"`
298 CreatedAt *time.Time `json:"created_at"`
299}
300
301func (c CommitComment) String() string {
302 return Stringify(c)
303}
304
305// GetCommitCommentsOptions represents the available GetCommitComments() options.
306//
307// GitLab API docs:
308// https://docs.gitlab.com/ce/api/commits.html#get-the-comments-of-a-commit
309type GetCommitCommentsOptions ListOptions
310
311// GetCommitComments gets the comments of a commit in a project.
312//
313// GitLab API docs:
314// https://docs.gitlab.com/ce/api/commits.html#get-the-comments-of-a-commit
315func (s *CommitsService) GetCommitComments(pid interface{}, sha string, opt *GetCommitCommentsOptions, options ...OptionFunc) ([]*CommitComment, *Response, error) {
316 project, err := parseID(pid)
317 if err != nil {
318 return nil, nil, err
319 }
320 u := fmt.Sprintf("projects/%s/repository/commits/%s/comments", pathEscape(project), sha)
321
322 req, err := s.client.NewRequest("GET", u, opt, options)
323 if err != nil {
324 return nil, nil, err
325 }
326
327 var c []*CommitComment
328 resp, err := s.client.Do(req, &c)
329 if err != nil {
330 return nil, resp, err
331 }
332
333 return c, resp, err
334}
335
336// PostCommitCommentOptions represents the available PostCommitComment()
337// options.
338//
339// GitLab API docs:
340// https://docs.gitlab.com/ce/api/commits.html#post-comment-to-commit
341type PostCommitCommentOptions struct {
342 Note *string `url:"note,omitempty" json:"note,omitempty"`
343 Path *string `url:"path" json:"path"`
344 Line *int `url:"line" json:"line"`
345 LineType *string `url:"line_type" json:"line_type"`
346}
347
348// PostCommitComment adds a comment to a commit. Optionally you can post
349// comments on a specific line of a commit. Therefor both path, line_new and
350// line_old are required.
351//
352// GitLab API docs:
353// https://docs.gitlab.com/ce/api/commits.html#post-comment-to-commit
354func (s *CommitsService) PostCommitComment(pid interface{}, sha string, opt *PostCommitCommentOptions, options ...OptionFunc) (*CommitComment, *Response, error) {
355 project, err := parseID(pid)
356 if err != nil {
357 return nil, nil, err
358 }
359 u := fmt.Sprintf("projects/%s/repository/commits/%s/comments", pathEscape(project), sha)
360
361 req, err := s.client.NewRequest("POST", u, opt, options)
362 if err != nil {
363 return nil, nil, err
364 }
365
366 c := new(CommitComment)
367 resp, err := s.client.Do(req, c)
368 if err != nil {
369 return nil, resp, err
370 }
371
372 return c, resp, err
373}
374
375// GetCommitStatusesOptions represents the available GetCommitStatuses() options.
376//
377// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#get-the-status-of-a-commit
378type GetCommitStatusesOptions struct {
379 ListOptions
380 Ref *string `url:"ref,omitempty" json:"ref,omitempty"`
381 Stage *string `url:"stage,omitempty" json:"stage,omitempty"`
382 Name *string `url:"name,omitempty" json:"name,omitempty"`
383 All *bool `url:"all,omitempty" json:"all,omitempty"`
384}
385
386// CommitStatus represents a GitLab commit status.
387//
388// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#get-the-status-of-a-commit
389type CommitStatus struct {
390 ID int `json:"id"`
391 SHA string `json:"sha"`
392 Ref string `json:"ref"`
393 Status string `json:"status"`
394 Name string `json:"name"`
395 TargetURL string `json:"target_url"`
396 Description string `json:"description"`
397 CreatedAt *time.Time `json:"created_at"`
398 StartedAt *time.Time `json:"started_at"`
399 FinishedAt *time.Time `json:"finished_at"`
400 Author Author `json:"author"`
401}
402
403// GetCommitStatuses gets the statuses of a commit in a project.
404//
405// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#get-the-status-of-a-commit
406func (s *CommitsService) GetCommitStatuses(pid interface{}, sha string, opt *GetCommitStatusesOptions, options ...OptionFunc) ([]*CommitStatus, *Response, error) {
407 project, err := parseID(pid)
408 if err != nil {
409 return nil, nil, err
410 }
411 u := fmt.Sprintf("projects/%s/repository/commits/%s/statuses", pathEscape(project), sha)
412
413 req, err := s.client.NewRequest("GET", u, opt, options)
414 if err != nil {
415 return nil, nil, err
416 }
417
418 var cs []*CommitStatus
419 resp, err := s.client.Do(req, &cs)
420 if err != nil {
421 return nil, resp, err
422 }
423
424 return cs, resp, err
425}
426
427// SetCommitStatusOptions represents the available SetCommitStatus() options.
428//
429// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#post-the-status-to-commit
430type SetCommitStatusOptions struct {
431 State BuildStateValue `url:"state" json:"state"`
432 Ref *string `url:"ref,omitempty" json:"ref,omitempty"`
433 Name *string `url:"name,omitempty" json:"name,omitempty"`
434 Context *string `url:"context,omitempty" json:"context,omitempty"`
435 TargetURL *string `url:"target_url,omitempty" json:"target_url,omitempty"`
436 Description *string `url:"description,omitempty" json:"description,omitempty"`
437}
438
439// SetCommitStatus sets the status of a commit in a project.
440//
441// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#post-the-status-to-commit
442func (s *CommitsService) SetCommitStatus(pid interface{}, sha string, opt *SetCommitStatusOptions, options ...OptionFunc) (*CommitStatus, *Response, error) {
443 project, err := parseID(pid)
444 if err != nil {
445 return nil, nil, err
446 }
447 u := fmt.Sprintf("projects/%s/statuses/%s", pathEscape(project), sha)
448
449 req, err := s.client.NewRequest("POST", u, opt, options)
450 if err != nil {
451 return nil, nil, err
452 }
453
454 cs := new(CommitStatus)
455 resp, err := s.client.Do(req, &cs)
456 if err != nil {
457 return nil, resp, err
458 }
459
460 return cs, resp, err
461}
462
463// GetMergeRequestsByCommit gets merge request associated with a commit.
464//
465// GitLab API docs:
466// https://docs.gitlab.com/ce/api/commits.html#list-merge-requests-associated-with-a-commit
467func (s *CommitsService) GetMergeRequestsByCommit(pid interface{}, sha string, options ...OptionFunc) ([]*MergeRequest, *Response, error) {
468 project, err := parseID(pid)
469 if err != nil {
470 return nil, nil, err
471 }
472 u := fmt.Sprintf("projects/%s/repository/commits/%s/merge_requests", pathEscape(project), sha)
473
474 req, err := s.client.NewRequest("GET", u, nil, options)
475 if err != nil {
476 return nil, nil, err
477 }
478
479 var mrs []*MergeRequest
480 resp, err := s.client.Do(req, &mrs)
481 if err != nil {
482 return nil, resp, err
483 }
484
485 return mrs, resp, err
486}
487
488// CherryPickCommitOptions represents the available CherryPickCommit() options.
489//
490// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#cherry-pick-a-commit
491type CherryPickCommitOptions struct {
492 Branch *string `url:"branch,omitempty" json:"branch,omitempty"`
493}
494
495// CherryPickCommit cherry picks a commit to a given branch.
496//
497// GitLab API docs: https://docs.gitlab.com/ce/api/commits.html#cherry-pick-a-commit
498func (s *CommitsService) CherryPickCommit(pid interface{}, sha string, opt *CherryPickCommitOptions, options ...OptionFunc) (*Commit, *Response, error) {
499 project, err := parseID(pid)
500 if err != nil {
501 return nil, nil, err
502 }
503 u := fmt.Sprintf("projects/%s/repository/commits/%s/cherry_pick", pathEscape(project), sha)
504
505 req, err := s.client.NewRequest("POST", u, opt, options)
506 if err != nil {
507 return nil, nil, err
508 }
509
510 c := new(Commit)
511 resp, err := s.client.Do(req, &c)
512 if err != nil {
513 return nil, resp, err
514 }
515
516 return c, resp, err
517}
518
519// RevertCommitOptions represents the available RevertCommit() options.
520//
521// GitLab API docs: https://docs.gitlab.com/ee/api/commits.html#revert-a-commit
522type RevertCommitOptions struct {
523 Branch *string `url:"branch,omitempty" json:"branch,omitempty"`
524}
525
526// RevertCommit reverts a commit in a given branch.
527//
528// GitLab API docs: https://docs.gitlab.com/ee/api/commits.html#revert-a-commit
529func (s *CommitsService) RevertCommit(pid interface{}, sha string, opt *RevertCommitOptions, options ...OptionFunc) (*Commit, *Response, error) {
530 project, err := parseID(pid)
531 if err != nil {
532 return nil, nil, err
533 }
534 u := fmt.Sprintf("projects/%s/repository/commits/%s/revert", pathEscape(project), sha)
535
536 req, err := s.client.NewRequest("POST", u, opt, options)
537 if err != nil {
538 return nil, nil, err
539 }
540
541 c := new(Commit)
542 resp, err := s.client.Do(req, &c)
543 if err != nil {
544 return nil, resp, err
545 }
546
547 return c, resp, err
548}
549
550// GPGSignature represents a Gitlab commit's GPG Signature.
551//
552// GitLab API docs:
553// https://docs.gitlab.com/ee/api/commits.html#get-gpg-signature-of-a-commit
554type GPGSignature struct {
555 KeyID int `json:"gpg_key_id"`
556 KeyPrimaryKeyID string `json:"gpg_key_primary_keyid"`
557 KeyUserName string `json:"gpg_key_user_name"`
558 KeyUserEmail string `json:"gpg_key_user_email"`
559 VerificationStatus string `json:"verification_status"`
560 KeySubkeyID int `json:"gpg_key_subkey_id"`
561}
562
563// GetGPGSiganature gets a GPG signature of a commit.
564//
565// GitLab API docs: https://docs.gitlab.com/ee/api/commits.html#get-gpg-signature-of-a-commit
566func (s *CommitsService) GetGPGSiganature(pid interface{}, sha string, options ...OptionFunc) (*GPGSignature, *Response, error) {
567 project, err := parseID(pid)
568 if err != nil {
569 return nil, nil, err
570 }
571 u := fmt.Sprintf("projects/%s/repository/commits/%s/signature", pathEscape(project), sha)
572
573 req, err := s.client.NewRequest("GET", u, nil, options)
574 if err != nil {
575 return nil, nil, err
576 }
577
578 sig := new(GPGSignature)
579 resp, err := s.client.Do(req, &sig)
580 if err != nil {
581 return nil, resp, err
582 }
583
584 return sig, resp, err
585}