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 Many of the simple read-only operations have already been
  23 moved to pure ruby.
  24
  25 = Major Objects
  26
  27 Git::Base - this is the object returned from a Git.open or Git.clone.
  28 Most major actions are called from this object.
  29
  30 Git::Object - this is the base object for your tree, blob and commit objects,
  31 returned from @git.gtree or @git.object calls.  the Git::AbstractObject will
  32 have most of the calls in common for all those objects.
  33
  34 Git::Diff - returns from a @git.diff command.  It is an Enumerable that returns
  35 Git::Diff:DiffFile objects from which you can get per file patches and insertion/deletion
  36 statistics.  You can also get total statistics from the Git::Diff object directly.
  37
  38 Git::Status - returns from a @git.status command.  It is an Enumerable that returns
  39 Git:Status::StatusFile objects for each object in git, which includes files in the working
  40 directory, in the index and in the repository.  Similar to running 'git status' on the command
  41 line to determine untracked and changed files.
  42
  43 Git::Branches - Enumerable object that holds Git::Branch objects.  You can call .local or .remote
  44 on it to filter to just your local or remote branches.
  45
  46 Git::Remote - A reference to a remote repository that is tracked by this repository.
  47
  48 Git::Log - An Enumerable object that references all the Git::Object::Commit objects that encompass
  49 your log query, which can be constructed through methods on the Git::Log object, like:
  50
  51  @git.log(20).object("HEAD^").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] }
  52
  53 = Gitr
  54
  55 I have included a command line pure-ruby git client called 'gitr'
  56
  57 The following commands are available - they all will run in pure ruby, without forking out the the git binary.
  58 In fact, they can be run on a machine without git compiled on it.
  59
  60 commands: log
  61           log-shas
  62           cat-file (treeish)
  63           rev-parse (treeish)
  64           branches
  65           config
  66           ls-tree (tree)
  67
  68
  69 = Examples
  70
  71 Here are a bunch of examples of how to use the Ruby/Git package.
  72
  73 First you have to remember to require rubygems if it's not.  Then include the 'git' gem.
  74
  75    require 'rubygems'
  76    require 'git'
  77
  78 Here are the operations that need read permission only.
  79
  80    g = Git.open (working_dir, :log => Logger.new(STDOUT))
  81
  82    g.index
  83    g.index.readable?
  84    g.index.writable?
  85    g.repo
  86    g.dir
  87
  88    g.log   # returns array of Git::Commit objects
  89    g.log.since('2 weeks ago')
  90    g.log.between('v2.5', 'v2.6')
  91    g.log.each {|l| puts l.sha }
  92    g.gblob('v2.5:Makefile').log.since('2 weeks ago')
  93
  94    g.object('HEAD^').to_s  # git show / git rev-parse
  95    g.object('HEAD^').contents
  96    g.object('v2.5:Makefile').size
  97    g.object('v2.5:Makefile').sha
  98
  99    g.gtree(treeish)
 100    g.gblob(treeish)
 101    g.gcommit(treeish)
 102
 103
 104    commit = g.gcommit('1cc8667014381')
 105     commit.gtree
 106     commit.parent.sha
 107     commit.parents.size
 108     commit.author.name
 109     commit.author.email
 110     commit.author.date.strftime("%m-%d-%y")
 111     commit.committer.name
 112     commit.date.strftime("%m-%d-%y")
 113     commit.message
 114
 115   tree = g.gtree("HEAD^{tree}")
 116     tree.blobs
 117     tree.subtrees
 118     tree.children # blobs and subtrees
 119
 120    g.revparse('v2.5:Makefile')
 121
 122    g.branches # returns Git::Branch objects
 123    g.branches.local
 124    g.branches.remote
 125    g.branches[:master].gcommit
 126    g.branches['origin/master'].gcommit
 127
 128    g.grep('hello')  # implies HEAD
 129    g.blob('v2.5:Makefile').grep('hello')
 130    g.tag('v2.5').grep('hello', 'docs/')
 131
 132    g.diff(commit1, commit2).size
 133    g.diff(commit1, commit2).stats
 134    g.gtree('v2.5').diff('v2.6').insertions
 135    g.diff('gitsearch1', 'v2.5').path('lib/')
 136    g.diff('gitsearch1', @git.gtree('v2.5'))
 137    g.diff('gitsearch1', 'v2.5').path('docs/').patch
 138    g.gtree('v2.5').diff('v2.6').patch
 139
 140    g.gtree('v2.5').diff('v2.6').each do |file_diff|
 141      puts file_diff.path
 142      puts file_diff.patch
 143      puts file_diff.blob(:src).contents
 144    end
 145
 146    g.config('user.name')  # returns 'Scott Chacon'
 147    g.config # returns whole config hash
 148
 149    g.tag # returns array of Git::Tag objects
 150
 151
 152
 153 And here are the operations that will need to write to your git repository.
 154
 155
 156    g = Git.init
 157      Git.init('project')
 158      Git.init('/home/schacon/proj',
 159                   { :git_dir => '/opt/git/proj.git',
 160                      :index_file => '/tmp/index'} )
 161
 162    g = Git.clone(URI, :name => 'name', :path => '/tmp/checkout')
 163    g.config('user.name', 'Scott Chacon')
 164    g.config('user.email', 'email@email.com')
 165
 166    g.add('.')
 167    g.add([file1, file2])
 168
 169    g.remove('file.txt')
 170    g.remove(['file.txt', 'file2.txt'])
 171
 172    g.commit('message')
 173    g.commit_all('message')
 174
 175    g = Git.clone(repo, 'myrepo')
 176    g.chdir do
 177     new_file('test-file', 'blahblahblah')
 178     g.status.changed.each do |file|
 179      puts file.blob(:index).contents
 180     end
 181    end
 182
 183    g.reset # defaults to HEAD
 184    g.reset_hard(Git::Commit)
 185
 186    g.branch('new_branch') # creates new or fetches existing
 187    g.branch('new_branch').checkout
 188    g.branch('new_branch').delete
 189    g.branch('existing_branch').checkout
 190
 191    g.checkout('new_branch')
 192    g.checkout(g.branch('new_branch'))
 193
 194    g.branch(name).merge(branch2)
 195    g.branch(branch2).merge  # merges HEAD with branch2
 196
 197    g.branch(name).in_branch(message) { # add files }  # auto-commits
 198    g.merge('new_branch')
 199    g.merge('origin/remote_branch')
 200    g.merge(b.branch('master'))
 201    g.merge([branch1, branch2])
 202
 203    r = g.add_remote(name, uri)  # Git::Remote
 204    r = g.add_remote(name, Git::Base)  # Git::Remote
 205
 206    g.remotes  # array of Git::Remotes
 207    g.remote(name).fetch
 208    g.remote(name).remove
 209    g.remote(name).merge
 210    g.remote(name).merge(branch)
 211
 212    g.fetch
 213    g.fetch(g.remotes.first)
 214
 215    g.pull
 216    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 217
 218    g.add_tag('tag_name') # returns Git::Tag
 219
 220    g.repack
 221
 222    g.push
 223    g.push(g.remote('name'))
 224
 225
 226 Some examples of more low-level index and tree operations
 227
 228    g.with_temp_index do
 229
 230      g.read_tree(tree3) # calls self.index.read_tree
 231      g.read_tree(tree1, :prefix => 'hi/')
 232
 233      c = g.commit_tree('message')
 234      # or #
 235      t = g.write_tree
 236      c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
 237
 238      g.branch('branch_name').update_ref(c)
 239      g.update_ref(branch, c)
 240
 241      g.with_temp_working do # new blank working directory
 242        g.checkout
 243        g.checkout(another_index)
 244        g.commit # commits to temp_index
 245      end
 246    end
 247
 248    g.set_index('/path/to/index')
 249
 250
 251    g.with_index(path) do
 252      # calls set_index, then switches back after
 253    end
 254
 255    g.with_working(dir) do
 256    # calls set_working, then switches back after
 257    end
 258
 259    g.with_temp_working(dir) do
 260      g.checkout_index(:prefix => dir, :path_limiter => path)
 261      # do file work
 262      g.commit # commits to index
 263    end
 264