multi_git 0.0.1.rc1 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 568f2ff3c702a98fe88e7f5ac6a1d80f2eae7b17
-  data.tar.gz: fac8b206478b5fef7c8ebd2e0872832415da0ec4
+  metadata.gz: ea6b7b8a649a9690089663d09a517b3be10a73e6
+  data.tar.gz: 54172a19b99fec2efe32e090d4f26f7625afd38f
 SHA512:
-  metadata.gz: d0092bb34f79f968ded7539c858a72daaf309c5c772130433001d8088ab2519224e0ea72e6d606136e925bbf99770c678b33385d06fbc72ea6f541063ab57645
-  data.tar.gz: 4ad11a12904c0de1560345983ccac9b5fc6fecf71f63f0fc3183d501b78f02cda0e0de4568c4b8fa5a4b3278d9290204a61fbdb45e28eae828f8436bd128de6a
+  metadata.gz: a31a18773445a3a64ff24b5bcccde2925af8b104911cc182c81b087c7e3ea83fbab63a5ba3df6133b64ca7ecb6f9dfe144de1339e750a397cb4f98dc2bfca5e8
+  data.tar.gz: e0b1465cc4df5b5e356f5b7304bd3ea0abcd678dc3f7964ee88a006a600a376ee6b5e9bdc4af4a9110c57c0226beea41939ef7381536ebe1eb490710d688a5af

data/lib/multi_git.rb

@@ -37,11 +37,11 @@ public
   #     # teardown:
   #     `rm -rf #{dir}`
   #
-  #
+  #   @param [String] directory
+  #   @param [Hash] options
+  #   @option options [Boolean] :init if true the repository is automatically created (defaults to: false)
+  #   @option options [Boolean] :bare if true the repository is expected to be bare
   #   @return [Repository]
-  #
-  #   @see Backend
-  # 
   delegate :open => 'best'
 
 end

data/lib/multi_git/backend.rb

@@ -2,8 +2,10 @@ require 'multi_git/utils'
 require 'multi_git/error'
 module MultiGit
 
+  # Backend is an abstract base class for all other Backends.
   module Backend
 
+    #@!visibility private
     attr :failed, :exception
 
     def check(description, &check)
@@ -28,6 +30,7 @@ module MultiGit
 
     private :check, :check!
 
+    # @api developer
     # @abstract
     #
     # This method implements loading the backend files.
@@ -37,6 +40,10 @@ module MultiGit
 
     # Opens a git repository.
     #
+    # @param [String] directory
+    # @param [Hash] options
+    # @option options [Boolean] :init if true the repository is automatically created (defaults to: false)
+    # @option options [Boolean] :bare if true the repository is expected to be bare
     # @return [Repository]
     def open(directory, options = {})
       load!

data/lib/multi_git/blob.rb

@@ -10,15 +10,18 @@ module MultiGit
         :blob
       end
 
+      # @visibility private
       def ==(other)
         return false unless other.respond_to? :oid
         return oid == other.oid
       end
 
+      # @visibility private
       def inspect
         ['<',self.class,' ',oid,'>'].join
       end
 
+      # @visibility private
       alias to_s inspect
     end
 
@@ -39,9 +42,7 @@ module MultiGit
         end
       end
 
-      def content
-        string
-      end
+      alias content string
 
       def content=(value)
         self.string = value.dup
@@ -58,14 +59,32 @@ module MultiGit
         dig << content
         return dig.hexdigest
       end
+
+      # Turns the blob into a file using the given parent and filename.
+      # @param [Object] parent
+      # @param [String] name
+      # @return [File::Builder]
+      def with_parent(parent, name)
+        File::Builder.new(parent, name, self)
+      end
     end
 
     include Object
     include Base
 
+    # @return [Builder]
     def to_builder
       Builder.new(self)
     end
 
+    # Turns the blob into a file using the given parent and filename.
+    # @param [Object] parent
+    # @param [String] name
+    # @return [File]
+    def with_parent(parent, name)
+      File.new(parent, name, self)
+    end
+
   end
 end
+require 'multi_git/file'

data/lib/multi_git/commit.rb

@@ -2,6 +2,7 @@ require 'forwardable'
 require 'multi_git/utils'
 require 'multi_git/handle'
 require 'multi_git/builder'
+require 'multi_git/object'
 module MultiGit
 
   module Commit
@@ -10,26 +11,41 @@ module MultiGit
       extend Utils::AbstractMethods
       extend Forwardable
 
-      # @return String
+      # @!attribute message
+      #   @return [String]
       abstract :message
 
-      # @return Tree
+      # @!attribute tree
+      #   @return [Tree]
       abstract :tree
 
-      # @return [Array<Commit>]
+      # @!attribute parents
+      #   @return [Array<Commit>]
       abstract :parents
 
