1 == Git Library for Ruby
3 Library for using Git in Ruby.
7 The Ruby/Git homepage is currently at :
9 http://jointheconversation.org/rubygit
11 Git public hosting of the project source code is at:
13 http://repo.or.cz/w/rubygit.git
17 Right now I'm forking calls to the 'git' binary,
18 but eventually I'll replace that with either C bindings
19 to libgit or libgit-thin, or I'll write pure ruby
20 handlers for at least some of the Git stuff.
24 Git::Base - this is the object returned from a Git.open or Git.clone.
25 Most major actions are called from this object.
27 Git::Object - this is the base object for your tree, blob and commit objects,
28 returned from @git.gtree or @git.object calls. the Git::AbstractObject will
29 have most of the calls in common for all those objects.
31 Git::Diff - returns from a @git.diff command. It is an Enumerable that returns
32 Git::Diff:DiffFile objects from which you can get per file patches and insertion/deletion
33 statistics. You can also get total statistics from the Git::Diff object directly.
35 Git::Status - returns from a @git.status command. It is an Enumerable that returns
36 Git:Status::StatusFile objects for each object in git, which includes files in the working
37 directory, in the index and in the repository. Similar to running 'git status' on the command
38 line to determine untracked and changed files.
40 Git::Branches - Enumerable object that holds Git::Branch objects. You can call .local or .remote
41 on it to filter to just your local or remote branches.
43 Git::Remote - A reference to a remote repository that is tracked by this repository.
45 Git::Log - An Enumerable object that references all the Git::Object::Commit objects that encompass
46 your log query, which can be constructed through methods on the Git::Log object, like:
48 @git.log(20).object("HEAD^").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }
53 Here are a bunch of examples of how to use the Ruby/Git package.
55 First you have to remember to require rubygems if it's not. Then include the 'git' gem.
60 Here are the operations that need read permission only.
62 g = Git.open (working_dir, :log => Logger.new(STDOUT))
70 g.log # returns array of Git::Commit objects
71 g.log.since('2 weeks ago')
72 g.log.between('v2.5', 'v2.6')
73 g.log.each {|l| puts l.sha }
74 g.gblob('v2.5:Makefile').log.since('2 weeks ago')
76 g.object('HEAD^').to_s # git show / git rev-parse
77 g.object('HEAD^').contents
78 g.object('v2.5:Makefile').size
79 g.object('v2.5:Makefile').sha
86 commit = g.gcommit('1cc8667014381')
92 commit.author.date.strftime("%m-%d-%y")
94 commit.date.strftime("%m-%d-%y")
97 tree = g.gtree("HEAD^{tree}")
100 tree.children # blobs and subtrees
102 g.revparse('v2.5:Makefile')
104 g.branches # returns Git::Branch objects
107 g.branches[:master].gcommit
108 g.branches['origin/master'].gcommit
110 g.grep('hello') # implies HEAD
111 g.blob('v2.5:Makefile').grep('hello')
112 g.tag('v2.5').grep('hello', 'docs/')
114 g.diff(commit1, commit2).size
115 g.diff(commit1, commit2).stats
116 g.gtree('v2.5').diff('v2.6').insertions
117 g.diff('gitsearch1', 'v2.5').path('lib/')
118 g.diff('gitsearch1', @git.gtree('v2.5'))
119 g.diff('gitsearch1', 'v2.5').path('docs/').patch
120 g.gtree('v2.5').diff('v2.6').patch
122 g.gtree('v2.5').diff('v2.6').each do |file_diff|
125 puts file_diff.blob(:src).contents
128 g.config('user.name') # returns 'Scott Chacon'
129 g.config # returns whole config hash
131 g.tag # returns array of Git::Tag objects
135 And here are the operations that will need to write to your git repository.
140 Git.init('/home/schacon/proj',
141 { :git_dir => '/opt/git/proj.git',
142 :index_file => '/tmp/index'} )
144 g = Git.clone(URI, :name => 'name', :path => '/tmp/checkout')
145 g.config('user.name', 'Scott Chacon')
146 g.config('user.email', 'email@email.com')
149 g.add([file1, file2])
152 g.remove(['file.txt', 'file2.txt'])
155 g.commit_all('message')
157 g = Git.clone(repo, 'myrepo')
159 new_file('test-file', 'blahblahblah')
160 g.status.changed.each do |file|
161 puts file.blob(:index).contents
165 g.reset # defaults to HEAD
166 g.reset_hard(Git::Commit)
168 g.branch('new_branch') # creates new or fetches existing
169 g.branch('new_branch').checkout
170 g.branch('new_branch').delete
171 g.branch('existing_branch').checkout
173 g.checkout('new_branch')
174 g.checkout(g.branch('new_branch'))
176 g.branch(name).merge(branch2)
177 g.branch(branch2).merge # merges HEAD with branch2
179 g.branch(name).in_branch(message) { # add files } # auto-commits
180 g.merge('new_branch')
181 g.merge('origin/remote_branch')
182 g.merge(b.branch('master'))
183 g.merge([branch1, branch2])
185 r = g.add_remote(name, uri) # Git::Remote
186 r = g.add_remote(name, Git::Base) # Git::Remote
188 g.remotes # array of Git::Remotes
190 g.remote(name).remove
192 g.remote(name).merge(branch)
195 g.fetch(g.remotes.first)
198 g.pull(Git::Repo, Git::Branch) # fetch and a merge
200 g.add_tag('tag_name') # returns Git::Tag
205 g.push(g.remote('name'))
208 Some examples of more low-level index and tree operations
212 g.read_tree(tree3) # calls self.index.read_tree
213 g.read_tree(tree1, :prefix => 'hi/')
215 c = g.commit_tree('message')
218 c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
220 g.branch('branch_name').update_ref(c)
221 g.update_ref(branch, c)
223 g.with_temp_working do # new blank working directory
225 g.checkout(another_index)
226 g.commit # commits to temp_index
230 g.set_index('/path/to/index')
233 g.with_index(path) do
234 # calls set_index, then switches back after
237 g.with_working(dir) do
238 # calls set_working, then switches back after
241 g.with_temp_working(dir) do
242 g.checkout_index(:prefix => dir, :path_limiter => path)
244 g.commit # commits to index