@@ -1,34 +1,3 @@ -= Gash, Git meets Hash -Modify a Git-repo without touching the working-directory - - gash = Gash.new("master", ".git") - gash["README"] # => This file - gash["lib/gash.rb"] # => That file - gash["lib"]["gash.rb"] # => Another way - gash / "lib" / "gash.rb" # => Yet another way - - gash["test"] = "Just a little demo" - gash.changed? # => true - gash["test"].changed? # => true - gash["lib"].changed? # => false - gash.commit("Playing with Gash") - gash.changed? # => false - - gash["lib"].sha1 # => SHA1 to tree - gash["lib"].mode # => "040000" - gash["README"].sha1 # => SHA1 to blob - gash["README"].mode # => "100644" - - git = Gash.new("master", "../git/.git") # Really big repo - # Lazy loading, so the above command is really quick - r = git["README", true] # => Don't load the blob yet - r.sha1 # => not yet... - r.mode # => not yet... - r.upcase # => there it will! - # Load explict with r.load! += Gash, Git + Hash -= Warning! -This is a really alpha, so don't blame me for destroying your repo. - -= Thanks! -This would be impossible without siebertm's git-shelve... +Please see http://dojo.rubyforge.org/gash or the documentation in lib/gash.rb! README @@ -1,25 +1,82 @@ require 'delegate' +# == What is Gash? +# +# * Gash lets you access a Git-repo as a Hash. +# * Gash only cares about the data, not the commits. +# * Gash only cares about the _latest_ data. +# * Gash can commit. +# * Gash doesn't touch your working directory +# * Gash will automatically create branches if they don't exists. +# * Gash only loads what it needs, so it handles large repos well. +# +# == How do you use it? +# +# gash = Gash.new +# gash["README"] = "new content" +# gash.commit("Some changes...") +# +# It's also important to remember that a Gash is simply a Tree, so you can +# also call those methods. +# +# See also: #new, #commit, Tree +# +# == Limitation +# +# The only Hash-like features which currently works is #[] and #[]=, +# so don't try #merge or something like that. class Gash < SimpleDelegator + module Errors + # This error is raised when the Git-command fails. + class Git < StandardError; end + end + + # Some common methods used by both Tree and Blob. module Helpers attr_accessor :sha1, :mode, :parent + # Sets the accessors using a Hash: + # + # tree = Gash::Tree.new(:sha1 => "some thing", :mode => "some thing", + # :parent => "some parent") + # tree.sha1 == "some thing" + # tree.mode == "some thing" + # tree.parent == "some parent" def initialize(opts = {}) opts.each do |key, value| send("#{key}=", value) end end - def blob?; self.class == Gash::Blob; end - def tree?; self.class == Gash::Tree; end - def changed?; !@sha1; end + # Checks if this is a Blob. + def blob?; self.class == Gash::Blob end + # Checks if this is a Tree. + def tree?; self.class == Gash::Tree end + # Checks if this object has been changed (since last commit). + def changed?; !@sha1 end + # Mark this, and all parents as changed. def changed!; @sha1 = nil;parent.changed! end - def gash; parent.gash; end + # Returns the Gash-object (top-parent). + def gash; parent.gash end end + # A Tree is a Hash which can store other instances of Tree and Blob. + # + # See also: Helpers, Blob class Tree < Hash include Helpers + # Retrieves the _value_ stored as +key+: + # + # tree["FILE"] == the file + # tree["DIR/FILE"] == tree["DIR"]["FILE"] = another file + # + # It will automatically call the +load!+-method in order to load + # it from the repo. Set +lazy+ to +true+ if this is not what you want: + # + # blob = tree["FILE", true] == #<Blob:1234...> + # # do some other stuff... + # blob.laod! # Load it now! def [](key, lazy = nil) ret = if key.include?("/") key, rest = key.split("/", 2) @@ -34,12 +91,30 @@ class Gash < SimpleDelegator end alias / [] - def []=(*a) - case a.length - when 3 - key, keep_sha1, value = [*a] - when 2 - key, value = [*a] + # Stores the given _value_: + # + # tree["FILE"] = "Content" + # + # Unless it's already a Tree or a Blob, it will be converted to a Blob, + # and the parent will _always_ be set to +self+. + # + # tree["FILE"] = "Content" + # # is the same as: + # tree["FILE"] = Gash::Blob.new(:content => "Content", :parent => tree) + # + # It will also mark the object as changed (using <code>Helpers#changed!</code>). + # Set +not_changed+ to +true+ if this is not what you want. + # + # (If you give it three arguments, then the second one will act as + # +not_changed+, not the third): + # + # tree["FILE", true] = "Test" + # tree["FILE"].changed? # => false + def []=(key, value, not_changed = nil) + key, value, not_changed = if not_changed.nil? + [key, value] + else + [key, not_changed, value] end if key.include?("/") @@ -48,7 +123,7 @@ class Gash < SimpleDelegator keys.inject(self) do |memo, i| memo[i] = Tree.new(:parent => self) unless memo.include?(i) memo[i, true] - end[name, keep_sha1] = value + end[name, not_changed] = value else value = case value when Tree, Blob @@ -60,45 +135,73 @@ class Gash < SimpleDelegator super(key, value) end ensure - self.changed! unless keep_sha1 + self.changed! unless not_changed end end + # A Blob represent a string: + # + # blob = Gash::Blob.new(:content => "Some content") + # blob # => "Some content" + # + # == Using SHA1 + # + # However, if you provide a SHA1 (and have a parent which is connected to + # a Gash-object) it will then load the content from the repo when needed: + # + # blob = Gash::Blob.new(:sha1 => "1234" * 10, :parent => gash_OR_tree_connected_to_gash) + # blob # => #<Blob:1234123412341234123412341234123412341234> + # blob.upcase # It's loaded when needed + # #blob.load! # or forced with #load! + # blob # => "Content of the blob" + # + # Tree#[]= automatically sets the parent to itself, so you don't need to + # provide it then: + # + # tree["FILE"] = Gash::Blob.new(:sha1 => a_sha1) + # + # See also: Helpers, Tree class Blob < Delegator include Helpers attr_accessor :content - def inspect - @content ? @content.inspect : (@sha1 ? "#<Blob:#{@sha1}>" : to_s.inspect) - end - + # Loads the file from Git, unless it's already been loaded. def load! @content ||= gash.send(:cat_file, @sha1) end - def __getobj__ + def inspect #:nodoc: + @content ? @content.inspect : (@sha1 ? "#<Blob:#{@sha1}>" : to_s.inspect) + end + + def __getobj__ #:nodoc: @content ||= @sha1 ? load! : '' end - alias to_s __getobj__ + alias_method :to_s, :__getobj__ end attr_accessor :branch, :repository - def initialize(branch, repo = ".") + # Opens the +repo+ with the specified +branch+. + # + # Please note: The +repo+ must link to the actual repo, + # not the working directory! + def initialize(branch = "master", repo = ".git") @branch = branch @repository = File.expand_path(repo) __setobj__(Tree.new(:parent => self)) update! end - def gash + def gash #:nodoc: self end - def changed! + def changed! #:nodoc: @sha1 = nil end + # Fetch the latest data from Git; you can use this as a +clear+-method. def update! clear self.sha1 = git_tree_sha1 @@ -127,6 +230,9 @@ class Gash < SimpleDelegator self end + # Commit the current changes and returns the commit-hash. + # + # Returns +nil+ if nothing has changed. def commit(msg) return unless changed? commit = commit_tree(to_tree!, msg) @@ -134,14 +240,15 @@ class Gash < SimpleDelegator commit end + # Checks if the current branch exists def branch_exists? git('rev-parse', @branch, '2>&1') true - rescue GitError + rescue Errors::Git false end - def inspect + def inspect #:nodoc: __getobj__.inspect end @@ -187,13 +294,13 @@ class Gash < SimpleDelegator git('ls-tree', '-r', '-t', @branch, '2>&1') do |f| f.each_line(&blk) end - rescue GitError + rescue Errors::Git "" end def git_tree_sha1(from = @branch) git('rev-parse', @branch + '^{tree}', '2>&1') - rescue GitError + rescue Errors::Git end def method_missing(meth, *args, &blk) @@ -215,7 +322,7 @@ class Gash < SimpleDelegator # :strip<Boolean>:: true to strip the output String#strip, false not to to it # # ==== Raises - # GitError:: if git returns non-null, an Exception is raised + # Errors::Git:: if git returns non-null, an Exception is raised # # ==== Returns # String:: if you didn't supply a block, the things git said on STDOUT, otherwise noting @@ -223,7 +330,7 @@ class Gash < SimpleDelegator result, status = run_git(cmd, *rest, &block) if status != 0 - raise GitError.new("Error: #{cmd} returned #{status}. Result: #{result}") + raise Errors::Git.new("Error: #{cmd} returned #{status}. Result: #{result}") end result end @@ -253,7 +360,7 @@ class Gash < SimpleDelegator # :strip<Boolean>:: true to strip the output String#strip, false not to to it # # ==== Raises - # GitError:: if git returns non-null, an Exception is raised + # Errors::Git:: if git returns non-null, an Exception is raised # # ==== Returns # Array[String, Integer]:: the first item is the STDOUT of git, the second is the return-status @@ -291,7 +398,4 @@ class Gash < SimpleDelegator [result, status] end - - class GitError < StandardError - end end \ No newline at end of file lib/gash.rb 97375947ed5295aa38dedabbd4dcab30c0b82da0 Magnus Holm judofyr@gmail.com http://github.com/judofyr/gash/commit/cab460d38b354282348e9923dc33ed5c1c1228cf cab460d38b354282348e9923dc33ed5c1c1228cf

2008-09-04T12:12:16-07:00

Adding documentation + some refactoring 341edd3002f00d9bd611e08e07984ac7999baf47 Magnus Holm judofyr@gmail.com