README

   1 == Git Library for Ruby
   2
   3 Library for using Git in Ruby.
   4
   5 = Homepage
   6
   7 The Ruby/Git homepage is currently at :
   8
   9 http://jointheconversation.org/rubygit
  10
  11 Git public hosting of the project source code is at:
  12
  13 http://repo.or.cz/w/rubygit.git
  14
  15 = Roadmap
  16
  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.
  21
  22
  23 = Examples
  24
  25 Here are a bunch of examples of how to use the Ruby/Git package.
  26
  27 First you have to remember to require rubygems if it's not.  Then include the 'git' gem.
  28
  29    require 'rubygems'
  30    require 'git'
  31
  32 Here are the operations that need read permission only.
  33
  34    g = Git.open (working_dir = '.')
  35           (git_dir, index_file)
  36
  37    g.index
  38    g.index.readable?
  39    g.index.writable?
  40    g.repo
  41    g.dir
  42
  43    g.log   # returns array of Git::Commit objects
  44    g.log.since('2 weeks ago')
  45    g.log.between('v2.5', 'v2.6')
  46    g.log.each {|l| puts l.sha }
  47    g.gblob('v2.5:Makefile').log.since('2 weeks ago')
  48
  49    g.object('HEAD^').to_s  # git show / git rev-parse
  50    g.object('HEAD^').contents
  51    g.object('v2.5:Makefile').size
  52    g.object('v2.5:Makefile').sha
  53
  54    g.gtree(treeish)
  55    g.gblob(treeish)
  56    g.gcommit(treeish)
  57
  58
  59    commit = g.gcommit('1cc8667014381')
  60     commit.gtree
  61     commit.parent.sha
  62     commit.parents.size
  63     commit.author.name
  64     commit.author.email
  65     commit.author.date.strftime("%m-%d-%y")
  66     commit.committer.name
  67     commit.date.strftime("%m-%d-%y")
  68     commit.message
  69
  70   tree = g.gtree("HEAD^{tree}")
  71     tree.blobs
  72     tree.subtrees
  73     tree.children # blobs and subtrees
  74
  75    g.revparse('v2.5:Makefile')
  76
  77    g.branches # returns Git::Branch objects
  78    g.branches.local
  79    g.branches.remote
  80    g.branches[:master].gcommit
  81    g.branches['origin/master'].gcommit
  82
  83    g.grep('hello')  # implies HEAD
  84    g.blob('v2.5:Makefile').grep('hello')
  85    g.tag('v2.5').grep('hello', 'docs/')
  86
  87    g.diff(commit1, commit2).size
  88    g.diff(commit1, commit2).stats
  89    g.gtree('v2.5').diff('v2.6').insertions
  90    g.diff('gitsearch1', 'v2.5').path('lib/')
  91    g.diff('gitsearch1', @git.gtree('v2.5'))
  92    g.diff('gitsearch1', 'v2.5').path('docs/').patch
  93    g.gtree('v2.5').diff('v2.6').patch
  94
  95    g.gtree('v2.5').diff('v2.6').each do |file_diff|
  96      puts file_diff.path
  97      puts file_diff.patch
  98      puts file_diff.blob(:src).contents
  99    end
 100
 101    g.config('user.name')  # returns 'Scott Chacon'
 102    g.config # returns whole config hash
 103
 104    g.tag # returns array of Git::Tag objects
 105
 106
 107
 108 And here are the operations that will need to write to your git repository.
 109
 110
 111    g = Git.init
 112      Git.init('project')
 113      Git.init('/home/schacon/proj',
 114                   { :git_dir => '/opt/git/proj.git',
 115                      :index_file => '/tmp/index'} )
 116
 117    g = Git.clone(URI, :name => 'name', :path => '/tmp/checkout')
 118    g.config('user.name', 'Scott Chacon')
 119    g.config('user.email', 'email@email.com')
 120
 121    g.add('.')
 122    g.add([file1, file2])
 123
 124    g.remove('file.txt')
 125    g.remove(['file.txt', 'file2.txt'])
 126
 127    g.commit('message')
 128    g.commit_all('message')
 129
 130    g = Git.clone(repo, 'myrepo')
 131    g.chdir do
 132     new_file('test-file', 'blahblahblah')
 133     g.status.changed.each do |file|
 134      puts file.blob(:index).contents
 135     end
 136    end
 137
 138    g.reset # defaults to HEAD
 139    g.reset_hard(Git::Commit)
 140
 141    g.branch('new_branch') # creates new or fetches existing
 142    g.branch('new_branch').checkout
 143    g.branch('new_branch').delete
 144    g.branch('existing_branch').checkout
 145
 146    g.checkout('new_branch')
 147    g.checkout(g.branch('new_branch'))
 148
 149    g.branch(name).merge(branch2)
 150    g.branch(branch2).merge  # merges HEAD with branch2
 151
 152    g.branch(name).in_branch(message) { # add files }  # auto-commits
 153    g.merge('new_branch')
 154    g.merge('origin/remote_branch')
 155    g.merge(b.branch('master'))
 156    g.merge([branch1, branch2])
 157
 158    r = g.add_remote(name, uri)  # Git::Remote
 159    r = g.add_remote(name, Git::Base)  # Git::Remote
 160
 161    g.remotes  # array of Git::Remotes
 162    g.remote(name).fetch
 163    g.remote(name).remove
 164    g.remote(name).merge
 165    g.remote(name).merge(branch)
 166
 167    g.fetch
 168    g.fetch(g.remotes.first)
 169
 170    g.pull
 171    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 172
 173    g.add_tag('tag_name') # returns Git::Tag
 174
 175    g.repack
 176
 177    g.push
 178    g.push(g.remote('name'))