doc/files/README.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html
   3      PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   4      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   5
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7 <head>
   8   <title>File: README</title>
   9   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  10   <meta http-equiv="Content-Script-Type" content="text/javascript" />
  11   <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
  12   <script type="text/javascript">
  13   // <![CDATA[
  14
  15   function popupCode( url ) {
  16     window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  17   }
  18
  19   function toggleCode( id ) {
  20     if ( document.getElementById )
  21       elem = document.getElementById( id );
  22     else if ( document.all )
  23       elem = eval( "document.all." + id );
  24     else
  25       return false;
  26
  27     elemStyle = elem.style;
  28
  29     if ( elemStyle.display != "block" ) {
  30       elemStyle.display = "block"
  31     } else {
  32       elemStyle.display = "none"
  33     }
  34
  35     return true;
  36   }
  37
  38   // Make codeblocks hidden by default
  39   document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  40
  41   // ]]>
  42   </script>
  43
  44 </head>
  45 <body>
  46
  47
  48
  49   <div id="fileHeader">
  50     <h1>README</h1>
  51     <table class="header-table">
  52     <tr class="top-aligned-row">
  53       <td><strong>Path:</strong></td>
  54       <td>README
  55       </td>
  56     </tr>
  57     <tr class="top-aligned-row">
  58       <td><strong>Last Update:</strong></td>
  59       <td>Tue Nov 13 06:53:10 PST 2007</td>
  60     </tr>
  61     </table>
  62   </div>
  63   <!-- banner header -->
  64
  65   <div id="bodyContent">
  66
  67
  68
  69   <div id="contextContent">
  70
  71     <div id="description">
  72       <h2><a href="../classes/Git.html">Git</a> Library for Ruby</h2>
  73 <p>
  74 Library for using <a href="../classes/Git.html">Git</a> in Ruby.
  75 </p>
  76 <h1>Homepage</h1>
  77 <p>
  78 The Ruby/<a href="../classes/Git.html">Git</a> homepage is currently at :
  79 </p>
  80 <p>
  81 <a
  82 href="http://jointheconversation.org/rubygit">jointheconversation.org/rubygit</a>
  83 </p>
  84 <p>
  85 <a href="../classes/Git.html">Git</a> public hosting of the project source
  86 code is at:
  87 </p>
  88 <p>
  89 <a href="http://repo.or.cz/w/rubygit.git">repo.or.cz/w/rubygit.git</a>
  90 </p>
  91 <h1>Roadmap</h1>
  92 <p>
  93 Right now I&#8217;m forking calls to the &#8216;git&#8217; binary, but
  94 eventually I&#8217;ll replace that with either C bindings to libgit or
  95 libgit-thin, or I&#8217;ll write pure ruby handlers for at least some of
  96 the <a href="../classes/Git.html">Git</a> stuff.
  97 </p>
  98 <h1>Major Objects</h1>
  99 <p>
 100 <a href="../classes/Git/Base.html">Git::Base</a> - this is the object
 101 returned from a <a href="../classes/Git.html#M000002">Git.open</a> or <a
 102 href="../classes/Git.html#M000004">Git.clone</a>. Most major actions are
 103 called from this object.
 104 </p>
 105 <p>
 106 <a href="../classes/Git/Object.html">Git::Object</a> - this is the base
 107 object for your tree, blob and commit objects, returned from @git.gtree or
 108 @git.object calls. the Git::AbstractObject will have most of the calls in
 109 common for all those objects.
 110 </p>
 111 <p>
 112 <a href="../classes/Git/Diff.html">Git::Diff</a> - returns from a @git.diff
 113 command. It is an Enumerable that returns <a
 114 href="../classes/Git/Diff.html">Git::Diff</a>:DiffFile objects from which
 115 you can get per file patches and insertion/deletion statistics. You can
 116 also get total statistics from the <a
 117 href="../classes/Git/Diff.html">Git::Diff</a> object directly.
 118 </p>
 119 <p>
 120 <a href="../classes/Git/Status.html">Git::Status</a>
 121 </p>
 122 <p>
 123 <a href="../classes/Git/Branches.html">Git::Branches</a>
 124 </p>
 125 <p>
 126 <a href="../classes/Git/Remote.html">Git::Remote</a>
 127 </p>
 128 <p>
 129 <a href="../classes/Git/Log.html">Git::Log</a>
 130 </p>
 131 <h1>Examples</h1>
 132 <p>
 133 Here are a bunch of examples of how to use the Ruby/<a
 134 href="../classes/Git.html">Git</a> package.
 135 </p>
 136 <p>
 137 First you have to remember to require rubygems if it&#8217;s not. Then
 138 include the &#8216;git&#8217; gem.
 139 </p>
 140 <pre>
 141    require 'rubygems'
 142    require 'git'
 143 </pre>
 144 <p>
 145 Here are the operations that need read permission only.
 146 </p>
 147 <pre>
 148    g = Git.open (working_dir = '.')
 149           (git_dir, index_file)
 150
 151    g.index
 152    g.index.readable?
 153    g.index.writable?
 154    g.repo
 155    g.dir
 156
 157    g.log   # returns array of Git::Commit objects
 158    g.log.since('2 weeks ago')
 159    g.log.between('v2.5', 'v2.6')
 160    g.log.each {|l| puts l.sha }
 161    g.gblob('v2.5:Makefile').log.since('2 weeks ago')
 162
 163    g.object('HEAD^').to_s  # git show / git rev-parse
 164    g.object('HEAD^').contents
 165    g.object('v2.5:Makefile').size
 166    g.object('v2.5:Makefile').sha
 167
 168    g.gtree(treeish)
 169    g.gblob(treeish)
 170    g.gcommit(treeish)
 171
 172    commit = g.gcommit('1cc8667014381')
 173     commit.gtree
 174     commit.parent.sha
 175     commit.parents.size
 176     commit.author.name
 177     commit.author.email
 178     commit.author.date.strftime(&quot;%m-%d-%y&quot;)
 179     commit.committer.name
 180     commit.date.strftime(&quot;%m-%d-%y&quot;)
 181     commit.message
 182
 183   tree = g.gtree(&quot;HEAD^{tree}&quot;)
 184     tree.blobs
 185     tree.subtrees
 186     tree.children # blobs and subtrees
 187
 188    g.revparse('v2.5:Makefile')
 189
 190    g.branches # returns Git::Branch objects
 191    g.branches.local
 192    g.branches.remote
 193    g.branches[:master].gcommit
 194    g.branches['origin/master'].gcommit
 195
 196    g.grep('hello')  # implies HEAD
 197    g.blob('v2.5:Makefile').grep('hello')
 198    g.tag('v2.5').grep('hello', 'docs/')
 199
 200    g.diff(commit1, commit2).size
 201    g.diff(commit1, commit2).stats
 202    g.gtree('v2.5').diff('v2.6').insertions
 203    g.diff('gitsearch1', 'v2.5').path('lib/')
 204    g.diff('gitsearch1', @git.gtree('v2.5'))
 205    g.diff('gitsearch1', 'v2.5').path('docs/').patch
 206    g.gtree('v2.5').diff('v2.6').patch
 207
 208    g.gtree('v2.5').diff('v2.6').each do |file_diff|
 209      puts file_diff.path
 210      puts file_diff.patch
 211      puts file_diff.blob(:src).contents
 212    end
 213
 214    g.config('user.name')  # returns 'Scott Chacon'
 215    g.config # returns whole config hash
 216
 217    g.tag # returns array of Git::Tag objects
 218 </pre>
 219 <p>
 220 And here are the operations that will need to write to your git repository.
 221 </p>
 222 <pre>
 223    g = Git.init
 224      Git.init('project')
 225      Git.init('/home/schacon/proj',
 226                  { :git_dir =&gt; '/opt/git/proj.git',
 227                      :index_file =&gt; '/tmp/index'} )
 228
 229    g = Git.clone(URI, :name =&gt; 'name', :path =&gt; '/tmp/checkout')
 230    g.config('user.name', 'Scott Chacon')
 231    g.config('user.email', 'email@email.com')
 232
 233    g.add('.')
 234    g.add([file1, file2])
 235
 236    g.remove('file.txt')
 237    g.remove(['file.txt', 'file2.txt'])
 238
 239    g.commit('message')
 240    g.commit_all('message')
 241
 242    g = Git.clone(repo, 'myrepo')
 243    g.chdir do
 244     new_file('test-file', 'blahblahblah')
 245     g.status.changed.each do |file|
 246      puts file.blob(:index).contents
 247     end
 248    end
 249
 250    g.reset # defaults to HEAD
 251    g.reset_hard(Git::Commit)
 252
 253    g.branch('new_branch') # creates new or fetches existing
 254    g.branch('new_branch').checkout
 255    g.branch('new_branch').delete
 256    g.branch('existing_branch').checkout
 257
 258    g.checkout('new_branch')
 259    g.checkout(g.branch('new_branch'))
 260
 261    g.branch(name).merge(branch2)
 262    g.branch(branch2).merge  # merges HEAD with branch2
 263
 264    g.branch(name).in_branch(message) { # add files }  # auto-commits
 265    g.merge('new_branch')
 266    g.merge('origin/remote_branch')
 267    g.merge(b.branch('master'))
 268    g.merge([branch1, branch2])
 269
 270    r = g.add_remote(name, uri)  # Git::Remote
 271    r = g.add_remote(name, Git::Base)  # Git::Remote
 272
 273    g.remotes  # array of Git::Remotes
 274    g.remote(name).fetch
 275    g.remote(name).remove
 276    g.remote(name).merge
 277    g.remote(name).merge(branch)
 278
 279    g.fetch
 280    g.fetch(g.remotes.first)
 281
 282    g.pull
 283    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 284
 285    g.add_tag('tag_name') # returns Git::Tag
 286
 287    g.repack
 288
 289    g.push
 290    g.push(g.remote('name'))
 291 </pre>
 292
 293     </div>
 294
 295
 296    </div>
 297
 298
 299   </div>
 300
 301
 302     <!-- if includes -->
 303
 304     <div id="section">
 305
 306
 307
 308
 309
 310
 311
 312
 313     <!-- if method_list -->
 314
 315
 316   </div>
 317
 318
 319 <div id="validator-badges">
 320   <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
 321 </div>
 322
 323 </body>
 324 </html>