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 = Major Objects
  23
  24 Git::Base - this is the object returned from a Git.open or Git.clone.
  25 Most major actions are called from this object.
  26
  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.
  30
  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.
  34
  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.
  39
  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.
  42
  43 Git::Remote - A reference to a remote repository that is tracked by this repository.
  44
  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:
  47
  48  @git.log(20).object("HEAD^").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }
  49
  50
  51 = Examples
  52
  53 Here are a bunch of examples of how to use the Ruby/Git package.
  54
  55 First you have to remember to require rubygems if it's not.  Then include the 'git' gem.
  56
  57    require 'rubygems'
  58    require 'git'
  59
  60 Here are the operations that need read permission only.
  61
  62    g = Git.open (working_dir, :log => Logger.new(STDOUT))
  63
  64    g.index
  65    g.index.readable?
  66    g.index.writable?
  67    g.repo
  68    g.dir
  69
  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')
  75
  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
  80
  81    g.gtree(treeish)
  82    g.gblob(treeish)
  83    g.gcommit(treeish)
  84
  85
  86    commit = g.gcommit('1cc8667014381')
  87     commit.gtree
  88     commit.parent.sha
  89     commit.parents.size
  90     commit.author.name
  91     commit.author.email
  92     commit.author.date.strftime("%m-%d-%y")
  93     commit.committer.name
  94     commit.date.strftime("%m-%d-%y")
  95     commit.message
  96
  97   tree = g.gtree("HEAD^{tree}")
  98     tree.blobs
  99     tree.subtrees
 100     tree.children # blobs and subtrees
 101
 102    g.revparse('v2.5:Makefile')
 103
 104    g.branches # returns Git::Branch objects
 105    g.branches.local
 106    g.branches.remote
 107    g.branches[:master].gcommit
 108    g.branches['origin/master'].gcommit
 109
 110    g.grep('hello')  # implies HEAD
 111    g.blob('v2.5:Makefile').grep('hello')
 112    g.tag('v2.5').grep('hello', 'docs/')
 113
 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
 121
 122    g.gtree('v2.5').diff('v2.6').each do |file_diff|
 123      puts file_diff.path
 124      puts file_diff.patch
 125      puts file_diff.blob(:src).contents
 126    end
 127
 128    g.config('user.name')  # returns 'Scott Chacon'
 129    g.config # returns whole config hash
 130
 131    g.tag # returns array of Git::Tag objects
 132
 133
 134
 135 And here are the operations that will need to write to your git repository.
 136
 137
 138    g = Git.init
 139      Git.init('project')
 140      Git.init('/home/schacon/proj',
 141                   { :git_dir => '/opt/git/proj.git',
 142                      :index_file => '/tmp/index'} )
 143
 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')
 147
 148    g.add('.')
 149    g.add([file1, file2])
 150
 151    g.remove('file.txt')
 152    g.remove(['file.txt', 'file2.txt'])
 153
 154    g.commit('message')
 155    g.commit_all('message')
 156
 157    g = Git.clone(repo, 'myrepo')
 158    g.chdir do
 159     new_file('test-file', 'blahblahblah')
 160     g.status.changed.each do |file|
 161      puts file.blob(:index).contents
 162     end
 163    end
 164
 165    g.reset # defaults to HEAD
 166    g.reset_hard(Git::Commit)
 167
 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
 172
 173    g.checkout('new_branch')
 174    g.checkout(g.branch('new_branch'))
 175
 176    g.branch(name).merge(branch2)
 177    g.branch(branch2).merge  # merges HEAD with branch2
 178
 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])
 184
 185    r = g.add_remote(name, uri)  # Git::Remote
 186    r = g.add_remote(name, Git::Base)  # Git::Remote
 187
 188    g.remotes  # array of Git::Remotes
 189    g.remote(name).fetch
 190    g.remote(name).remove
 191    g.remote(name).merge
 192    g.remote(name).merge(branch)
 193
 194    g.fetch
 195    g.fetch(g.remotes.first)
 196
 197    g.pull
 198    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 199
 200    g.add_tag('tag_name') # returns Git::Tag
 201
 202    g.repack
 203
 204    g.push
 205    g.push(g.remote('name'))
 206
 207
 208 Some examples of more low-level index and tree operations
 209
 210    g.with_temp_index do
 211
 212      g.read_tree(tree3) # calls self.index.read_tree
 213      g.read_tree(tree1, :prefix => 'hi/')
 214
 215      c = g.commit_tree('message')
 216      # or #
 217      t = g.write_tree
 218      c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
 219
 220      g.branch('branch_name').update_ref(c)
 221      g.update_ref(branch, c)
 222
 223      g.with_temp_working do # new blank working directory
 224        g.checkout
 225        g.checkout(another_index)
 226        g.commit # commits to temp_index
 227      end
 228    end
 229
 230    g.set_index('/path/to/index')
 231
 232
 233    g.with_index(path) do
 234      # calls set_index, then switches back after
 235    end
 236
 237    g.with_working(dir) do
 238    # calls set_working, then switches back after
 239    end
 240
 241    g.with_temp_working(dir) do
 242      g.checkout_index(:prefix => dir, :path_limiter => path)
 243      # do file work
 244      g.commit # commits to index
 245    end
 246