README.md 6.31 KB
Newer Older
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
1
# GitLab Git
2

Denys Vitali's avatar
Denys Vitali committed
3
## `Gitlab::Git` has been absorbed into the [main GitLab project](https://gitlab.com/gitlab-org/gitlab-ce), and the `gitlab_git` gem has been deprecated. See the [gitlab-ce issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/24374) and [merge request](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8447) for more information.
4

5
GitLab wrapper around git objects.
6

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
7
[![build status](https://gitlab.com/gitlab-org/gitlab_git/badges/master/build.svg)](https://gitlab.com/gitlab-org/gitlab_git/commits/master)
8 9
[![Gem Version](https://badge.fury.io/rb/gitlab_git.svg)](http://badge.fury.io/rb/gitlab_git)

10
## Moved from Grit to Rugged
11

12
GitLab Git used grit as main library in past. Now it uses rugged
13

14
## How to use
15

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
16
### Repository
17

18
    # Init repo with full path
19
    repo = Gitlab::Git::Repository.new('/home/git/repositories/gitlab/gitlab-ci.git')
20

21
    repo.path
22 23
    # "/home/git/repositories/gitlab/gitlab-ci.git"

24 25 26
    repo.name
    # "gitlab-ci.git"

27 28 29 30 31 32 33 34 35 36 37 38 39 40
    # Get branches and tags
    repo.branches
    repo.tags

    # Get branch or tag names
    repo.branch_names
    repo.tag_names

    # Archive repo to `/tmp` dir
    repo.archive_repo('master', '/tmp')

    # Bare repo size in MB.
    repo.size
    # 10.43
41

42 43 44
    # Search for code
    repo.search_files('rspec', 'master')
    # [ <Gitlab::Git::BlobSnippet:0x000..>, <Gitlab::Git::BlobSnippet:0x000..>]
45

Vinnie Okada's avatar
Vinnie Okada committed
46 47
    # Access to rugged repo object
    repo.rugged
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
48

49 50 51 52
### Specs

In case it's needed to update https://gitlab.com/gitlab-org/gitlab-git-test with new content changes the developer should update `spec/support/last_commit.rb` with the updated sha of the last commit and the required information. The developer should also run the full set of tests to check which ones are failing and fix them accordingly.

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
53
### Tree
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
54

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
55 56
    # Tree objects for root dir
    tree = Gitlab::Git::Tree.where(repo, '893ade32')
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
57

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
58
    # Tree objects for sub dir
59
    tree = Gitlab::Git::Tree.where(repo, '893ade32', 'app/models/')
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
60

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
61 62 63 64
    # [
    #   #<Gitlab::Git::Tree:0x00000002b2ed80 @id="38f45392ae61f0effa84048f208a81019cc306bb", @name="lib", @path="projects/lib", @type=:tree, @mode="040000", @commit_id="8470d70da67355c9c009e4401746b1d5410af2e3">
    #   #<Gitlab::Git::Tree:0x00000002b2ed80 @id="32a45392ae61f0effa84048f208a81019cc306bb", @name="sample.rb", @path="projects/sample.rb", @type=:blob, @mode="040000", @commit_id="8470d70da67355c9c009e4401746b1d5410af2e3">
    # ]
65

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
66 67 68 69 70
    dir = tree.first
    dir.name # lib
    dir.type # :tree
    dir.dir? # true
    dir.file? # false
71

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
72 73 74 75 76
    file = tree.last
    file.name # sample.rb
    file.type # :blob
    file.dir? # false
    file.file? # true
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
77

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
78 79
    # Select only files for tree
    tree.select(&:file?)
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
80

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
81 82
    # Find readme
    tree.find(&:readme?)
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
83

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
84
### Blob
85 86 87 88

    # Blob object for Commit sha 893ade32
    blob = Gitlab::Git::Blob.find(repo, '893ade32', 'Gemfile')

89
    # Attributes
90 91 92
    blob.id
    blob.name
    blob.size
93
    blob.data # contains only a fragment of the blob's data to save memory
94 95 96 97
    blob.mode
    blob.path
    blob.commit_id

98 99 100
    # Load all blob data into memory
    blob.load_all_data!(repo)

101 102 103 104 105 106 107 108
    # Blob object with sha 8a3f8ddcf3536628c9670d41e67a785383eded1d
    raw_blob = Gitlab::Git::Blob.raw(repo, '8a3f8ddcf3536628c9670d41e67a785383eded1d')

    # Attributes for raw blobs are more limited
    raw_blob.id
    raw_blob.size
    raw_blob.data

109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
#### Commiting blob

    options = {
       file: {
         content: 'Lorem ipsum...',
         path: 'documents/story.txt'
       },
       author: {
         email: 'user@example.com',
         name: 'Test User',
         time: Time.now
       },
       committer: {
         email: 'user@example.com',
         name: 'Test User',
         time: Time.now
       },
       commit: {
         message: 'Wow such commit',
         branch: 'master'
       }
    }

132
    # Create or update file in repository.
133 134 135 136
    # Returns sha of commit that did a change
    Gitlab::Git::Blob.commit(repository, commit_options)


Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
137
### Commit
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
138

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
139
#### Picking
140

141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
    # Get commits collection with pagination
    Gitlab::Git::Commit.where(
      repo: repo,
      ref: 'master',
      path: 'app/models',
      limit: 10,
      offset: 5,
    )

    # Find single commit
    Gitlab::Git::Commit.find(repo, '29eda46b')
    Gitlab::Git::Commit.find(repo, 'v2.4.6')

    # Get last commit for HEAD
    commit = Gitlab::Git::Commit.last(repo)

    # Get last commit for specified file/directory
Chris Barber's avatar
Chris Barber committed
158
    Gitlab::Git::Commit.last_for_path(repo, '29eda46b', 'app/models')
159 160 161 162

    # Commits between branches
    Gitlab::Git::Commit.between(repo, 'dev', 'master')
    # [ <Gitlab::Git::Commit:0x000..>, <Gitlab::Git::Commit:0x000..>]
163

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
164
#### Commit object
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
165

166 167 168 169
    # Commit id
    commit.id
    commit.sha
    # ba8812a2de5e5ea191da6930a8ee1965873286e3
170

171 172
    commit.short_id
    # ba8812a2de
173

174 175 176
    commit.message
    commit.safe_message
    # Fix bug 891
177

178 179
    commit.parent_id
    # ba8812a2de5e5ea191da6930a8ee1965873286e3
180

181 182
    commit.diffs
    # [ <Gitlab::Git::Diff:0x000..>, <Gitlab::Git::Diff:0x000..>]
183

184 185 186 187
    commit.created_at
    commit.authored_date
    commit.committed_date
    # 2013-07-03 22:11:26 +0300
188

189 190 191 192 193 194 195
    commit.committer_name
    commit.author_name
    # John Smith

    commit.committer_email
    commit.author_email
    # jsmith@sample.com
196

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
197
### Diff object
198

199 200 201
    # From commit
    commit.diffs
    # [ <Gitlab::Git::Diff:0x000..>, <Gitlab::Git::Diff:0x000..>]
202

203 204 205
    # Diff between several commits
    Gitlab::Git::Diff.between(repo, 'dev', 'master')
    # [ <Gitlab::Git::Diff:0x000..>, <Gitlab::Git::Diff:0x000..>]
206

207 208
    # Diff object
    diff = commit.diffs.first
209

210 211 212 213 214 215 216 217
    diff.diff #  "--- a/Gemfile.lock\....."
    diff.new_path # => "Gemfile.lock",
    diff.old_path # => "Gemfile.lock",
    diff.a_mode # => nil,
    diff.b_mode # => "100644",
    diff.new_file # => false,
    diff.renamed_file # => false,
    diff.deleted_file # => false
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
218 219

### Git blame
220

221 222 223 224 225 226
    # Git blame for file
    blame = Gitlab::Git::Blame.new(repo, 'master, 'app/models/project.rb')
    blame.each do |commit, lines|
      commit # <Gitlab::Git::Commit:0x000..>
      lines # ['class Project', 'def initialize']
    end
227

Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
228
### Compare
229

230
Allows you to get difference (commits, diffs) between two SHA/branch/tag:
231

232
    compare = Gitlab::Git::Compare.new(repo, 'v4.3.2', 'master')
233

234 235 236 237 238
    compare.commits
    # [ <Gitlab::Git::Commit:0x000..>, <Gitlab::Git::Commit:0x000..>]

    compare.diffs
    # [ <Gitlab::Git::Diff:0x000..>, <Gitlab::Git::Diff:0x000..>]