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 = '.')
  63           (git_dir, index_file)
  64
  65    g.index
  66    g.index.readable?
  67    g.index.writable?
  68    g.repo
  69    g.dir
  70
  71    g.log   # returns array of Git::Commit objects
  72    g.log.since('2 weeks ago')
  73    g.log.between('v2.5', 'v2.6')
  74    g.log.each {|l| puts l.sha }
  75    g.gblob('v2.5:Makefile').log.since('2 weeks ago')
  76
  77    g.object('HEAD^').to_s  # git show / git rev-parse
  78    g.object('HEAD^').contents
  79    g.object('v2.5:Makefile').size
  80    g.object('v2.5:Makefile').sha
  81
  82    g.gtree(treeish)
  83    g.gblob(treeish)
  84    g.gcommit(treeish)
  85
  86
  87    commit = g.gcommit('1cc8667014381')
  88     commit.gtree
  89     commit.parent.sha
  90     commit.parents.size
  91     commit.author.name
  92     commit.author.email
  93     commit.author.date.strftime("%m-%d-%y")
  94     commit.committer.name
  95     commit.date.strftime("%m-%d-%y")
  96     commit.message
  97
  98   tree = g.gtree("HEAD^{tree}")
  99     tree.blobs
 100     tree.subtrees
 101     tree.children # blobs and subtrees
 102
 103    g.revparse('v2.5:Makefile')
 104
 105    g.branches # returns Git::Branch objects
 106    g.branches.local
 107    g.branches.remote
 108    g.branches[:master].gcommit
 109    g.branches['origin/master'].gcommit
 110
 111    g.grep('hello')  # implies HEAD
 112    g.blob('v2.5:Makefile').grep('hello')
 113    g.tag('v2.5').grep('hello', 'docs/')
 114
 115    g.diff(commit1, commit2).size
 116    g.diff(commit1, commit2).stats
 117    g.gtree('v2.5').diff('v2.6').insertions
 118    g.diff('gitsearch1', 'v2.5').path('lib/')
 119    g.diff('gitsearch1', @git.gtree('v2.5'))
 120    g.diff('gitsearch1', 'v2.5').path('docs/').patch
 121    g.gtree('v2.5').diff('v2.6').patch
 122
 123    g.gtree('v2.5').diff('v2.6').each do |file_diff|
 124      puts file_diff.path
 125      puts file_diff.patch
 126      puts file_diff.blob(:src).contents
 127    end
 128
 129    g.config('user.name')  # returns 'Scott Chacon'
 130    g.config # returns whole config hash
 131
 132    g.tag # returns array of Git::Tag objects
 133
 134
 135
 136 And here are the operations that will need to write to your git repository.
 137
 138
 139    g = Git.init
 140      Git.init('project')
 141      Git.init('/home/schacon/proj',
 142                   { :git_dir => '/opt/git/proj.git',
 143                      :index_file => '/tmp/index'} )
 144
 145    g = Git.clone(URI, :name => 'name', :path => '/tmp/checkout')
 146    g.config('user.name', 'Scott Chacon')
 147    g.config('user.email', 'email@email.com')
 148
 149    g.add('.')
 150    g.add([file1, file2])
 151
 152    g.remove('file.txt')
 153    g.remove(['file.txt', 'file2.txt'])
 154
 155    g.commit('message')
 156    g.commit_all('message')
 157
 158    g = Git.clone(repo, 'myrepo')
 159    g.chdir do
 160     new_file('test-file', 'blahblahblah')
 161     g.status.changed.each do |file|
 162      puts file.blob(:index).contents
 163     end
 164    end
 165
 166    g.reset # defaults to HEAD
 167    g.reset_hard(Git::Commit)
 168
 169    g.branch('new_branch') # creates new or fetches existing
 170    g.branch('new_branch').checkout
 171    g.branch('new_branch').delete
 172    g.branch('existing_branch').checkout
 173
 174    g.checkout('new_branch')
 175    g.checkout(g.branch('new_branch'))
 176
 177    g.branch(name).merge(branch2)
 178    g.branch(branch2).merge  # merges HEAD with branch2
 179
 180    g.branch(name).in_branch(message) { # add files }  # auto-commits
 181    g.merge('new_branch')
 182    g.merge('origin/remote_branch')
 183    g.merge(b.branch('master'))
 184    g.merge([branch1, branch2])
 185
 186    r = g.add_remote(name, uri)  # Git::Remote
 187    r = g.add_remote(name, Git::Base)  # Git::Remote
 188
 189    g.remotes  # array of Git::Remotes
 190    g.remote(name).fetch
 191    g.remote(name).remove
 192    g.remote(name).merge
 193    g.remote(name).merge(branch)
 194
 195    g.fetch
 196    g.fetch(g.remotes.first)
 197
 198    g.pull
 199    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 200
 201    g.add_tag('tag_name') # returns Git::Tag
 202
 203    g.repack
 204
 205    g.push
 206    g.push(g.remote('name'))
 207
 208
 209 Some examples of more low-level index and tree operations
 210
 211    g.with_temp_index do
 212
 213      g.read_tree(tree3) # calls self.index.read_tree
 214      g.read_tree(tree1, :prefix => 'hi/')
 215
 216      c = g.commit_tree('message')
 217      # or #
 218      t = g.write_tree
 219      c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
 220
 221      g.branch('branch_name').update_ref(c)
 222      g.update_ref(branch, c)
 223
 224      g.with_temp_working do # new blank working directory
 225        g.checkout
 226        g.checkout(another_index)
 227        g.commit # commits to temp_index
 228      end
 229    end
 230
 231    g.set_index('/path/to/index')
 232
 233
 234    g.with_index(path) do
 235      # calls set_index, then switches back after
 236    end
 237
 238    g.with_working(dir) do
 239    # calls set_working, then switches back after
 240    end
 241
 242    g.with_temp_working(dir) do
 243      g.checkout_index(:prefix => dir, :path_limiter => path)
 244      # do file work
 245      g.commit # commits to index
 246    end
 247