grit 1.0.1 → 1.1.0

data/History.txt

@@ -1,8 +1,38 @@
-== 1.0.1 / 2008-02-10
+== 1.1.0 / 2009-03-29
+  * Backwards breaking changes
+    * Diff#a_commit -> Diff#a_blob, Diff#b_commit -> Diff#b_blob
+  * Major Enhancments
+    * Ruby 1.9 compatibility [github.com/chapados, github.com/js]
+  * Minor Enhancements
+    * Convert readme to markdown
+    * Added a shortcut for commit_stats as Commit#stats [github.com/js]
+    * Add a #basename method to Submodule, Blob and Tree for retrieving the name [github.com/js]
+    * Make Grit::Submodule grasp the concept of non-unix lineendings [github.com/js]
+    * Added Repo#commit_deltas_from [github.com/js]
+    * do some mild shell escaping when running commands [github.com/js]
+    * Added two shortcut methods to Tree, for picking trees/blobs only [github.com/Voker57]
+    * Added <=> method to Blob, needed for sorting tree [github.com/Voker57]
+    * Make the number of bytes to be read from git's stdout configurable [github.com/josb]
+    * Repo.archive_to_file accepts extra parameters making plain zipping possible [github.com/darwin]
+    * Handle commit stats that summarize commits with binary changes [github.com/therealadam]
+    * Add a DiffStat class for easy access to diff stats [github.com/therealadam]
+    * Don't split git logs that contain blank lines into two CommitStats [github.com/therealadam]
+    * Add DiffStat#net for total change count [github.com/therealadam]
+
+== 1.0.3 / 2009-02-13
+  * Minor Enhancements
+    * Added Grit::Commit#to_patch for plaintext formatted patches.
+    * Fixed Grit::Tag to work with annotated tags.
+
+== 1.0.2 / 2009-02-10
+  * Minor Enhancements
+    * Implement Grit.version to use VERSION.yml file
+
+== 1.0.1 / 2009-02-10
   * Bug Fixes
     * Add diff-lcs as a dependency
 
-== 1.0.0 / 2008-01-27
+== 1.0.0 / 2009-01-27
   * Tons of awesome in here. Also, we suck at updating the history.
   * Let's do better at that from now on.
 

data/README.md

