git-ds 0.9.2

data/lib/git-ds/model/item_list.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::ModelItemList
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+module GitDS
+
+=begin rdoc
+A generic list of ModelItem objects.
+
+This associates a ModelItem class with a model and a base path in that model.
+All elements in this list are subdirectories of the base path, and will be
+instantiated/created/listed using methods in the ModelItem class.
+
+This is used for ModelItem children of a ModelItem object (NOT Property
+children).
+=end
+  class ModelItemList
+    include Enumerable
+
+    def initialize(cls, model, path)
+      @item_class = cls
+      @model = model
+      @base_path = path
+    end
+
+=begin rdoc
+List ModelItem class instances contained in this list.
+
+Note: This always returns a sorted list.
+=end
+    def keys
+      @item_class.list_in_path(@model, @base_path)
+    end
+
+=begin rdoc
+Return number of items in list.
+=end
+    def count
+      keys.count
+    end
+
+=begin rdoc
+Return first item list.
+=end
+    def first
+      keys.first 
+    end
+
+=begin rdoc
+Return last item list.
+=end
+    def last
+      keys.last
+    end
+
+=begin rdoc
+Yield each ident in list.
+
+See keys.
+=end
+    def each
+      keys.each { |key| yield key }
+    end
+
+=begin rdoc
+Return instance of ModelItem class for 'ident'.
+=end
+    def [](ident)
+      @item_class.new(@model, @item_class.instance_path(@base_path, ident))
+    end
+
+=begin rdoc
+Add an instance of ModelItem class to 'parent' based on 'args'.
+
+Note: This calls ModelItemClass.create, so args must be a suitable Hash. When
+a ProxyModelItemClass is used as the item class, the args will be passed to
+ProxyModelItemClass.create.
+=end
+    def add(parent, args)
+      @item_class.create(parent, args)
+    end
+
+=begin rdoc
+Delete instance of ModelItem from list.
+
+Note: this has the same effect as just calling item#delete.
+=end
+    def delete(ident)
+      item = self[ident]
+      item.delete if item
+    end
+  end
+
+end

data/lib/git-ds/model/item_proxy.rb

