git 1.0.2 → 1.0.3

data/lib/git.rb

@@ -23,22 +23,68 @@ require 'git/diff'
 require 'git/status'
 require 'git/author'
 
+# Git/Ruby Library
+#
+# This provides bindings for working with git in complex
+# interactions, including branching and merging, object
+# inspection and manipulation, history, patch generation
+# and more.  You should be able to do most fundamental git
+# operations with this library.
+#
+# This module provides the basic functions to open a git 
+# reference to work with. You can open a working directory,
+# open a bare repository, initialize a new repo or clone an
+# existing remote repository.
+#
+# Author::    Scott Chacon (mailto:schacon@gmail.com)
+# License::   MIT License
 module Git
 
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
   
+  # open a bare repository
+  #
+  # this takes the path to a bare git repo
+  # it expects not to be able to use a working directory
+  # so you can't checkout stuff, commit things, etc.
+  # but you can do most read operations
   def self.bare(git_dir)
     Base.bare(git_dir)
   end
     
+  # open an existing git working directory
+  # 
+  # this will most likely be the most common way to create
+  # a git reference, referring to a working directory.
+  # if not provided in the options, the library will assume
+  # your git_dir and index are in the default place (.git/, .git/index)
+  #
+  # options
+  #   :repository => '/path/to/alt_git_dir'
+  #   :index => '/path/to/alt_index_file'
   def self.open(working_dir, options = {})
     Base.open(working_dir, options)
   end
 
+  # initialize a new git repository, defaults to the current working directory
+  #
+  # options
+  #   :repository => '/path/to/alt_git_dir'
+  #   :index => '/path/to/alt_index_file'
   def self.init(working_dir = '.', options = {})
     Base.init(working_dir, options)
   end
 
+  # clones a remote repository
+  #
+  # options
+  #   :bare => true (does a bare clone)
+  #   :repository => '/path/to/alt_git_dir'
+  #   :index => '/path/to/alt_index_file'
+  #
+  # example
+  #  Git.clone('git://repo.or.cz/rubygit.git', 'clone.git', :bare => true)
+  #
   def self.clone(repository, name, options = {})
     Base.clone(repository, name, options)
   end

data/lib/git/base.rb

@@ -6,6 +6,8 @@ module Git
     @repository = nil
     @index = nil
 
+    @lib = nil
+    
     # opens a bare Git Repository - no working directory options
     def self.bare(git_dir)
       self.new :repository => git_dir
@@ -72,24 +74,51 @@ module Git
     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
@@ -117,43 +146,86 @@ module Git
     
     # 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
-    alias_method :gtree, :object
-    alias_method :gcommit, :object
-    alias_method :gblob, :object
     
+    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
-      Git::Lib.new(self)
+      @lib ||= Git::Lib.new(self)
     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
@@ -163,53 +235,80 @@ module Git
       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
     
+    # 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
 
+    # 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
@@ -218,29 +317,111 @@ module Git
       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, true)
+      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
     
-    # convenience methods
-
+    # 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
     
+    
+    ## 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
 
+    # returns the name of the branch the working directory is currently on
     def current_branch
       self.lib.branch_current
     end

data/lib/git/branch.rb

@@ -21,15 +21,18 @@ module Git
     end
     
     def gcommit
-      @gcommit = @base.object(name) if !@gcommit
+      @gcommit = @base.object(@full) if !@gcommit
       @gcommit
     end
     
     def checkout
       check_if_create
-      @base.checkout(@name)
+      @base.checkout(@full)
     end
     
+    def archive(file, opts = {})
+      @base.lib.archive(@full, file, opts)
+    end
     
     # g.branch('new_branch').in_branch do
     #   # create new file
@@ -72,6 +75,10 @@ module Git
       end
     end
     
+    def update_ref(commit)
+      @base.lib.update_ref(@full, commit)
+    end
+    
     def to_a
       [@full]
     end

data/lib/git/index.rb

@@ -1,4 +1,5 @@
 module Git
   class Index < Git::Path
+    
   end
 end