schacon-git 1.0.6

data/README

@@ -0,0 +1,238 @@
+== Git Library for Ruby
+
+Library for using Git in Ruby.
+
+= Homepage
+
+The Ruby/Git homepage is currently at : 
+
+http://jointheconversation.org/rubygit
+
+Git public hosting of the project source code is at:
+
+http://github/schacon/ruby-git
+
+= Major Objects
+
+Git::Base - this is the object returned from a Git.open or Git.clone.  
+Most major actions are called from this object.
+
+Git::Object - this is the base object for your tree, blob and commit objects,
+returned from @git.gtree or @git.object calls.  the Git::AbstractObject will
+have most of the calls in common for all those objects.
+
+Git::Diff - returns from a @git.diff command.  It is an Enumerable that returns
+Git::Diff:DiffFile objects from which you can get per file patches and insertion/deletion
+statistics.  You can also get total statistics from the Git::Diff object directly.
+
+Git::Status - returns from a @git.status command.  It is an Enumerable that returns
+Git:Status::StatusFile objects for each object in git, which includes files in the working
+directory, in the index and in the repository.  Similar to running 'git status' on the command
+line to determine untracked and changed files.
+
+Git::Branches - Enumerable object that holds Git::Branch objects.  You can call .local or .remote
+on it to filter to just your local or remote branches.
+
+Git::Remote - A reference to a remote repository that is tracked by this repository.
+
+Git::Log - An Enumerable object that references all the Git::Object::Commit objects that encompass
+your log query, which can be constructed through methods on the Git::Log object, like:
+
+ @git.log(20).object("some_file").since("2 weeks ago").between('v2.6', 'v2.7').each { |commit| [block] } 
+
+= Examples
+
+Here are a bunch of examples of how to use the Ruby/Git package. 
+
+First you have to remember to require rubygems if it's not.  Then include the 'git' gem.
+
+   require 'rubygems'
+   require 'git'
+
+Here are the operations that need read permission only.
+      
+   g = Git.open (working_dir, :log => Logger.new(STDOUT))
+   
+   g.index
+   g.index.readable?
+   g.index.writable?
+   g.repo
+   g.dir
+   
+   g.log   # returns array of Git::Commit objects
+   g.log.since('2 weeks ago')
+   g.log.between('v2.5', 'v2.6')
+   g.log.each {|l| puts l.sha }
+   g.gblob('v2.5:Makefile').log.since('2 weeks ago')
+   
+   g.object('HEAD^').to_s  # git show / git rev-parse
+   g.object('HEAD^').contents
+   g.object('v2.5:Makefile').size
+   g.object('v2.5:Makefile').sha
+   
+   g.gtree(treeish)
+   g.gblob(treeish)
+   g.gcommit(treeish)
+   
+   
+   commit = g.gcommit('1cc8667014381')
+    commit.gtree
+    commit.parent.sha
+    commit.parents.size
+    commit.author.name
+    commit.author.email
+    commit.author.date.strftime("%m-%d-%y")
+    commit.committer.name
+    commit.date.strftime("%m-%d-%y")
+    commit.message
+   
+  tree = g.gtree("HEAD^{tree}")
+    tree.blobs
+    tree.subtrees
+    tree.children # blobs and subtrees
+   
+   g.revparse('v2.5:Makefile')
+   
+   g.branches # returns Git::Branch objects
+   g.branches.local
+   g.branches.remote
+   g.branches[:master].gcommit
+   g.branches['origin/master'].gcommit
+   
+   g.grep('hello')  # implies HEAD
+   g.blob('v2.5:Makefile').grep('hello')
+   g.tag('v2.5').grep('hello', 'docs/')
+   
+   g.diff(commit1, commit2).size
+   g.diff(commit1, commit2).stats
+   g.gtree('v2.5').diff('v2.6').insertions
+   g.diff('gitsearch1', 'v2.5').path('lib/')
+   g.diff('gitsearch1', @git.gtree('v2.5'))
+   g.diff('gitsearch1', 'v2.5').path('docs/').patch
+   g.gtree('v2.5').diff('v2.6').patch
+   
+   g.gtree('v2.5').diff('v2.6').each do |file_diff|
+     puts file_diff.path
+     puts file_diff.patch
+     puts file_diff.blob(:src).contents
+   end
+   
+   g.config('user.name')  # returns 'Scott Chacon'
+   g.config # returns whole config hash
+   
+   g.tag # returns array of Git::Tag objects
+   
+   
+   
+And here are the operations that will need to write to your git repository.
+   
+   
+   g = Git.init
+     Git.init('project')
+     Git.init('/home/schacon/proj', 
+	 	  { :git_dir => '/opt/git/proj.git', 
+		     :index_file => '/tmp/index'} )
+ 	  
+   g = Git.clone(URI, :name => 'name', :path => '/tmp/checkout')   
+   g.config('user.name', 'Scott Chacon')
+   g.config('user.email', 'email@email.com')      
+   
+   g.add('.')
+   g.add([file1, file2])
+   
+   g.remove('file.txt')
+   g.remove(['file.txt', 'file2.txt'])
+		     
+   g.commit('message')
+   g.commit_all('message')
+   
+   g = Git.clone(repo, 'myrepo')
+   g.chdir do
+    new_file('test-file', 'blahblahblah')
+    g.status.changed.each do |file|
+     puts file.blob(:index).contents
+    end
+   end
+   
+   g.reset # defaults to HEAD
+   g.reset_hard(Git::Commit)
+   
+   g.branch('new_branch') # creates new or fetches existing
+   g.branch('new_branch').checkout
+   g.branch('new_branch').delete
+   g.branch('existing_branch').checkout
+   
+   g.checkout('new_branch')
+   g.checkout(g.branch('new_branch'))
+   
+   g.branch(name).merge(branch2)
+   g.branch(branch2).merge  # merges HEAD with branch2
+   
+   g.branch(name).in_branch(message) { # add files }  # auto-commits
+   g.merge('new_branch')
+   g.merge('origin/remote_branch')
+   g.merge(b.branch('master'))
+   g.merge([branch1, branch2])
+   
+   r = g.add_remote(name, uri)  # Git::Remote
+   r = g.add_remote(name, Git::Base)  # Git::Remote
+   
+   g.remotes  # array of Git::Remotes
+   g.remote(name).fetch
+   g.remote(name).remove
+   g.remote(name).merge
+   g.remote(name).merge(branch)
+   
+   g.fetch
+   g.fetch(g.remotes.first)
+   
+   g.pull
+   g.pull(Git::Repo, Git::Branch) # fetch and a merge
+   
+   g.add_tag('tag_name') # returns Git::Tag
+   
+   g.repack
+
+   g.push
+   g.push(g.remote('name'))
+
+
+Some examples of more low-level index and tree operations
+
+   g.with_temp_index do 
+
+     g.read_tree(tree3) # calls self.index.read_tree
+     g.read_tree(tree1, :prefix => 'hi/')
+
+     c = g.commit_tree('message')
+     # or #
+     t = g.write_tree
+     c = g.commit_tree(t, :message => 'message', :parents => [sha1, sha2])
+
+     g.branch('branch_name').update_ref(c)
+     g.update_ref(branch, c)
+
+     g.with_temp_working do # new blank working directory
+       g.checkout
+       g.checkout(another_index)
+       g.commit # commits to temp_index
+     end    
+   end
+
+   g.set_index('/path/to/index')
+   
+   
+   g.with_index(path) do 
+     # calls set_index, then switches back after
+   end
+   
+   g.with_working(dir) do
+   # calls set_working, then switches back after
+   end
+   
+   g.with_temp_working(dir) do
+     g.checkout_index(:prefix => dir, :path_limiter => path)
+     # do file work
+     g.commit # commits to index
+   end
+   

data/lib/git/author.rb

@@ -0,0 +1,14 @@
+module Git
+  class Author
+    attr_accessor :name, :email, :date
+    
+    def initialize(author_string)
+      if m = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string)
+        @name = m[1]
+        @email = m[2]
+        @date = Time.at(m[3].to_i)
+      end
+    end
+    
+  end
+end