@@ -0,0 +1,128 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::ModelItemProxy
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'git-ds/model/item_list'
+
+module GitDS
+
+=begin rdoc
+Exception raised by errors in creating ModelItemClassProxy instances, e.g.
+bad target or link path.
+=end
+  class ProxyItemError < RuntimeError
+  end
+
+=begin rdoc
+Proxy a ModelItem class.
+
+This is used to store a link to a ModelItem class instance. A ModelItemList can
+be passed a ModelItemClassProxy instance as its cls parameter in order to
+store a list of links to ModelItem class instances.
+=end
+  class ModelItemClassProxy
+
+    def initialize(cls)
+      @true_class = cls
+    end
+
+=begin rdoc
+List ModelItem class instances contained in this list.
+
+Note: this is passed to the proxied class, as it is just a list of idents.
+
+Instantiating and adding an ident is handled by this class.
+=end
+    def list_in_path(model, path)
+      @true_class.list_in_path(model, path)
+    end
+
+=begin rdoc
+Return instance of ModelItem class for 'ident'.
+=end
+    def new(model, link_path)
+      # read path to ModelItem instance from link file at 'link_path'
+      instance_path = model.get_item(link_path)
+      raise ProxyItemError.new("Invalid ProxyItem path: #{link_path}") if \
+            (not instance_path) || (instance_path.empty?)
+
+      @true_class.new(model, instance_path.chomp)
+    end
+
+=begin rdoc
+This is passed to the proxied class, as it just returns class_dir + ident.
+=end
+    def instance_path(base_path, ident)
+      @true_class.instance_path(base_path, ident)
+    end
+
+=begin rdoc
+Create a link to ModelItem.
+
+The ModelItem class ident() method will be used to find the ident of the
+instance in the args Hash.
+
+The full path to the instance is expected to be in the :path key of the args
+Hash.
+
+If args[:fs] is not nil or false, the link file will be created on-filesystem
+as well as in-db.
+=end
+    def create(parent, args)
+      link_path = instance_path(parent.path, @true_class.ident(args))
+      raise ProxyItemError.new("Invalid ProxyItem path: #{link_path}") if \
+            (not link_path) || (link_path.empty?)
+
+      path = args[:path]
+      raise ProxyItemError.new('Invalid ModelItem path') if (not path) || \
+            (path.empty?)
+
+      # write path to ModelItem into link file at 'instance path'
+      args[:fs] ? parent.model.add_fs_item(link_path, path.to_s + "\n") \
+                : parent.model.add_item(link_path, path.to_s + "\n")
+    end
+
+  end
+
+=begin rdoc
+A generic list of links to ModelItemClass instance of a specific class.
+
+Example:
+     class a/1/name
+     class a/1/data
+     class a/2/name
+     class a/2/data
+     class b/1/a/1
+     class b/1/a/2
+class b/$ID/a is a list of links to class a objects.
+=end
+  class ProxyItemList < ModelItemList
+
+    def initialize(cls, model, path)
+      @true_class = cls
+      @proxy_class = ModelItemClassProxy.new(cls)
+      super @proxy_class, model, path
+    end
+
+=begin rdoc
+Add a link to 'obj' to the list.
+=end
+    def add(parent, obj, on_fs=false)
+      args = { :path => obj.path, :fs => on_fs }
+      args[@true_class.ident_key] = obj.ident
+      super parent, args
+    end
+
+=begin rdoc
+Delete a link from the list. This does not delete the object that was linked
+to.
+=end
+    def delete(ident)
+      @model.delete_item @proxy_class.instance_path(@base_path, ident)
+    end
+  end
+
+end

data/lib/git-ds/model/property.rb

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::PropertyDefinition
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'git-ds/shared'
+
+module GitDS
+
+=begin rdoc
+Exception raised when duplicate properties (i.e. having the same name) are
+defined for a single class.
+=end
+  class DuplicatePropertyError < ArgumentError
+    def initialize(name)
+      super "Duplicate property '#{name}'"
+    end
+  end
+
+=begin rdoc
+Exception raised when Property#valid? returns false.
+=end
+  class InvalidPropertyValueError < ArgumentError
+    def initialize(name, value)
+      super "Invalid value '#{value}' for property '#{name}'"
+    end
+  end
+
+=begin rdoc
+A definition of a ModelItem property.
+
+These are stored in the class, and are used to wrap access to properties
+by ModelItem objects.
+=end
+  class PropertyDefinition
+
+=begin rdoc
+Name of the property, e.g. 'size'.
+=end
+    attr_accessor :name
+
+=begin rdoc
+Default value, e.g. '0'.
+=end
+    attr_accessor :default_value
+
+=begin rdoc
+Property exists on-disk as well as in the object db.
+=end
+    attr_accessor :on_fs
+
+=begin rdoc
+Block used to validate data when set.
+=end
+    attr_accessor :validation_block
+
+    def initialize(name, default=nil, fs=false, &block)
+      @name = name
+      @default_value = default
+      @on_fs = fs
+      @validation_block = (block_given?) ? block : nil
+    end
+
+=begin rdoc
+Get full path to BLOB for property based on parent directory.
+=end
+    def path(parent_path)
+      parent_path + ::File::SEPARATOR + name.to_s
+    end
+
+=begin rdoc
+Read value from ModelItem at path in Model.
+This just returns the String value of the property file contents; subclasses
+should wrap this with a call that will generate an Integer, List, etc from
+the contents.
+=end
+    def get(model, parent_path)
+      val = model.get_item(path(parent_path))
+      val ? val.chomp : ''
+    end
+
+=begin rdoc
+Write value to ModelItem at path in Model.
+
+Note: this returns the String representation of the value as written to the
+Property BLOB.
+=end
+    def set(model, parent_path, value)
+      raise InvalidPropertyValueError.new(name, value) if not valid? value
+      val = value.to_s
+
+      if value.kind_of?(Array)
+        val = value.join("\n")
+      elsif value.kind_of?(Hash)
+        val = value.inspect
+      end
+
+      on_fs ? model.add_fs_item(path(parent_path), val + "\n") \
+            : model.add_item(path(parent_path), val + "\n")
+      val
+    end
+
+=begin rdoc
+If property has a validation block, invoke it to determine if value is
+valid. Otherwise, return true.
+=end
+    def valid?(value)
+      blk = self.validation_block
+      blk ? blk.call(value) : true
+    end
+
+    alias :default :default_value
+
+  end
+
+=begin rdoc
+A Property that is a link to a ModelItem class instance.
+=end
+  class ProxyProperty < PropertyDefinition
+    attr_reader :obj_class
+    def initialize(name, cls, fs=false, &block)
+      super name, nil, fs, &block
+      @obj_class = cls
+    end
+
+=begin rdoc
+Write path of object to property.
+=end
+    def set(model, parent_path, obj)
+      super model, parent_path, obj.path
+    end
+
+=begin rdoc
+Instantiate object from path stored in property.
+=end
+    def get(model, parent_path)
+      path = super model, parent_path
+      @obj_class.new(model, path) if path && (not path.empty?)
+    end
+  end
+
+end