@@ -0,0 +1,210 @@
+Grit
+====
+
+Grit gives you object oriented read/write access to Git repositories via Ruby.
+The main goals are stability and performance. To this end, some of the
+interactions with Git repositories are done by shelling out to the system's
+`git` command, and other interactions are done with pure Ruby
+reimplementations of core Git functionality. This choice, however, is
+transparent to end users, and you need not know which method is being used.
+
+This software was developed to power GitHub, and should be considered
+production ready. An extensive test suite is provided to verify its correctness.
+
+Grit is maintained by Tom Preston-Werner, Scott Chacon, Chris Wanstrath, and
+PJ Hyett.
+
+This documentation is accurate as of Grit 1.0.2.
+
+
+## Requirements #############################################################
+
+* git (http://git-scm.com) tested with 1.6.0.2
+
+
+## Install ##################################################################
+
+Easiest install is via RubyGems:
+
+    $ gem install grit
+
+or
+
+    $ gem sources -a http://gems.github.com/ (you only need to do this once)
+    $ gem install mojombo-grit
+
+The gem from GitHub will generally be available sooner than the gem from
+Rubyforge. Both sources will eventually contain the same releases.
+
+
+## Source ###################################################################
+
+Grit's Git repo is available on GitHub, which can be browsed at:
+
+    http://github.com/mojombo/grit
+
+and cloned with:
+
+    git clone git://github.com/mojombo/grit.git
+
+
+## Usage ####################################################################
+
+Grit gives you object model access to your Git repositories. Once you have
+created a `Repo` object, you can traverse it to find parent commits,
+trees, blobs, etc.
+
+### Initialize a Repo object
+
+The first step is to create a `Grit::Repo` object to represent your repo. In
+this documentation I include the `Grit` module to reduce typing.
+
+    require 'grit'
+    include Grit
+    repo = Repo.new("/Users/tom/dev/grit")
+
+In the above example, the directory `/Users/tom/dev/grit` is my working
+directory and contains the `.git` directory. You can also initialize Grit with
+a bare repo.
+
+    repo = Repo.new("/var/git/grit.git")
+
+### Getting a list of commits
+
+From the `Repo` object, you can get a list of commits as an array of `Commit`
+objects.
+
+    repo.commits
+    # => [#<Grit::Commit "e80bbd2ce67651aa18e57fb0b43618ad4baf7750">,
+          #<Grit::Commit "91169e1f5fa4de2eaea3f176461f5dc784796769">,
+          #<Grit::Commit "038af8c329ef7c1bae4568b98bd5c58510465493">,
+          #<Grit::Commit "40d3057d09a7a4d61059bca9dca5ae698de58cbe">,
+          #<Grit::Commit "4ea50f4754937bf19461af58ce3b3d24c77311d9">]
+
+Called without arguments, `Repo#commits` returns a list of up to ten commits
+reachable by the **master** branch (starting at the latest commit). You can
+ask for commits beginning at a different branch, commit, tag, etc.
+
+    repo.commits('mybranch')
+    repo.commits('40d3057d09a7a4d61059bca9dca5ae698de58cbe')
+    repo.commits('v0.1')
+
+You can specify the maximum number of commits to return.
+
+    repo.commits('master', 100)
+
+If you need paging, you can specify a number of commits to skip.
+
+    repo.commits('master', 10, 20)
+
+The above will return commits 21-30 from the commit list.
+
+### The Commit object
+
+`Commit` objects contain information about that commit.
+
+    head = repo.commits.first
+
+    head.id
+    # => "e80bbd2ce67651aa18e57fb0b43618ad4baf7750"
+
+    head.parents
+    # => [#<Grit::Commit "91169e1f5fa4de2eaea3f176461f5dc784796769">]
+
+    head.tree
+    # => #<Grit::Tree "3536eb9abac69c3e4db583ad38f3d30f8db4771f">
+
+    head.author
+    # => #<Grit::Actor "Tom Preston-Werner <tom@mojombo.com>">
+
+    head.authored_date
+    # => Wed Oct 24 22:02:31 -0700 2007
+
+    head.committer
+    # => #<Grit::Actor "Tom Preston-Werner <tom@mojombo.com>">
+
+    head.committed_date
+    # => Wed Oct 24 22:02:31 -0700 2007
+
+    head.message
+    # => "add Actor inspect"
+
+You can traverse a commit's ancestry by chaining calls to `#parents`.
+
+    repo.commits.first.parents[0].parents[0].parents[0]
+
+The above corresponds to **master^^^** or **master~3** in Git parlance.
+
+### The Tree object
+
+A tree records pointers to the contents of a directory. Let's say you want
+the root tree of the latest commit on the **master** branch.
+
+    tree = repo.commits.first.tree
+    # => #<Grit::Tree "3536eb9abac69c3e4db583ad38f3d30f8db4771f">
+
+    tree.id
+    # => "3536eb9abac69c3e4db583ad38f3d30f8db4771f"
+
+Once you have a tree, you can get the contents.
+
+    contents = tree.contents
+    # => [#<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">,
+          #<Grit::Blob "81d2c27608b352814cbe979a6acd678d30219678">,
+          #<Grit::Tree "c3d07b0083f01a6e1ac969a0f32b8d06f20c62e5">,
+          #<Grit::Tree "4d00fe177a8407dbbc64a24dbfc564762c0922d8">]
+
+This tree contains two `Blob` objects and two `Tree` objects. The trees are
+subdirectories and the blobs are files. Trees below the root have additional
+attributes.
+
+    contents.last.name
+    # => "lib"
+
+    contents.last.mode
+    # => "040000"
+
+There is a convenience method that allows you to get a named sub-object
+from a tree.
+
+    tree / "lib"
+    # => #<Grit::Tree "e74893a3d8a25cbb1367cf241cc741bfd503c4b2">
+
+You can also get a tree directly from the repo if you know its name.
+
+    repo.tree
+    # => #<Grit::Tree "master">
+
+    repo.tree("91169e1f5fa4de2eaea3f176461f5dc784796769")
+    # => #<Grit::Tree "91169e1f5fa4de2eaea3f176461f5dc784796769">
+
+### The Blob object
+
+A blob represents a file. Trees often contain blobs.
+
+    blob = tree.contents.first
+    # => #<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">
+
+A blob has certain attributes.
+
+    blob.id
+    # => "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666"
+
+    blob.name
+    # => "README.txt"
+
+    blob.mode
+    # => "100644"
+
+    blob.size
+    # => 7726
+
+You can get the data of a blob as a string.
+
+    blob.data
+    # => "Grit is a library to ..."
+
+You can also get a blob directly from the repo if you know its name.
+
+    repo.blob("4ebc8aea50e0a67e000ba29a30809d0a7b9b2666")
+    # => #<Grit::Blob "4ebc8aea50e0a67e000ba29a30809d0a7b9b2666">

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 1
-:minor: 0
-:patch: 1
+:minor: 1
+:patch: 0

data/lib/grit.rb

@@ -17,14 +17,19 @@ end
 
 # third party
 require 'rubygems'
+gem "mime-types", ">=0"
 require 'mime/types'
 
+# ruby 1.9 compatibility
+require 'grit/ruby1.9'
+
 # internal requires
 require 'grit/lazy'
 require 'grit/errors'
 require 'grit/git-ruby'
 require 'grit/git'
 require 'grit/ref'
+require 'grit/tag'
 require 'grit/commit'
 require 'grit/commit_stats'
 require 'grit/tree'
@@ -41,7 +46,6 @@ require 'grit/merge'
 
 
 module Grit
-  
   class << self
     # Set +debug+ to true to log all git calls and responses
     attr_accessor :debug
@@ -54,8 +58,11 @@ module Grit
   end
   self.debug = false
   self.use_git_ruby = true
-  
+
   @logger ||= ::Logger.new(STDOUT)
-  
-  VERSION = '1.0.0'
+
+  def self.version
+    yml = YAML.load(File.read(File.join(File.dirname(__FILE__), *%w[.. VERSION.yml])))
+    "#{yml[:major]}.#{yml[:minor]}.#{yml[:patch]}"
+  end
 end

data/lib/grit/blob.rb

@@ -104,14 +104,23 @@ module Grit
             info = nil
         end
       end
-      
+
       blames
     end
     
+    def basename
+      File.basename(name)
+    end
+    
     # Pretty object inspection
     def inspect
       %Q{#<Grit::Blob "#{@id}">}
     end
+
+    # Compares blobs by name
+    def <=>(other)
+      name <=> other.name
+    end
   end # Blob
-  
+
 end # Grit

data/lib/grit/commit.rb

@@ -1,5 +1,5 @@
 module Grit
-  
+
   class Commit
     attr_reader :id
     lazy_reader :parents
@@ -11,7 +11,7 @@ module Grit
     lazy_reader :message
     lazy_reader :short_message
     lazy_reader :author_string
-    
+
     # Instantiate a new Commit
     #   +id+ is the id of the commit
     #   +parents+ is an array of commit ids (will be converted into Commit instances)
@@ -35,11 +35,11 @@ module Grit
       @message = message.join("\n")
       @short_message = message[0] || ''
     end
-    
+
     def id_abbrev
       @id_abbrev ||= @repo.git.rev_parse({}, self.id).chomp[0, 7]
     end
-    
+
     # Create an unbaked Commit containing just the specified attributes
     #   +repo+ is the Repo
     #   +atts+ is a Hash of instance variable data
@@ -48,7 +48,7 @@ module Grit
     def self.create(repo, atts)
       self.allocate.create_initialize(repo, atts)
     end
-    
+
     # Initializer for Commit.create
     #   +repo+ is the Repo
     #   +atts+ is a Hash of instance variable data
@@ -61,11 +61,11 @@ module Grit
       end
       self
     end
-    
+
     def lazy_source
       self.class.find_all(@repo, @id, {:max_count => 1}).first
     end
-    
+
     # Count the number of commits reachable from this ref
     #   +repo+ is the Repo
     #   +ref+ is the ref from which to begin (SHA1 or name)
@@ -74,7 +74,7 @@ module Grit
     def self.count(repo, ref)
       repo.git.rev_list({}, ref).size / 41
     end
-    
+
     # Find all commits matching the given criteria.
     #   +repo+ is the Repo
     #   +ref+ is the ref from which to begin (SHA1 or name) or nil for --all
@@ -85,21 +85,21 @@ module Grit
     # Returns Grit::Commit[] (baked)
     def self.find_all(repo, ref, options = {})
       allowed_options = [:max_count, :skip, :since]
-          
+
       default_options = {:pretty => "raw"}
       actual_options = default_options.merge(options)
-      
+
       if ref
         output = repo.git.rev_list(actual_options, ref)
       else
         output = repo.git.rev_list(actual_options.merge(:all => true))
       end
-            
+
       self.list_from_string(repo, output)
     rescue Grit::GitRuby::Repository::NoSuchShaFound
       []
     end
-    
+
     # Parse out commit information into an array of baked Commit objects
     #   +repo+ is the Repo
     #   +text+ is the text output from the git command (raw format)
@@ -111,40 +111,40 @@ module Grit
     #
     def self.list_from_string(repo, text)
       lines = text.split("\n")
-      
+
       commits = []
-            
+
       while !lines.empty?
         id = lines.shift.split.last
         tree = lines.shift.split.last
-        
+
         parents = []
         parents << lines.shift.split.last while lines.first =~ /^parent/
-        
+
         author, authored_date = self.actor(lines.shift)
         committer, committed_date = self.actor(lines.shift)
-        
+
         # not doing anything with this yet, but it's sometimes there
         encoding = lines.shift.split.last if lines.first =~ /^encoding/
-        
+
         lines.shift
-        
+
         message_lines = []
         message_lines << lines.shift[4..-1] while lines.first =~ /^ {4}/
-        
+
         lines.shift while lines.first && lines.first.empty?
-        
+
         commits << Commit.new(repo, id, parents, tree, author, authored_date, committer, committed_date, message_lines)
       end
-      
+
       commits
     end
-    
+
     # Show diffs between two trees:
     #   +repo+ is the Repo
     #   +a+ is a named commit
-    #   +b+ is an optional named commit.  Passing an array assumes you 
-    #     wish to omit the second named commit and limit the diff to the 
+    #   +b+ is an optional named commit.  Passing an array assumes you
+    #     wish to omit the second named commit and limit the diff to the
     #     given paths.
     #   +paths* is an array of paths to limit the diff.
     #
@@ -175,10 +175,14 @@ module Grit
       if parents.empty?
         show
       else
-        self.class.diff(@repo, parents.first.id, @id) 
+        self.class.diff(@repo, parents.first.id, @id)
       end
     end
     
+    def stats
+      stats = @repo.commit_stats(self.sha, 1)[0][-1]
+    end
+    
     # Convert this Commit to a String which is just the SHA1 id
     def to_s
       @id
@@ -187,18 +191,22 @@ module Grit
     def sha
       @id
     end
-    
+
     def date
       @committed_date
     end
-    
+
+    def to_patch
+      @repo.git.format_patch({'1' => true, :stdout => true}, to_s)
+    end
+
     # Pretty object inspection
     def inspect
       %Q{#<Grit::Commit "#{@id}">}
     end
-    
+
     # private
-    
+
     # Parse out the actor (author or committer) info
     #
     # Returns [String (actor name and email), Time (acted at time)]
@@ -206,11 +214,11 @@ module Grit
       m, actor, epoch = *line.match(/^.+? (.*) (\d+) .*$/)
       [Actor.from_string(actor), Time.at(epoch.to_i)]
     end
-    
+
     def author_string
       "%s <%s> %s %+05d" % [author.name, author.email, authored_date.to_i, 800]
     end
-    
+
     def to_hash
       {
         'id'       => id,
@@ -230,5 +238,5 @@ module Grit
       }
     end
   end # Commit
-  
+
 end # Grit