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>Fri Nov 16 11:43:31 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> - returns from a
 121 @git.status command. It is an Enumerable that returns <a
 122 href="../classes/Git.html">Git</a>:Status::StatusFile objects for each
 123 object in git, which includes files in the working directory, in the index
 124 and in the repository. Similar to running &#8216;git status&#8217; on the
 125 command line to determine untracked and changed files.
 126 </p>
 127 <p>
 128 <a href="../classes/Git/Branches.html">Git::Branches</a> - Enumerable
 129 object that holds <a href="../classes/Git/Branch.html">Git::Branch</a>
 130 objects. You can call .local or .remote on it to filter to just your local
 131 or remote branches.
 132 </p>
 133 <p>
 134 <a href="../classes/Git/Remote.html">Git::Remote</a> - A reference to a
 135 remote repository that is tracked by this repository.
 136 </p>
 137 <p>
 138 <a href="../classes/Git/Log.html">Git::Log</a> - An Enumerable object that
 139 references all the <a
 140 href="../classes/Git/Object/Commit.html">Git::Object::Commit</a> objects
 141 that encompass your log query, which can be constructed through methods on
 142 the <a href="../classes/Git/Log.html">Git::Log</a> object, like:
 143 </p>
 144 <pre>
 145  @git.log(20).object(&quot;HEAD^&quot;).since(&quot;2 weeks ago&quot;).between('v2.6', 'v2.7').each { |commit| [block] }
 146 </pre>
 147 <h1>Examples</h1>
 148 <p>
 149 Here are a bunch of examples of how to use the Ruby/<a
 150 href="../classes/Git.html">Git</a> package.
 151 </p>
 152 <p>
 153 First you have to remember to require rubygems if it&#8217;s not. Then
 154 include the &#8216;git&#8217; gem.
 155 </p>
 156 <pre>
 157    require 'rubygems'
 158    require 'git'
 159 </pre>
 160 <p>
 161 Here are the operations that need read permission only.
 162 </p>
 163 <pre>
 164    g = Git.open (working_dir = '.')
 165           (git_dir, index_file)
 166
 167    g.index
 168    g.index.readable?
 169    g.index.writable?
 170    g.repo
 171    g.dir
 172
 173    g.log   # returns array of Git::Commit objects
 174    g.log.since('2 weeks ago')
 175    g.log.between('v2.5', 'v2.6')
 176    g.log.each {|l| puts l.sha }
 177    g.gblob('v2.5:Makefile').log.since('2 weeks ago')
 178
 179    g.object('HEAD^').to_s  # git show / git rev-parse
 180    g.object('HEAD^').contents
 181    g.object('v2.5:Makefile').size
 182    g.object('v2.5:Makefile').sha
 183
 184    g.gtree(treeish)
 185    g.gblob(treeish)
 186    g.gcommit(treeish)
 187
 188    commit = g.gcommit('1cc8667014381')
 189     commit.gtree
 190     commit.parent.sha
 191     commit.parents.size
 192     commit.author.name
 193     commit.author.email
 194     commit.author.date.strftime(&quot;%m-%d-%y&quot;)
 195     commit.committer.name
 196     commit.date.strftime(&quot;%m-%d-%y&quot;)
 197     commit.message
 198
 199   tree = g.gtree(&quot;HEAD^{tree}&quot;)
 200     tree.blobs
 201     tree.subtrees
 202     tree.children # blobs and subtrees
 203
 204    g.revparse('v2.5:Makefile')
 205
 206    g.branches # returns Git::Branch objects
 207    g.branches.local
 208    g.branches.remote
 209    g.branches[:master].gcommit
 210    g.branches['origin/master'].gcommit
 211
 212    g.grep('hello')  # implies HEAD
 213    g.blob('v2.5:Makefile').grep('hello')
 214    g.tag('v2.5').grep('hello', 'docs/')
 215
 216    g.diff(commit1, commit2).size
 217    g.diff(commit1, commit2).stats
 218    g.gtree('v2.5').diff('v2.6').insertions
 219    g.diff('gitsearch1', 'v2.5').path('lib/')
 220    g.diff('gitsearch1', @git.gtree('v2.5'))
 221    g.diff('gitsearch1', 'v2.5').path('docs/').patch
 222    g.gtree('v2.5').diff('v2.6').patch
 223
 224    g.gtree('v2.5').diff('v2.6').each do |file_diff|
 225      puts file_diff.path
 226      puts file_diff.patch
 227      puts file_diff.blob(:src).contents
 228    end
 229
 230    g.config('user.name')  # returns 'Scott Chacon'
 231    g.config # returns whole config hash
 232
 233    g.tag # returns array of Git::Tag objects
 234 </pre>
 235 <p>
 236 And here are the operations that will need to write to your git repository.
 237 </p>
 238 <pre>
 239    g = Git.init
 240      Git.init('project')
 241      Git.init('/home/schacon/proj',
 242                  { :git_dir =&gt; '/opt/git/proj.git',
 243                      :index_file =&gt; '/tmp/index'} )
 244
 245    g = Git.clone(URI, :name =&gt; 'name', :path =&gt; '/tmp/checkout')
 246    g.config('user.name', 'Scott Chacon')
 247    g.config('user.email', 'email@email.com')
 248
 249    g.add('.')
 250    g.add([file1, file2])
 251
 252    g.remove('file.txt')
 253    g.remove(['file.txt', 'file2.txt'])
 254
 255    g.commit('message')
 256    g.commit_all('message')
 257
 258    g = Git.clone(repo, 'myrepo')
 259    g.chdir do
 260     new_file('test-file', 'blahblahblah')
 261     g.status.changed.each do |file|
 262      puts file.blob(:index).contents
 263     end
 264    end
 265
 266    g.reset # defaults to HEAD
 267    g.reset_hard(Git::Commit)
 268
 269    g.branch('new_branch') # creates new or fetches existing
 270    g.branch('new_branch').checkout
 271    g.branch('new_branch').delete
 272    g.branch('existing_branch').checkout
 273
 274    g.checkout('new_branch')
 275    g.checkout(g.branch('new_branch'))
 276
 277    g.branch(name).merge(branch2)
 278    g.branch(branch2).merge  # merges HEAD with branch2
 279
 280    g.branch(name).in_branch(message) { # add files }  # auto-commits
 281    g.merge('new_branch')
 282    g.merge('origin/remote_branch')
 283    g.merge(b.branch('master'))
 284    g.merge([branch1, branch2])
 285
 286    r = g.add_remote(name, uri)  # Git::Remote
 287    r = g.add_remote(name, Git::Base)  # Git::Remote
 288
 289    g.remotes  # array of Git::Remotes
 290    g.remote(name).fetch
 291    g.remote(name).remove
 292    g.remote(name).merge
 293    g.remote(name).merge(branch)
 294
 295    g.fetch
 296    g.fetch(g.remotes.first)
 297
 298    g.pull
 299    g.pull(Git::Repo, Git::Branch) # fetch and a merge
 300
 301    g.add_tag('tag_name') # returns Git::Tag
 302
 303    g.repack
 304
 305    g.push
 306    g.push(g.remote('name'))
 307 </pre>
 308 <p>
 309 Some examples of more low-level index and tree operations
 310 </p>
 311 <pre>
 312    g.with_temp_index do
 313
 314      g.read_tree(tree3) # calls self.index.read_tree
 315      g.read_tree(tree1, :prefix =&gt; 'hi/')
 316
 317      c = g.commit_tree('message')
 318      # or #
 319      t = g.write_tree
 320      c = g.commit_tree(t, :message =&gt; 'message', :parents =&gt; [sha1, sha2])
 321
 322      g.branch('branch_name').update_ref(c)
 323      g.update_ref(branch, c)
 324
 325      g.with_temp_working do # new blank working directory
 326        g.checkout
 327        g.checkout(another_index)
 328        g.commit # commits to temp_index
 329      end
 330    end
 331
 332    g.set_index('/path/to/index')
 333
 334    g.with_index(path) do
 335      # calls set_index, then switches back after
 336    end
 337
 338    g.with_working(dir) do
 339    # calls set_working, then switches back after
 340    end
 341
 342    g.with_temp_working(dir) do
 343      g.checkout_index(:prefix =&gt; dir, :path_limiter =&gt; path)
 344      # do file work
 345      g.commit # commits to index
 346    end
 347 </pre>
 348
 349     </div>
 350
 351
 352    </div>
 353
 354
 355   </div>
 356
 357
 358     <!-- if includes -->
 359
 360     <div id="section">
 361
 362
 363
 364
 365
 366
 367
 368
 369     <!-- if method_list -->
 370
 371
 372   </div>
 373
 374
 375 <div id="validator-badges">
 376   <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
 377 </div>
 378
 379 </body>
 380 </html>