data/lib/git-ds/model/root.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::RootItem
+=begin rdoc
+
+Copyright 2011 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'git-ds/shared'
+require 'git-ds/model/item'
+
+module GitDS
+
+=begin rdoc
+A mock ModelItem that acts as the root of the data model.
+=end
+  class RootItem
+    attr_reader :model
+    attr_reader :path
+
+    def initialize(model)
+      @path = ''
+      @model = model
+    end
+
+    def delete
+      # nop
+    end
+
+    def self.name
+      ''
+    end
+
+    def self.path
+      ''
+    end
+
+    def self.create(parent, args)
+      return @model.root
+    end
+
+    def self.list
+      return []
+    end
+
+  end
+end

data/lib/git-ds/repo.rb

@@ -0,0 +1,455 @@
+#!/usr/bin/env ruby
+# :title: Git-DS::Repo
+=begin rdoc
+Grit wrappers.
+
+Copyright 2010 Thoughtgang <http://www.thoughtgang.org>
+=end
+
+require 'rubygems'
+require 'grit'
+
+require 'git-ds/index'
+require 'git-ds/shared'
+
+# TODO: mutex for staging
+# TODO: cross-process (file) locking? via config or something. Maybe in Database
+
+module GitDS
+
+=begin rdoc
+Error raised when a command-line Git command files.
+=end
+  class CommandError < RuntimeError
+  end
+
+=begin rdoc
+A Git repository.
+
+Note: StagingIndex is cached, as it is from the command line.
+=end
+  class Repo < Grit::Repo
+    GIT_DIR = ::File::SEPARATOR + '.git'
+
+    DEFAULT_TAG = '0.0.0'
+    attr_reader :last_branch_tag
+
+    DEFAULT_BRANCH='master'
+    attr_reader :current_branch
+
+    attr_reader :path
+
+    # TODO: something more intelligent, e.g. with git/repo options
+    def self.create(path)
+      Grit::Repo.init(path)
+      self.new(path)          # discard Grit::Repo object and use a Repo object
+    end
+
+=begin rdoc
+Return the top-level directory of the repo containing the location 'path'.
+=end
+    def self.top_level(path='.')
+      local = (path == '.')
+      old_dir = nil
+
+      if path != '.'
+        old_dir = Dir.getwd
+        dest = (File.directory? path) ? path : File.dirname(path)
+        Dir.chdir dest
+      end
+
+      dir = `git rev-parse --show-toplevel`
+
+      Dir.chdir old_dir if old_dir
+
+      dir.chomp
+    end
+
+=begin rdoc
+Initialize a repo from the .git subdir in the given path.
+=end
+    def initialize(path)
+      path.chomp(GIT_DIR) if path.end_with? GIT_DIR
+      @path = (path.empty?) ? '.' : path
+
+      # TODO: get last branch tag from repo
+      #       prob as a git-config
+      @last_branch_tag = DEFAULT_TAG.dup
+      @current_branch = DEFAULT_BRANCH.dup
+      @staging_index = nil
+      @saved_stages = {}
+
+      super(@path + GIT_DIR)
+    end
+
+=begin rdoc
+Return the top-level directory of the repo (the parent of .git).
+=end
+    def top_level
+      git.git_dir.chomp(GIT_DIR)
+    end
+
+=begin rdoc
+Return true if path exists in repo (on fs or in-tree)
+=end
+    def include?(path)
+      path_to_object(path) ? true : false
+    end
+
+    alias :exist? :include?
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Return a cleaned-up version of the tag name, suitable for use as a filename.
+Replaces all non-alphanumeric characters (except "-.,") with "_". 
+=end
+    def clean_tag(name)
+      name.gsub( /[^-.,_[:alnum:]]/, '_' )
+    end
+
+=begin rdoc
+Returns the next value for a tag. This is primarily used to auto-generate
+tag names, e.g. 1.0.1, 1.0.2, etc.
+=end
+    def next_branch_tag
+      @last_branch_tag.succ!
+    end
+
+=begin rdoc
+Return the Head object for the specified branch
+=end
+    def branch(tag=@current_branch)
+      get_head(tag)
+    end
+
+=begin rdoc
+Creates a branch in refs/heads and associates it with the specified commit.
+If sha is nil, the latest commit from 'master' is used.
+The canonical name of the tag is returned.
+=end
+    def create_branch( tag=next_branch_tag(), sha=nil )
+      if not sha
+        sha = commits.first.id
+        #sha = branches.first.commit.id if not sha
+      end
+      name = clean_tag(tag)
+      update_ref(name, sha)
+      name
+    end
+
+=begin rdoc
+Sets the current branch to the specified tag. This changes the default
+branch for all repo activity and sets HEAD.
+=end
+    def set_branch( tag, actor=nil )
+      # allow creating of new branches
+      opt = (is_head? tag) ? '' : '-b'
+
+      # Save staging index for current branch
+      @saved_stages[@current_branch] = self.staging if self.staging?
+
+      exec_git_cmd( "git checkout -q -m #{opt} '#{tag}'", actor )
+
+      # Synchronize staging index (required before merge)
+      unstage
+      self.staging.sync
+
+      # Update current_branch info and restore staging for branch
+      self.staging = @saved_stages[tag]
+      @current_branch = tag
+    end
+
+=begin rdoc
+Merge specified branch into master.
+=end
+    def merge_branch( tag=@current_branch, actor=nil )
+      raise "Invalid branch '#{tag}'" if not (is_head? tag)
+
+      tag.gsub!(/['\\]/, '')
+
+      # switch to master branch
+      set_branch(DEFAULT_BRANCH, actor)
+
+      # merge target branch to master branch
+
+      rv = nil
+      begin
+        rv = exec_git_cmd("git merge -n --no-ff --no-log --no-squash '#{tag}'", 
+                          actor)
+      rescue CommandError => e
+        $stderr.puts e.message
+      end
+      rv
+    end
+
+=begin rdoc
+Tag (name) an object, e.g. a commit.
+=end
+    def tag_object(tag, sha)
+      git.fs_write("refs/tags/#{clean_tag(tag)}", sha)
+    end
+
+# ----------------------------------------------------------------------
+
+=begin rdoc
+Return an empty git index for the repo.
+=end
+    def index_new
+      Index.new(self)
+    end
+
+=begin rdoc
+Return the staging index for the repo.
+=end
+    def staging
+      # TODO: mutex
+      @staging_index ||= StageIndex.new(self)
+    end
+
+=begin rdoc
+Set the staging index. This can be used to clear the staging index, or to
+use a specific index as the staging index.
+=end
+    def staging=(idx)
+      # TODO: mutex
+      @staging_index = idx
+    end
+
+=begin rdoc
+Close staging index.
+This discards all (non-committed) changes in the staging index.
+=end
+    def unstage
+      self.staging=(nil)
+    end
+
+=begin rdoc
+Return true if a staging index is active.
+=end
+    def staging?
+      @staging_index != nil
+    end
+
+    alias :index :staging
+    alias :index= :staging=
+    
+=begin rdoc 
+Yield staging index to the provided block, then write the index when the
+block returns.
+This allows the Git staging index to be modified from within Ruby, with all
+changes being visible to the Git command-line tools.
+Returns staging index for chaining purposes.
+=end
+    def stage(&block)
+      idx = self.staging
+      rv = yield idx
+      idx.build
+      rv
+    end
+
+=begin rdoc
+Read the Git staging index, then commit it with the provided message and
+author info.
+Returns SHA of commit.
+=end
+    def stage_and_commit(msg, actor=nil, &block)
+      stage(&block)
+      self.staging.commit(msg, actor)
+    end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+Change to the Repo#top_level dir, yield to block, then pop the dir stack.
+=end
+    def exec_in_git_dir(&block)
+      curr = Dir.getwd
+      Dir.chdir top_level
+      result = yield
+      Dir.chdir curr
+      result
+    end
+
+=begin rdoc
+Execute the specified command using Repo#exec_in_git_dir.
+=end
+    def exec_git_cmd( cmd, actor=nil )
+      old_aname = ENV['GIT_AUTHOR_NAME']
+      old_aemail = ENV['GIT_AUTHOR_EMAIL']
+      old_cname = ENV['GIT_COMMITTER_NAME']
+      old_cemail = ENV['GIT_COMMITTER_EMAIL']
+      old_pager = ENV['GIT_PAGER']
+
+      if actor
+        ENV['GIT_AUTHOR_NAME'] = actor.name
+        ENV['GIT_AUTHOR_EMAIL'] = actor.email
+        ENV['GIT_COMMITTER_NAME'] = actor.name
+        ENV['GIT_COMMITTER_EMAIL'] = actor.email
+      end
+      ENV['GIT_PAGER'] = ''
+
+      # Note: we cannot use Grit#raw_git_call as it requires an index file
+      rv = exec_in_git_dir do 
+        `#{cmd}`
+        raise CommandError, rv if $? != 0
+      end
+
+      ENV['GIT_AUTHOR_NAME'] = old_aname
+      ENV['GIT_AUTHOR_EMAIL'] = old_aemail
+      ENV['GIT_COMMITTER_NAME'] = old_cname
+      ENV['GIT_COMMITTER_EMAIL'] = old_cemail
+      ENV['GIT_PAGER'] = old_pager
+
+      rv
+    end
+
+# ----------------------------------------------------------------------
+    alias :add_files :add
+
+=begin rdoc
+Add a DB entry at the filesystem path 'path' with contents 'data'. If
+'on_fs' is true, the file is created in the filesystem as well.
+This uses the staging index.
+=end
+    def add(path, data='', on_fs=false)
+      self.stage { |idx| idx.add(path, data, on_fs) }
+    end
+
+=begin rdoc
+Remove an object from the database. This can be a path to a Tree or a Blob.
+=end
+    def delete(path)
+      self.stage { |idx| idx.delete(path) }
+    end
+
+=begin rdoc
+Fetch the contents of a DB or FS object from the object database. This uses
+the staging index.
+=end
+    def object_data(path)
+      blob = path_to_object(path)
+      (blob && blob.kind_of?(Grit::Blob)) ? blob.data : nil
+    end
+
+# ----------------------------------------------------------------------
+=begin rdoc
+The Tree object for the given treeish reference 
+  +treeish+ is the reference (default 'master')
+  +paths+ is an optional Array of directory paths to restrict the tree (default [])
+
+Uses staging index if present and provides wrapper for nil treeish.
+
+ Examples 
+  repo.tree('master', ['lib/'])
+
+ Returns Grit::Tree (baked)
+=end
+    def tree(treeish=nil, paths = [])
+      begin 
+        if staging? && (not treeish)
+          @staging_index.sync
+          super(@staging_index.current_tree.id, paths)
+        else
+          treeish = 'master' if not treeish
+          super
+        end
+      rescue Grit::GitRuby::Repository::NoSuchPath
+        
+      end
+    end
+
+
+=begin rdoc
+Return the SHA1 of 'path' in repo. 
+Uses staging index if present.
+=end
+    def path_to_sha(path, head=@current_branch)
+      # Return the root of the repo if no path is specified
+      return root_sha(head) if (not path) || (path.empty?)
+
+      if staging?
+        @staging_index.sync
+        head = @staging_index.current_tree.id
+      end
+
+      dir = tree(head, [path])
+      (dir && dir.contents.length > 0) ? dir.contents.first.id : nil
+    end
+
+=begin rdoc
+Return the SHA of the root Tree in the repository.
+
+Uses the staging index if it is active.
+=end
+    def root_sha(head=@current_branch)
+      if staging?
+        @staging_index.sync
+        return @staging_index.sha
+      end
+
+      (self.commits.count > 0) ? self.commits.first.tree.id : nil
+    end
+
+=begin rdoc
+Return a Hash of the contents of 'tree'. The key is the filename, the 
+value is the Grit object (a Tree or a Blob).
+=end
+    def tree_contents(tree)
+      return {} if not tree
+      tree.contents.inject({}) { |h,item| h[item.name] = item; h }
+    end
+
+=begin rdoc
+Return a Hash of the contents of 'path'. This is just a wrapper for 
+tree_contents.
+=end
+    def list(path=nil)
+      sha = path_to_sha(path)
+      # ensure correct operation even if path doesn't exist in repo
+      t = sha ? tree(sha) : tree('master', (path ? [path] : []))
+      t ? tree_contents( t ) : {}
+    end
+
+=begin rdoc
+Return Hash of all Blob child objects at 'path'.
+=end
+    def list_blobs(path='')
+      list(path).delete_if { |k,v| not v.kind_of?(Grit::Blob) }
+    end
+
+=begin rdoc
+Return Hash of all Tree child objects at 'path'.
+=end
+    def list_trees(path='')
+      list(path).delete_if { |k,v| not v.kind_of?(Grit::Tree) }
+    end
+
+=begin rdoc
+Returns the raw (git cat-file) representation of a tree.
+=end
+    def raw_tree(path, recursive=false)
+      # Note: to construct recursive tree: 
+      #   Tree.allocate.construct_initialize(repo, treeish, output)
+      #   from repo.git.ls_tree or raw_tree
+      sha = path_to_sha(path)
+      sha ? git.ruby_git.get_raw_tree( sha, recursive ) : ''
+    end
+
+=begin rdoc
+Fetch an object from the repo based on its path.
+
+If a staging index exists, its tree will be used; otherwise, the tree
+'master' will be used.
+
+The object returned will be a Grit::Blob, a Grit::Tree, or nil.
+=end
+    def path_to_object(path)
+      treeish = (@staging_index ? staging.sha : 'master')
+      tree = self.tree(treeish, [path])
+      return tree.blobs.first if tree && (not tree.blobs.empty?)
+      return tree.trees.first if tree && (not tree.trees.empty?)
+      nil
+    end
+
+  end
+
+end