data/lib/git/base.rb

@@ -0,0 +1,464 @@
+module Git
+  
+  class Base
+
+    @working_directory = nil
+    @repository = nil
+    @index = nil
+
+    @lib = nil
+    @logger = nil
+    
+    # opens a bare Git Repository - no working directory options
+    def self.bare(git_dir, opts = {})
+      default = {:repository => git_dir}
+      git_options = default.merge(opts)
+      
+      self.new(git_options)
+    end
+    
+    # opens a new Git Project from a working directory
+    # you can specify non-standard git_dir and index file in the options
+    def self.open(working_dir, opts={})    
+      default = {:working_directory => working_dir}
+      git_options = default.merge(opts)
+      
+      self.new(git_options)
+    end
+
+    # initializes a git repository
+    #
+    # options:
+    #  :repository
+    #  :index_file
+    #
+    def self.init(working_dir, opts = {})
+      default = {:working_directory => working_dir,
+                 :repository => File.join(working_dir, '.git')}
+      git_options = default.merge(opts)
+      
+      if git_options[:working_directory]
+        # if !working_dir, make it
+        FileUtils.mkdir_p(git_options[:working_directory]) if !File.directory?(git_options[:working_directory])
+      end
+      
+      # run git_init there
+      Git::Lib.new(git_options).init
+       
+      self.new(git_options)
+    end
+
+    # clones a git repository locally
+    #
+    #  repository - http://repo.or.cz/w/sinatra.git
+    #  name - sinatra
+    #
+    # options:
+    #   :repository
+    #
+    #    :bare
+    #   or 
+    #    :working_directory
+    #    :index_file
+    #
+    def self.clone(repository, name, opts = {})
+      # run git-clone 
+      self.new(Git::Lib.new.clone(repository, name, opts))
+    end
+        
+    def initialize(options = {})
+      if working_dir = options[:working_directory]
+        options[:repository] = File.join(working_dir, '.git') if !options[:repository]
+        options[:index] = File.join(working_dir, '.git', 'index') if !options[:index]
+      end
+      if options[:log]
+        @logger = options[:log]
+        @logger.info("Starting Git")
+      end
+      
+      @working_directory = Git::WorkingDirectory.new(options[:working_directory]) if options[:working_directory]
+      @repository = Git::Repository.new(options[:repository]) if options[:repository]
+      @index = Git::Index.new(options[:index], false) if options[:index]
+    end
+  
+  
+    # returns a reference to the working directory
+    #  @git.dir.path
+    #  @git.dir.writeable?
+    def dir
+      @working_directory
+    end
+
+    # returns reference to the git repository directory
+    #  @git.dir.path
+    def repo
+      @repository
+    end
+    
+    # returns reference to the git index file
+    def index
+      @index
+    end
+    
+    
+    def set_working(work_dir, check = true)
+      @lib = nil
+      @working_directory = Git::WorkingDirectory.new(work_dir.to_s, check)
+    end
+
+    def set_index(index_file, check = true)
+      @lib = nil
+      @index = Git::Index.new(index_file.to_s, check)
+    end
+    
+    # changes current working directory for a block
+    # to the git working directory
+    #
+    # example
+    #  @git.chdir do 
+    #    # write files
+    #    @git.add
+    #    @git.commit('message')
+    #  end
+    def chdir
+      Dir.chdir(dir.path) do
+        yield dir.path
+      end
+    end
+    
+    # returns the repository size in bytes
+    def repo_size
+      size = 0
+      Dir.chdir(repo.path) do
+        (size, dot) = `du -s`.chomp.split
+      end
+      size.to_i
+    end
+    
+    #g.config('user.name', 'Scott Chacon') # sets value
+    #g.config('user.email', 'email@email.com')  # sets value
+    #g.config('user.name')  # returns 'Scott Chacon'
+    #g.config # returns whole config hash
+    def config(name = nil, value = nil)
+      if(name && value)
+        # set value
+        lib.config_set(name, value)
+      elsif (name)
+        # return value
+        lib.config_get(name)
+      else
+        # return hash
+        lib.config_list
+      end
+    end
+    
+    # factory methods
+    
+    # returns a Git::Object of the appropriate type
+    # you can also call @git.gtree('tree'), but that's 
+    # just for readability.  If you call @git.gtree('HEAD') it will
+    # still return a Git::Object::Commit object.  
+    #
+    # @git.object calls a factory method that will run a rev-parse 
+    # on the objectish and determine the type of the object and return 
+    # an appropriate object for that type 
+    def object(objectish)
+      Git::Object.new(self, objectish)
+    end
+    
+    def gtree(objectish)
+      Git::Object.new(self, objectish, 'tree')
+    end
+    
+    def gcommit(objectish)
+      Git::Object.new(self, objectish, 'commit')
+    end
+    
+    def gblob(objectish)
+      Git::Object.new(self, objectish, 'blob')
+    end
+    
+    # returns a Git::Log object with count commits
+    def log(count = 30)
+      Git::Log.new(self, count)
+    end
+
+    # returns a Git::Status object
+    def status
+      Git::Status.new(self)
+    end
+        
+    # returns a Git::Branches object of all the Git::Branch objects for this repo
+    def branches
+      Git::Branches.new(self)
+    end
+    
+    # returns a Git::Branch object for branch_name
+    def branch(branch_name = 'master')
+      Git::Branch.new(self, branch_name)
+    end
+
+    # returns a Git::Remote object
+    def remote(remote_name = 'origin')
+      Git::Remote.new(self, remote_name)
+    end
+
+    # this is a convenience method for accessing the class that wraps all the 
+    # actual 'git' forked system calls.  At some point I hope to replace the Git::Lib
+    # class with one that uses native methods or libgit C bindings
+    def lib
+      @lib ||= Git::Lib.new(self, @logger)
+    end
+    
+    # will run a grep for 'string' on the HEAD of the git repository
+    # 
+    # to be more surgical in your grep, you can call grep() off a specific
+    # git object.  for example:
+    #
+    #  @git.object("v2.3").grep('TODO')
+    #
+    # in any case, it returns a hash of arrays of the type:
+    #  hsh[tree-ish] = [[line_no, match], [line_no, match2]]
+    #  hsh[tree-ish] = [[line_no, match], [line_no, match2]]
+    #
+    # so you might use it like this:
+    #
+    #   @git.grep("TODO").each do |sha, arr|
+    #     puts "in blob #{sha}:"
+    #     arr.each do |match|
+    #       puts "\t line #{match[0]}: '#{match[1]}'"
+    #     end
+    #   end
+    def grep(string)
+      self.object('HEAD').grep(string)
+    end
+    
+    # returns a Git::Diff object
+    def diff(objectish = 'HEAD', obj2 = nil)
+      Git::Diff.new(self, objectish, obj2)
+    end
+    
+    # adds files from the working directory to the git repository
+    def add(path = '.')
+      self.lib.add(path)
+    end
+
+    # removes file(s) from the git repository
+    def remove(path = '.', opts = {})
+      self.lib.remove(path, opts)
+    end
+
+    # resets the working directory to the provided commitish
+    def reset(commitish = nil, opts = {})
+      self.lib.reset(commitish, opts)
+    end
+
+    # resets the working directory to the commitish with '--hard'
+    def reset_hard(commitish = nil, opts = {})
+      opts = {:hard => true}.merge(opts)
+      self.lib.reset(commitish, opts)
+    end
+
+    # commits all pending changes in the index file to the git repository
+    def commit(message, opts = {})
+      self.lib.commit(message, opts)
+    end
+        
+    # commits all pending changes in the index file to the git repository,
+    # but automatically adds all modified files without having to explicitly
+    # calling @git.add() on them.  
+    def commit_all(message, opts = {})
+      opts = {:add_all => true}.merge(opts)
+      self.lib.commit(message, opts)
+    end
+
+    # checks out a branch as the new git working directory
+    def checkout(branch = 'master', opts = {})
+      self.lib.checkout(branch, opts)
+    end
+    
+    # checks out an old version of a file
+    def checkout_file(version, file)
+      self.lib.checkout_file(version,file)
+    end
+
+    # fetches changes from a remote branch - this does not modify the working directory,
+    # it just gets the changes from the remote if there are any
+    def fetch(remote = 'origin')
+      self.lib.fetch(remote)
+    end
+
+    # pushes changes to a remote repository - easiest if this is a cloned repository,
+    # otherwise you may have to run something like this first to setup the push parameters:
+    #
+    #  @git.config('remote.remote-name.push', 'refs/heads/master:refs/heads/master')
+    #
+    def push(remote = 'origin', branch = 'master')
+      self.lib.push(remote, branch)
+    end
+    
+    # merges one or more branches into the current working branch
+    #
+    # you can specify more than one branch to merge by passing an array of branches
+    def merge(branch, message = 'merge')
+      self.lib.merge(branch, message)
+    end
+
+    # iterates over the files which are unmerged
+    #
+    # yields file, your_version, their_version
+    def each_conflict(&block)
+      self.lib.conflicts(&block)
+    end
+
+    # fetches a branch from a remote and merges it into the current working branch
+    def pull(remote = 'origin', branch = 'master', message = 'origin pull')
+      fetch(remote)
+      merge(branch, message)
+    end
+    
+    # returns an array of Git:Remote objects
+    def remotes
+      self.lib.remotes.map { |r| Git::Remote.new(self, r) }
+    end
+
+    # adds a new remote to this repository
+    # url can be a git url or a Git::Base object if it's a local reference
+    # 
+    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
+    #  @git.fetch('scotts_git')
+    #  @git.merge('scotts_git/master')
+    #
+    def add_remote(name, url, opts = {})
+      if url.is_a?(Git::Base)
+        url = url.repo.path
+      end
+      self.lib.remote_add(name, url, opts)
+      Git::Remote.new(self, name)
+    end
+
+    # returns an array of all Git::Tag objects for this repository
+    def tags
+      self.lib.tags.map { |r| tag(r) }
+    end
+    
+    # returns a Git::Tag object
+    def tag(tag_name)
+      Git::Object.new(self, tag_name, 'tag', true)
+    end
+
+    # creates a new git tag (Git::Tag)
+    def add_tag(tag_name)
+      self.lib.tag(tag_name)
+      tag(tag_name)
+    end
+    
+    # creates an archive file of the given tree-ish
+    def archive(treeish, file = nil, opts = {})
+      self.object(treeish).archive(file, opts)
+    end
+    
+    # repacks the repository
+    def repack
+      self.lib.repack
+    end
+    
+    def gc
+      self.lib.gc
+    end
+    
+    
+    ## LOWER LEVEL INDEX OPERATIONS ##
+    
+    def with_index(new_index)
+      old_index = @index
+      set_index(new_index, false)
+      return_value = yield @index
+      set_index(old_index)
+      return_value
+    end
+    
+    def with_temp_index &blk
+      tempfile = Tempfile.new('temp-index')
+      temp_path = tempfile.path
+      tempfile.unlink
+      with_index(temp_path, &blk)
+    end
+    
+    def checkout_index(opts = {})
+      self.lib.checkout_index(opts)
+    end
+    
+    def read_tree(treeish, opts = {})
+      self.lib.read_tree(treeish, opts)
+    end
+    
+    def write_tree
+      self.lib.write_tree
+    end
+    
+    def commit_tree(tree = nil, opts = {})
+      Git::Object::Commit.new(self, self.lib.commit_tree(tree, opts))
+    end
+    
+    def write_and_commit_tree(opts = {})
+      tree = write_tree
+      commit_tree(tree, opts)
+    end
+      
+    def update_ref(branch, commit)
+      branch(branch).update_ref(commit)
+    end
+    
+    
+    def ls_files
+      self.lib.ls_files
+    end
+
+    def with_working(work_dir)
+      return_value = false
+      old_working = @working_directory
+      set_working(work_dir) 
+      Dir.chdir work_dir do
+        return_value = yield @working_directory
+      end
+      set_working(old_working)
+      return_value
+    end
+    
+    def with_temp_working &blk
+      tempfile = Tempfile.new("temp-workdir")
+      temp_dir = tempfile.path
+      tempfile.unlink
+      Dir.mkdir(temp_dir, 0700)
+      with_working(temp_dir, &blk)
+    end
+    
+    
+    # runs git rev-parse to convert the objectish to a full sha
+    #
+    #   @git.revparse("HEAD^^")
+    #   @git.revparse('v2.4^{tree}')
+    #   @git.revparse('v2.4:/doc/index.html')
+    #
+    def revparse(objectish)
+      self.lib.revparse(objectish)
+    end
+    
+    def ls_tree(objectish)
+      self.lib.ls_tree(objectish)
+    end
+    
+    def cat_file(objectish)
+      self.lib.object_contents(objectish)
+    end
+
+    # returns the name of the branch the working directory is currently on
+    def current_branch
+      self.lib.branch_current
+    end
+
+    
+  end
+  
+end