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    g.revparse('v2.5:Makefile')
  59
  60    g.branches # returns Git::Branch objects
  61    g.branches.local
  62    g.branches.remote
  63    g.branches[:master].gcommit
  64    g.branches['origin/master'].gcommit
  65
  66    g.grep('hello')  # implies HEAD
  67    g.blob('v2.5:Makefile').grep('hello')
  68    g.tag('v2.5').grep('hello', 'docs/')
  69
  70    g.diff(commit1, commit2).size
  71    g.diff(commit1, commit2).stats
  72    g.gtree('v2.5').diff('v2.6').insertions
  73    g.diff('gitsearch1', 'v2.5').path('lib/')
  74    g.diff('gitsearch1', @git.gtree('v2.5'))
  75    g.diff('gitsearch1', 'v2.5').path('docs/').patch
  76    g.gtree('v2.5').diff('v2.6').patch
  77
  78    g.gtree('v2.5').diff('v2.6').each do |file_diff|
  79      puts file_diff.path
  80      puts file_diff.patch
  81      puts file_diff.blob(:src).contents
  82    end
  83
  84    g.config('user.name')  # returns 'Scott Chacon'
  85    g.config # returns whole config hash
  86
  87    g.tag # returns array of Git::Tag objects
  88
  89
  90
  91 And here are the operations that will need to write to your git repository.
  92
  93
  94    g = Git.init
  95      Git.init('project')
  96      Git.init('/home/schacon/proj',
  97                   { :git_dir => '/opt/git/proj.git',
  98                      :index_file => '/tmp/index'} )
  99
 100    g = Git.clone(URI, :name => 'name', :path => '/tmp/checkout')
 101    g.config('user.name', 'Scott Chacon')
 102    g.config('user.email', 'email@email.com')
 103
 104    g.add('.')
 105    g.add([file1, file2])
 106
 107    g.remove('file.txt')
 108    g.remove(['file.txt', 'file2.txt'])
 109
 110    g.commit('message')
 111    g.commit_all('message')
 112
 113    g = Git.clone(repo, 'myrepo')
 114    g.chdir do
 115     new_file('test-file', 'blahblahblah')
 116     g.status.changed.each do |file|
 117      puts file.blob(:index).contents
 118     end
 119    end
 120
 121    g.reset # defaults to HEAD
 122    g.reset_hard(Git::Commit)
 123
 124    g.branch('new_branch') # creates new or fetches existing
 125    g.branch('new_branch').checkout
 126    g.branch('new_branch').delete
 127    g.branch('existing_branch').checkout
 128
 129    g.checkout('new_branch')
 130    g.checkout(g.branch('new_branch'))
 131
 132    g.branch(name).merge(branch2)
 133    g.branch(branch2).merge  # merges HEAD with branch2
 134
 135    g.branch(name).in_branch(message) { # add files }  # auto-commits
 136    g.merge('new_branch')
 137    g.merge('origin/remote_branch')
 138    g.merge(b.branch('master'))
 139    g.merge([branch1, branch2])
 140
 141    r = g.add_remote(name, uri)  # Git::Remote
 142    r = g.add_remote(name, Git::Base)  # Git::Remote
 143
 144    g.remotes  # array of Git::Remotes
 145    g.remote(name).fetch
 146    g.remote(name).remove
 147    g.remote(name).merge
 148    g.remote(name).merge(branch)
 149
 150    g.fetch
 151    g.fetch(g.remotes.first)
 152
 153    g.pull
 154    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 155
 156    g.add_tag('tag_name') # returns Git::Tag
 157
 158    g.repack
 159
 160    g.push
 161    g.push(g.remote('name'))