-      # @return [Time]
+      # @!attribute time
+      #   @return [Time]
       abstract :time
-      # @return [Handle]
+
+      # @!attribute author
+      #   @return [Handle]
       abstract :author
 
-      # @return [Time]
+      # @!attribute commit_time
+      #   @return [Time]
       abstract :commit_time
-      # @return [Handle]
+
+      # @!attribute committer
+      #   @return [Handle]
       abstract :committer
 
-      delegate [:[], :/] => :tree
+      # @!method [](path)
+      #   @see (MultiGit::Tree#[])
+      delegate :[] => :tree
+
+      # @!parse alias / []
+      delegate :/ => :tree
+
 
       def type
         :commit
@@ -49,11 +65,11 @@ module MultiGit
     #   builder = MultiGit::Commit::Builder.new
     #   builder.message = "My first commit"
     #   builder.by "me@example.com"
-    #   builder.tree["a_file"] = "some content"
+    #   builder["a_file"] = "some content"
     #   # builder is now ready to be inserted
     #   repository = MultiGit.open(dir, init: true)
     #   commit = repository << builder #=> be_a MultiGit::Commit
-    #   commit.tree['a_file'].content  #=> eql "some content"
+    #   commit['a_file'].content  #=> eql "some content"
     #   # teardown:
     #   `rm -rf #{dir}`
     class Builder
@@ -128,6 +144,11 @@ module MultiGit
         return self
       end
 
+      extend Forwardable
+      # @!method []=(path, content)
+      #   @see (MultiGit::TreeBuilder#[]=)
+      delegate :[]= => :tree
+
       def initialize(from = nil, &block)
         @parents = []
         if from.kind_of? Tree
@@ -178,6 +199,7 @@ module MultiGit
 
     end
 
+    include Object
     include Base
 
   end

data/lib/multi_git/directory.rb

@@ -10,14 +10,12 @@ module MultiGit
         Utils::MODE_DIRECTORY
       end
 
-      def parent?
-        !@parent.nil?
-      end
-
       def size
         object.size
       end
 
+      # @param [String] key
+      # @return [TreeEntry, nil]
       def entry(key)
         e = object.entry(key)
         e.with_parent(self) if e
@@ -52,23 +50,7 @@ module MultiGit
       include Tree::Builder::DSL
       include Base
 
-      def make_inner(*args)
-        if args.any?
-          if args[0].kind_of?(Tree::Builder)
-            return args[0]
-          elsif args[0].kind_of?(Directory)
-            return args[0].object.to_builder
-          elsif args[0].kind_of?(Tree)
-            return args[0].to_builder
-          end
-        end
-        Tree::Builder.new(*args)
-      end
-
-      def entry_set(key, value)
-        object.entry_set(key, make_entry(key, value))
-      end
-
+      # @return [Hash<String, TreeEntry::Builder>]
       def entries
         Hash[
           object.map{|entry| [entry.name, entry.with_parent(self) ] }
@@ -79,12 +61,32 @@ module MultiGit
 
       delegate (Tree::Builder.instance_methods - self.instance_methods) => :object
 
+      # @return [TreeEntry, nil]
       def from
         defined?(@from) ? @from : @from = make_from
       end
 
+      # @visibility private
+      # @api private
+      def entry_set(key, value)
+        object.entry_set(key, make_entry(key, value))
+      end
+
     private
 
+      def make_inner(*args)
+        if args.any?
+          if args[0].kind_of?(Tree::Builder)
+            return args[0]
+          elsif args[0].kind_of?(Directory)
+            return args[0].object.to_builder
+          elsif args[0].kind_of?(Tree)
+            return args[0].to_builder
+          end
+        end
+        Tree::Builder.new(*args)
+      end
+
       def make_from
         if object.from.nil?
           nil
@@ -96,6 +98,7 @@ module MultiGit
 
     include Base
 
+    # @return [Hash<String, TreeEntry>]
     def entries
       @entries ||= Hash[
         object.map{|entry| [entry.name, entry.with_parent(self) ] }

data/lib/multi_git/error.rb

@@ -67,11 +67,19 @@ module MultiGit
 
       def initialize
         super 'Another process has updated the ref you are currently updating.
-This is unlikely to be a problem, no data got lost. You may simply retry the update.
+This is unlikely a problem, no data got lost. You may simply retry the update.
 If this happens frequently, you may have want to run "git gc" to remove clobber.'
       end
     end
 
+    class InvalidReferenceTarget < ArgumentError
+      include Error
+
+      def initialize(supplied_value)
+        super "References can only point to instances of MultiGit::Ref, MultiGit::Object, MultiGit::Builder or nil. You supplied: #{supplied_value.inspect}"
+      end
+    end
+
     class DuplicateConfigKey < Exception
       include Error
     end

data/lib/multi_git/file.rb

@@ -13,7 +13,11 @@ module MultiGit
 
     class Builder < TreeEntry::Builder
       include Base
+      extend Forwardable
+
+      delegate (Blob::Builder.instance_methods - self.instance_methods) => :object
 
+    private
       def make_inner(*args)
         if args.any?
           if args[0].kind_of? Blob::Builder
@@ -24,10 +28,6 @@ module MultiGit
         end
         Blob::Builder.new(*args)
       end
-
-      extend Forwardable
-
-      delegate (Blob::Builder.instance_methods - self.instance_methods) => :object
     end
 
     include Base

data/lib/multi_git/git_backend.rb

@@ -9,6 +9,10 @@ module MultiGit
         true
       end
 
+      # @param (see MultiGit#open)
+      # @raise (see MultiGit#open)
+      # @option (see MultiGit#open)
+      # @return (see MultiGit#open)
       def open(directory, options = {})
         Repository.new(directory, options)
       end

data/lib/multi_git/jgit_backend.rb

@@ -5,6 +5,10 @@ module MultiGit
       def load!
       end
 
+      # @param (see MultiGit#open)
+      # @raise (see MultiGit#open)
+      # @option (see MultiGit#open)
+      # @return (see MultiGit#open)
       def open(path, options = {})
         Repository.new(path, options)
       end

data/lib/multi_git/jgit_backend/commit.rb

@@ -20,11 +20,11 @@ module MultiGit
       end
 
       def time
-        @time ||= java_commit.author_ident.when
+        @time ||= date_to_ruby(java_commit.author_ident.when).freeze
       end
 
       def commit_time
-        @time ||= java_commit.committer_ident.when
+        @time ||= date_to_ruby(java_commit.committer_ident.when).freeze
       end
 
       def author
@@ -36,6 +36,10 @@ module MultiGit
       end
     private
 
+      def date_to_ruby( date )
+        Java::OrgJruby::RubyTime.newTime(JRuby.runtime,Java::OrgJodaTime::DateTime.new(date))
+      end
+
       def java_commit
         @java_commit ||= repository.use_reader{|rd| RevWalk.new(rd).parseCommit(java_oid) }
       end

data/lib/multi_git/jgit_backend/object.rb

@@ -32,9 +32,7 @@ class MultiGit::JGitBackend::Object
 private
 
   def java_stream
-    stream = java_object.openStream
-    stream.mark(bytesize)
-    stream
+    java_object.openStream
   end
 
 protected

data/lib/multi_git/jgit_backend/ref.rb

@@ -5,10 +5,10 @@ module MultiGit
 
       include MultiGit::Ref
 
-      # HACK!
-      # @api private
-      # @visibility private
       if defined? Java::OrgEclipseJgitStorageFile::RefDirectoryUpdate
+        # HACK!
+        # @api private
+        # @visibility private
         class Java::OrgEclipseJgitStorageFile::RefDirectoryUpdate
           public :tryLock, :unlock, :doUpdate, :doDelete
         end

data/lib/multi_git/jgit_backend/rewindeable_io.rb

@@ -10,17 +10,29 @@ class MultiGit::JGitBackend::RewindeableIO < IO
   import "org.jruby.util.io.ChannelStream"
   import "org.jruby.util.io.ChannelDescriptor"
   import "java.nio.channels.Channels"
-  def self.new(inputStream)
-    jruby_io = RubyIO.new(JRuby.runtime, self)
-    jruby_io.openFile.setMainStream(
-       ChannelStream.open(
-         JRuby.runtime,
-         ChannelDescriptor.new(
-           Channels.newChannel(inputStream)
+
+  class JavaRewindeableIO < RubyIO
+  private
+    field_reader :openFile
+    field_writer :openFile
+
+    def initialize(inputStream)
+      super(JRuby.runtime, MultiGit::JGitBackend::RewindeableIO)
+      self.openFile = OpenFile.new
+      openFile.setMainStream(
+         ChannelStream.open(
+           JRuby.runtime,
+           ChannelDescriptor.new(
+             Channels.newChannel(inputStream)
+           )
          )
-       )
-     )
-    jruby_io.openFile.setMode(OpenFile::READABLE)
+      )
+      openFile.setMode(OpenFile::READABLE)
+    end
+  end
+
+  def self.new(inputStream)
+    jruby_io = JavaRewindeableIO.new(inputStream)
     io = JRuby.dereference(jruby_io)
     io.instance_variable_set(:@backend, inputStream)
     return io

data/lib/multi_git/object.rb

@@ -25,6 +25,7 @@ module MultiGit
       return false
     end
 
+    # @visibility private
     alias eql? ==
 
     # @visibility private

data/lib/multi_git/ref.rb

@@ -53,7 +53,7 @@ module MultiGit
         nx = case new
              when Ref, nil then new
              when Object, Builder then repository.write(new)
-             else raise
+             else raise Error::InvalidReferenceTarget, new
              end
         @target = nx
         return nx
@@ -224,8 +224,18 @@ module MultiGit
     end
 
     class RecklessUpdater < Updater
+      class << self
+        attr :updater
+      end
+
+      SUBCLASSES = Hash.new{|hsh,key|
+        hsh[key] = Class.new(self) do
+          @updater = key
+        end
+      }
+
       def update( new )
-        pu = PessimisticFileUpdater.new( ref )
+        pu = self.class.updater.new( ref )
         begin
           pu.update( new )
         ensure
@@ -266,10 +276,10 @@ module MultiGit
     #
     # @return [MultGit::Ref]
     def resolve
-      @leaf = begin
+      @leaf ||= begin
         ref = self
         loop do
-          break ref unless ref.symbolic?
+          break ref unless ref.target.kind_of? MultiGit::Ref
           ref = ref.target
         end
       end
@@ -333,12 +343,12 @@ module MultiGit
     #   @param lock [:reckless, :optimistic, :pessimistic]
     #   @yield [current_target] Yields the current target and expects the block to return the new target
     #   @yieldparam current_target [MultiGit::Ref, MultiGit::Object, nil] current target
-    #   @yieldreturn [MultiGit::Ref, MultiGit::Object, nil] new target
+    #   @yieldreturn [MultiGit::Ref, MultiGit::Object, MultiGit::Builder, nil] new target
     #   @return [MultiGit::Ref] The altered ref
     #
     # @overload update( value )
     #
-    #   @param value [Commit, Ref, nil] new target for this ref
+    #   @param value [MultiGit::Commit, MultiGit::Ref, MultiGit::Builder, nil] new target for this ref
     #   @return [MultiGit::Ref] The altered ref
     #
     # @example
@@ -436,7 +446,7 @@ module MultiGit
     end
 
     def reckless_updater
-      RecklessUpdater
+      RecklessUpdater::SUBCLASSES[pessimistic_updater]
     end
 
     def updater_class( block_given, lock )
@@ -445,6 +455,8 @@ module MultiGit
         when :optimistic  then optimistic_updater
         when :pessimistic then pessimistic_updater
         when :reckless    then reckless_updater
+        else
+          raise ArgumentError, "Locking method must be either :optimistic, :pessimistic or :reckless. You supplied: #{lock.inspect}"
         end
       else
         pessimistic_updater

data/lib/multi_git/repository.rb

@@ -10,6 +10,22 @@ require 'multi_git/executeable'
 require 'multi_git/submodule'
 
 # Abstract base class for all repository implementations.
+#
+# @example Creating a new repository
+#   # setup:
+#   dir = `mktemp -d`
+#   # example:
+#   repo = MultiGit.open(dir, init: true) #=> be_a MultiGit::Repository
+#   repo.bare? #=> eql false
+#   repo.git_dir #=> eql dir + '/.git'
+#   repo.git_work_tree #=> eql dir
+#   # creating a first commit:
+#   repo.branch('master').commit do
+#     tree['file'] = 'content'
+#   end
+#   # teardown:
+#   `rm -rf #{dir}`
+#
 # @abstract
 class MultiGit::Repository
 
@@ -29,29 +45,33 @@ public
 
   # @!method git_dir
   #   @abstract
-  #   Return the repository base directory
+  #   Returns the repository directory (the place where the internal stuff is stored)
   #   @return [String]
   abstract :git_dir
 
+  # @!method git_work_tree
+  #   @abstract
+  #   Returns the working directory (the place where your files are)
+  #   @return [String]
+  abstract :git_work_tree
+
   # @!method bare?
   #   @abstract
   #   Is this repository bare?
   abstract :bare?
 
-  # @!method initialize(directory, options = {})
-  #   @param directory [String] a directory
-  #   @option options [Boolean] :init init the repository if it doesn't exist
-  #   @option options [Boolean] :bare open/init the repository bare
+  # @!group Object interface
 
-  # @!method read(ref)
-  #   Reads a reference.
+  # @!method read(expression)
+  #   Reads an object from the database.
   #
+  #   @see http://git-scm.com/docs/git-rev-parse#_specifying_revisions Revision expression syntax
   #   @abstract
   #
   #   @raise [MultiGit::Error::InvalidReference] if ref is not a valid reference
   #   @raise [MultiGit::Error::AmbiguousReference] if ref refers to multiple objects
   #   @raise [MultiGit::Error::BadRevisionSyntax] if ref does not contain a valid ref-syntax
-  #   @param [String] ref
+  #   @param [String] expression
   #   @return [MultiGit::Object] object
   abstract :read
 
@@ -62,10 +82,12 @@ public
   #   @return [Boolean]
   abstract :include?
 
-  # @!method parse(ref)
-  #   Resolves a reference into an oid.
+  # @!method parse(expression)
+  #   Resolves an expression into an oid.
   #   @abstract
-  #   @param [String] rev
+  #
+  #   @see http://git-scm.com/docs/git-rev-parse#_specifying_revisions Revision expression syntax
+  #   @param [String] expression
   #   @raise [MultiGit::Error::InvalidReference] if ref is not a valid reference
   #   @raise [MultiGit::Error::AmbiguousReference] if ref refers to multiple objects
   #   @raise [MultiGit::Error::BadRevisionSyntax] if ref does not contain a valid ref-syntax
@@ -78,10 +100,10 @@ public
   #   If called with a String or an IO, this method creates a {MultiGit::Blob} with the
   #   given content. This is the easiest way to create blobs.
   #
-  #   If called with a {MultiGit::Object}, this method determines if the object does already exist 
+  #   If called with a {MultiGit::Object}, this method determines if the object does already exist
   #   and writes it otherwise.
   #
-  #   If called with a {MultiGit::Builder}, this method inserts the content of the builder to the 
+  #   If called with a {MultiGit::Builder}, this method inserts the content of the builder to the
   #   repository. This is the easiest way to create trees/commits.
   #
   #   @abstract
@@ -89,6 +111,14 @@ public
   #   @return [MultiGit::Object] the resulting object
   abstract :write
 
+  # @!parse alias_method :<<, :write
+  def <<(*args,&block)
+    write(*args,&block)
+  end
+
+  # @!endgroup
+  # @!group References interface
+
   # @!method ref(name)
   #   Opens a reference. A reference is usually known as branch or tag.
   #
@@ -107,7 +137,7 @@ public
   #   @return [MultiGit::Ref] ref
   abstract :ref
 
-  # Gets the ref
+  # Gets the HEAD ref.
   # @return [Ref] head
   def head
     return ref('HEAD')
@@ -115,6 +145,18 @@ public
 
   # Opens a branch
   #
+  # @example
+  #   # setup:
+  #   dir = `mktemp -d`
+  #   # example:
+  #   repository = MultiGit.open(dir, init: true)
+  #   # getting a local branch
+  #   repository.branch('master') #=> be_a MultiGit::Ref
+  #   # getting a remote branch
+  #   repository.branch('origin/master') #=> be_a MultiGit::Ref
+  #   # teardown:
+  #   `rm -rf #{dir}`
+  #
   # @param name [String] branch name
   # @return [Ref]
   def branch(name)
@@ -134,8 +176,8 @@ public
   end
 
   # @method each_branch( filter = :all )
-  #   Yields either all, local or remote branches. If called 
-  #   with a regular expression it will be used to filter the 
+  #   Yields either all, local or remote branches. If called
+  #   with a regular expression it will be used to filter the
   #   branches by name.
   #
   #   @param filter [:all, :local, :remote, Regexp]
@@ -145,7 +187,6 @@ public
   #
   abstract :each_branch
 
-
   # @method each_tag
   #   Yields all tags.
   #
@@ -160,10 +201,7 @@ public
     ref(name)
   end
 
-  # @!parse alias_method :<<, :write
-  def <<(*args,&block)
-    write(*args,&block)
-  end
+  # !@endgroup
 
   # @visibility private
   def inspect
@@ -254,3 +292,4 @@ protected
   end
 
 end
+

data/lib/multi_git/rugged_backend.rb

@@ -6,6 +6,10 @@ module MultiGit
       def load!
       end
 
+      # @param (see MultiGit#open)
+      # @raise (see MultiGit#open)
+      # @option (see MultiGit#open)
+      # @return (see MultiGit#open)
       def open(path, options = {})
         Repository.new(path, options)
       end

data/lib/multi_git/symlink.rb

@@ -18,6 +18,10 @@ module MultiGit
 
       include Base
 
+      def target=(t)
+        object.content = t
+      end
+    private
       def make_inner(*args)
         if args.any?
           if args[0].kind_of? Blob::Builder
@@ -28,11 +32,6 @@ module MultiGit
         end
         Blob::Builder.new(*args)
       end
-
-      def target=(t)
-        object.content = t
-      end
-
     end
 
     include Base

data/lib/multi_git/tree.rb

@@ -16,10 +16,6 @@ module MultiGit
         :tree
       end
 
-      def parent?
-        false
-      end
-
       def key?(key)
         if key.kind_of? String
           return entries.key?(key)
@@ -52,10 +48,10 @@ module MultiGit
         while parts.any?
           part = parts.pop
           if part == '..'
-            unless current.parent?
+            unless current.respond_to?(:parent) && p = current.parent
               raise MultiGit::Error::InvalidTraversal, "Can't traverse to parent of #{current.inspect} since I don't know where it is."
             end
-            current = current.parent
+            current = p
           elsif part == '.' || part == ''
             # do nothing
           else
@@ -130,10 +126,16 @@ module MultiGit
         return self
       end
 
-      # @yield [MultiGit::TreeEntry]
+
+      # @overload each(&block)
+      #   @yield [entry]
+      #   @yieldparam entry [MultiGit::TreeEntry]
+      #
+      # @overload each
+      #   @return [Enumerable]
       def each
         return to_enum unless block_given?
-        entries.each do |name, entry|
+        entries.each do |_, entry|
           yield entry
         end
         return self
@@ -170,31 +172,44 @@ module MultiGit
         entries.keys
       end
 
+      # @api private
       def ==( other )
         return false unless other.respond_to? :entries
         entries == other.entries
       end
 
+      # @api private
+      alias eql? ==
+
+      # @api private
+      def hash
+        entries.hash
+      end
+
+      # @return [Hash<String, MultiGit::TreeEntry>]
+      def entries
+        @entries ||= Hash[ raw_entries.map{|name, mode, oid| [name, make_entry(name, mode, oid) ] } ]
+      end
     end
 
     include Base
     include Object
 
+    # @return [Builder]
     def to_builder
       Builder.new(self)
     end
 
+    # @return [Directory]
+    def with_parent(parent, name)
+      Directory.new(parent, name, self)
+    end
+
     # @visibility private
     def inspect
       ['#<',self.class.name,' ',oid,' repository:', repository.inspect,'>'].join
     end
-
   protected
-    # @return [Hash<String, MultiGit::TreeEntry>]
-    def entries
-      @entries ||= Hash[ raw_entries.map{|name, mode, oid| [name, make_entry(name, mode, oid) ] } ]
-    end
-
     def raw_entries
       raise Error::NotYetImplemented, "#{self.class}#each_entry"
     end

data/lib/multi_git/tree/builder.rb

@@ -10,28 +10,40 @@ module MultiGit
     include MultiGit::Builder
     include Tree::Base
 
-    attr :entries
+    # @return [Hash<String,MultiGit::TreeEntry::Base>]
+    attr :dirty_entries
+    private :dirty_entries
+
+    # @return [MultiGit::Tree::Base, nil]
     attr :from
 
     def initialize(from = nil, &block)
-      @entries = {}
+      @dirty_entries = {}
       @from = from
       instance_eval(&block) if block
     end
 
+    # @param [String] key
+    # @return [TreeEntry::Builder, nil]
     def entry(key)
       if @from
-        @entries.fetch(key) do
+        dirty_entries.fetch(key) do
           e = @from.entry(key)
           if e
-            @entries[key] = e.to_builder.with_parent(self)
+            dirty_entries[key] = e.to_builder.with_parent(self)
           end
         end
       else
-        @entries[key]
+        dirty_entries[key]
       end
     end
 
+    # @overload each(&block)
+    #   @yield [entry]
+    #   @yieldparam entry [MultiGit::TreeEntry]
+    #
+    # @overload each
+    #   @return [Enumerable]
     def each
       return to_enum unless block_given?
       names.each do |name|
@@ -42,7 +54,7 @@ module MultiGit
     # TODO: cache
     def names
       names = @from ? @from.names.dup : []
-      @entries.each do |k,v|
+      dirty_entries.each do |k,v|
         if v
           unless names.include? k
             names << k
@@ -54,13 +66,18 @@ module MultiGit
       return names
     end
 
+    # @return [Hash<String,MultiGit::TreeEntry::Builder>]
+    def entries
+      Hash[names.map do |n| [n, entry(n)] end ]
+    end
+
     def size
       names.size
     end
 
     def >>(repository)
       ent = []
-      @entries.each do |name, entry|
+      dirty_entries.each do |name, entry|
         if entry
           object = repository.write(entry)
           ent << [name, object.mode, object.oid]
@@ -68,7 +85,7 @@ module MultiGit
       end
       if @from
         @from.each do |entry|
-          unless @entries.key? entry.name
+          unless dirty_entries.key? entry.name
             ent << [entry.name, entry.mode, entry.oid]
           end
         end
@@ -76,8 +93,27 @@ module MultiGit
       return repository.make_tree(ent)
     end
 
+    # @param (see Object#with_parent)
+    # @return [Directory::Builder]
+    def with_parent(parent, name)
+      Directory::Builder.new(parent, name, self)
+    end
+
     module DSL
 
+      # @overload set(path, options = {:create => true }, &block)
+      #   @param [String] path
+      #   @param [Hash] options
+      #   @yield [parent, name]
+      #   @yieldparam parent [MultiGit::Tree, nil]
+      #   @yieldparam name [String]
+      #   @yieldreturn [#with_parent, nil]
+      #
+      # @overload set(path, options = {:create => true }, value)
+      #   @param [String] path
+      #   @param [Hash] options
+      #   @param [#with_parent, nil] value
+      #
       def set(key, *args, &block)
         options = {}
         case(args.size)
@@ -108,8 +144,9 @@ module MultiGit
 
       alias []= set
 
+      # @api private
       def entry_set(key, value)
-        entries[key] = make_entry(key, value)
+        dirty_entries[key] = make_entry(key, value)
       end
 
       def make_entry(key, value)
@@ -120,12 +157,13 @@ module MultiGit
           return value
         elsif value.kind_of? String
           return MultiGit::File::Builder.new(self, key, value)
-        elsif value.kind_of? MultiGit::Builder
-          return value.with_parent(self)
+        elsif value.respond_to? :with_parent
+          return value.with_parent(self, key)
         else
           raise ArgumentError, "No idea what to do with #{value.inspect}"
         end
       end
+      private :make_entry
 
       def traverse_set(current, parts, value, create)
         if parts.none?
@@ -157,6 +195,7 @@ module MultiGit
         current.entry_set(part, traverse_set(entry, rest, value, create))
         return current
       end
+      private :traverse_set
 
       def file(name, content = nil, &block)
         set(name){|parent, name|
@@ -186,6 +225,14 @@ module MultiGit
         set(name){ nil }
       end
 
+      def clear
+        names.each do |name|
+          delete(name)
+        end
+        return nil
+      end
+
+      # @return [self]
       def to_builder
         self
       end
@@ -199,7 +246,8 @@ module MultiGit
       #   builder.file('a_file','some content')
       #   builder.changed? 'a_file' #=> eq true
       #   builder.changed? 'another_file' #=> eq false
-      def changed?( path )
+      #   builder.changed? #=> eq true
+      def changed?( path = '.' )
         begin
           new = traverse(path)
         rescue Error::EntryDoesNotExist

data/lib/multi_git/tree_entry.rb

@@ -3,8 +3,10 @@ require 'multi_git/object'
 require 'multi_git/builder'
 require 'multi_git/walkable'
 module MultiGit
-  # A tree entry is like a {MultiGit::Object} or a {MultiGit::Builder} but it 
-  # also has knows it's parent tree.
+  # A tree entry is a {MultiGit::Object} or a {MultiGit::Builder} that
+  # knows its parent tree and therefore supports several additional operations.
+  # 
+  # @abstract
   class TreeEntry
 
     module Base
@@ -13,7 +15,7 @@ module MultiGit
 
       # @return [String]
       attr :name
-      # @return [MultiGit::Tree::Base]
+      # @return [MultiGit::Tree::Base, nil]
       attr :parent
 
       extend MultiGit::Utils::AbstractMethods
@@ -36,6 +38,17 @@ module MultiGit
         self.class.new(parent, name, @object)
       end
 
+      # Returns the full path to this entry.
+      #
+      # @example
+      #   tree = MultiGit::Tree::Builder.new do
+      #     directory "a" do
+      #       file "b", "content"
+      #     end
+      #   end
+      #   tree['a/b'].path #=> eql 'a/b'
+      #
+      # @return [String]
       def path
         @path ||= begin
                     if parent.respond_to? :path
@@ -46,17 +59,20 @@ module MultiGit
                   end
       end
 
+      # @visibility private
       def ==(other)
         return false unless other.respond_to?(:path) && other.respond_to?(:object) && other.respond_to?(:mode)
         return (path == other.path) && (object == other.object) && (mode == other.mode)
       end
 
+      # @visibility private
       def inspect
         ['#<', self.class.name,'@',path,' ', object.inspect, '>'].join
       end
-   end
+    end
 
-    class Builder# < Base
+    # @abstract
+    class Builder
 
       include MultiGit::Builder
       include Base
@@ -93,7 +109,6 @@ module MultiGit
       self.class::Builder.new(parent, name, object)
     end
 
-
   end
 
 end

data/lib/multi_git/version.rb

@@ -1,3 +1,3 @@
 module MultiGit
-  VERSION = '0.0.1.rc1'
+  VERSION = '0.0.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: multi_git
 version: !ruby/object:Gem::Version
-  version: 0.0.1.rc1
+  version: 0.0.1
 platform: ruby
 authors:
 - Hannes Georg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-29 00:00:00.000000000 Z
+date: 2013-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -100,62 +100,62 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/multi_git/handle.rb
-- lib/multi_git/commit.rb
-- lib/multi_git/walkable.rb
-- lib/multi_git/executeable.rb
-- lib/multi_git/tree/builder.rb
-- lib/multi_git/submodule.rb
+- lib/multi_git.rb
+- lib/multi_git/backend.rb
+- lib/multi_git/backend_set.rb
 - lib/multi_git/blob.rb
-- lib/multi_git/object.rb
+- lib/multi_git/builder.rb
+- lib/multi_git/commit.rb
+- lib/multi_git/config.rb
+- lib/multi_git/config/default_schema.rb
+- lib/multi_git/config/schema.rb
 - lib/multi_git/directory.rb
-- lib/multi_git/jgit_backend.rb
-- lib/multi_git/version.rb
-- lib/multi_git/file.rb
 - lib/multi_git/error.rb
-- lib/multi_git/refspec.rb
-- lib/multi_git/backend.rb
-- lib/multi_git/tree.rb
-- lib/multi_git/config.rb
-- lib/multi_git/ref.rb
-- lib/multi_git/builder.rb
-- lib/multi_git/remote.rb
-- lib/multi_git/git_backend/commit.rb
+- lib/multi_git/executeable.rb
+- lib/multi_git/file.rb
+- lib/multi_git/git_backend.rb
 - lib/multi_git/git_backend/blob.rb
-- lib/multi_git/git_backend/object.rb
 - lib/multi_git/git_backend/cmd.rb
-- lib/multi_git/git_backend/tree.rb
+- lib/multi_git/git_backend/commit.rb
 - lib/multi_git/git_backend/config.rb
+- lib/multi_git/git_backend/object.rb
 - lib/multi_git/git_backend/ref.rb
 - lib/multi_git/git_backend/remote.rb
 - lib/multi_git/git_backend/repository.rb
-- lib/multi_git/symlink.rb
+- lib/multi_git/git_backend/tree.rb
+- lib/multi_git/handle.rb
+- lib/multi_git/jgit_backend.rb
+- lib/multi_git/jgit_backend/blob.rb
+- lib/multi_git/jgit_backend/commit.rb
+- lib/multi_git/jgit_backend/config.rb
+- lib/multi_git/jgit_backend/object.rb
+- lib/multi_git/jgit_backend/ref.rb
+- lib/multi_git/jgit_backend/remote.rb
+- lib/multi_git/jgit_backend/repository.rb
+- lib/multi_git/jgit_backend/rewindeable_io.rb
+- lib/multi_git/jgit_backend/tree.rb
+- lib/multi_git/object.rb
+- lib/multi_git/ref.rb
+- lib/multi_git/refspec.rb
+- lib/multi_git/remote.rb
 - lib/multi_git/repository.rb
-- lib/multi_git/git_backend.rb
-- lib/multi_git/config/default_schema.rb
-- lib/multi_git/config/schema.rb
 - lib/multi_git/rugged_backend.rb
-- lib/multi_git/utils.rb
-- lib/multi_git/tree_entry.rb
-- lib/multi_git/backend_set.rb
-- lib/multi_git/rugged_backend/commit.rb
 - lib/multi_git/rugged_backend/blob.rb
-- lib/multi_git/rugged_backend/object.rb
-- lib/multi_git/rugged_backend/tree.rb
+- lib/multi_git/rugged_backend/commit.rb
 - lib/multi_git/rugged_backend/config.rb
+- lib/multi_git/rugged_backend/object.rb
 - lib/multi_git/rugged_backend/ref.rb
 - lib/multi_git/rugged_backend/remote.rb
 - lib/multi_git/rugged_backend/repository.rb
-- lib/multi_git/jgit_backend/commit.rb
-- lib/multi_git/jgit_backend/blob.rb
-- lib/multi_git/jgit_backend/object.rb
-- lib/multi_git/jgit_backend/tree.rb
-- lib/multi_git/jgit_backend/config.rb
-- lib/multi_git/jgit_backend/ref.rb
-- lib/multi_git/jgit_backend/remote.rb
-- lib/multi_git/jgit_backend/repository.rb
-- lib/multi_git/jgit_backend/rewindeable_io.rb
-- lib/multi_git.rb
+- lib/multi_git/rugged_backend/tree.rb
+- lib/multi_git/submodule.rb
+- lib/multi_git/symlink.rb
+- lib/multi_git/tree.rb
+- lib/multi_git/tree/builder.rb
+- lib/multi_git/tree_entry.rb
+- lib/multi_git/utils.rb
+- lib/multi_git/version.rb
+- lib/multi_git/walkable.rb
 homepage: https://github.com/hannesg/multi_git
 licenses:
 - GPL-3
@@ -171,13 +171,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements:
 - jar 'org.eclipse.jgit:org.eclipse.jgit'
 rubyforge_project: 
-rubygems_version: 2.1.4
+rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
 summary: Use all the git