ginatra 2.0.2 → 2.1.0

data/.gitignore

@@ -11,3 +11,6 @@ _site/
 _layouts/
 **/*.swp
 *.swp
+.yardoc
+doc/*
+pkg/*

data/README.md

@@ -6,14 +6,18 @@ repositories out of a set of  specified directories using an array of glob-based
 paths. I have plans to make it  function just as gitweb does, including leeching
 config files and suchlike.
 
-Updating to Multiple directory repositories:
-============================================
+Updating to the Most Recent Release (Gem):
+------------------------------------------
 
-- Remove any bare cloned repositories from `./repos/`
-- Execute the following: `rake setup:repo` which creates a non-bare test repo in
-  `./repos/`
+- ` $ gem install ginatra`
+- (re)Move `~/.ginatra`
+- Run the following to open an irb with Ginatra loaded: ` $ irb -r 'rubygems' -r 'rubygems'`
+- In this irb session, run the following then close it: `>> Ginatra::Config.setup!`
 
-Simple eh?
+**BEWARE**: The last method that you just called will dump a config to `~/.ginatra/config.yml`.
+This ignores anything already there, so be careful. You have been warned.
+
+You can now copy the contents your old `~/.ginatra/` file into `~/.ginatra/config.yml`.
 
 Installation
 ------------
@@ -23,65 +27,68 @@ You should be using Git 1.6.3 or later just to be sure that it all works:
     $ git --version
     git version 1.6.3
 
-You'll need a few gems just to serve git repositories, for page caching, syntax highlighting & a sinatra daemon runner:
+Next, just do the following (your setup may require sudo):
+
+    $ gem install ginatra
 
-    $ (sudo) gem install grit kematzy-sinatra-cache coderay vegas
+This pulls down all the required dependencies too.
 
-To run the test suite, you also need:
+If you want to play around with the code, you can clone the repository. This also allows you
+to use a special rackup file to mount it where you wish. I am yet to sort out some of the
+details of running Ginatra from a gem with a rackup.ru file.
 
-    $ (sudo) gem install rspec webrat rack-test cucumber
+Usage
+-----
 
-To do both these steps more quickly, run the following rake tasks:
+If you're just using it in development, use the following to start, check and stop Ginatra
+respectively:
 
-    $ rake setup:gems
-    $ rake setup:test
-    
-Then clone this repository:
+    $ ginatra server start
+    $ ginatra server status
+    $ ginatra server stop
 
-    $ git clone git://github.com/lenary/ginatra.git
-    
-You'll  also need  to  (`--bare`) clone  `atmos/hancock-client`  into the  repos
-directory and call it test: (don't ask, it was just a repo i chose at random)
+Ginatra  also runs  on thin, with the approach outlined above.
 
-    $ cd repos && git clone --bare git://github.com/atmos/hancock-client.git test.git
+**BEWARE:** There are issues running Ginatra on Passenger. We discourage Ginatra's use
+on Passenger until we can make it stable.
 
-This can be done much quicker by doing the following rake task
+Ginatra can also start a git-daemon serving all the repositories that ginatra serves:
 
-    $ rake setup:repo
-    
-Usage
------
-        
-If you're just using it in development, use the following to run Ginatra:
+    $ ginatra daemon start
+    $ ginatra daemon status
+    $ ginatra daemon stop
 
-    $ ruby ginatra.rb
-    
-Ginatra  also runs  on thin.  **BEWARE:** There  are issues  running Ginatra  on
-Passenger. We discourage Ginatra's use on Passenger until we can make it stable.
+This runs on the default git daemon port.
 
-I have made a rake task so that  you can easily add repositories to Ginatra. Use
-the following to add repositories to Ginatra, without fear of getting it wrong:
+You can add a glob specified list of git repositories for ginatra to serve using the
+following commands:
 
-    $ rake add repo='git://github.com/lenary/ginatra.git'
-    $ rake add repo='git://github.com/mojombo/grit.git' name='fun'
+    $ ginatra directory add '~/Git/ginatra/*'
+    $ ginatra directory list
+    $ ginatra directory remove '~/Git/ginatra/*'
 
-Authors & Thanks
-----------------
+These should be fairly self explanatory. Help is shown with either the --help option
+or by not specifying a sub-command like start, status, stop, add, list or remove.
+
+
+Attribution
+-----------
 
 **Authors:**
 
 - Samuel Elliott (lenary)
 - Ryan Bigg (radar)
 
+**Patches**
+
+- James Tucker (raggi)
+- Elia Schito (elia)
+- Scott Wisely (Syd)
+- Jonathan Stott (namelessjon)
+
 **Thanks**
 
-- tekkub - For help with Grit
-- schacon - For help with Grit
-- cirwin - For moral support and design help
-- irc://irc.freenode.net/git - for any other problems I had
-- Picol Project (http://picol.org) - for the icons
-- sr - For help with a large sinatra error
-- raggi - For a refactor and several feature suggestions
+Too many to name. Thanks be to you all.
 
 Screenshots
 -----------

data/VERSION

@@ -1 +1 @@
-2.0.2
+2.1.0

data/ginatra.gemspec

@@ -1,15 +1,15 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{ginatra}
-  s.version = "2.0.2"
+  s.version = "2.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Sam Elliott", "Ryan Bigg"]
-  s.date = %q{2009-08-26}
+  s.date = %q{2009-12-28}
   s.description = %q{Host your own git repository browser through the power of Sinatra and Grit}
   s.email = %q{sam@lenary.co.uk}
   s.executables = ["ginatra", "ginatra-daemon", "ginatra-directory", "ginatra-server"]
@@ -63,19 +63,6 @@ Gem::Specification.new do |s|
      "spec/repo_list_spec.rb",
      "spec/repo_spec.rb",
      "spec/spec_helper.rb",
-     "vendor/vegas/History.txt",
-     "vendor/vegas/LICENSE",
-     "vendor/vegas/Manifest.txt",
-     "vendor/vegas/README.rdoc",
-     "vendor/vegas/Rakefile",
-     "vendor/vegas/lib/vegas.rb",
-     "vendor/vegas/lib/vegas/runner.rb",
-     "vendor/vegas/test/test_app/bin/test_app",
-     "vendor/vegas/test/test_app/test_app.rb",
-     "vendor/vegas/test/test_apps.rb",
-     "vendor/vegas/test/test_helper.rb",
-     "vendor/vegas/test/test_vegas_runner.rb",
-     "vendor/vegas/vegas.gemspec",
      "views/_actor_box.erb",
      "views/_commit_info_box.erb",
      "views/_header.erb",
@@ -91,7 +78,7 @@ Gem::Specification.new do |s|
   s.homepage = %q{http://lenary.github.com/ginatra}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.4}
+  s.rubygems_version = %q{1.3.5}
   s.summary = %q{A Gitweb Clone in Sinatra and Grit}
   s.test_files = [
     "spec/repo_list_spec.rb",
@@ -118,3 +105,4 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<coderay>, [">= 0.8.0"])
   end
 end
+

data/lib/ginatra/config.rb

@@ -1,8 +1,16 @@
 module Ginatra
+
+  # A Wrapper for the ginatra configuration variables,
+  # including methods to load, dump and lookup keys
+  # using just the class.
   class Config
 
     current_path = File.expand_path("#{File.dirname(__FILE__)}")
+
+    # A default path for our configuration variables!
     CONFIG_PATH = File.expand_path("~/.ginatra/config.yml")
+
+    # A default config that we fall back to if no file is found.
     DEFAULT_CONFIG = {
       :git_dirs => [File.expand_path("#{current_path}/../../repos/*")],
       :ignored_files => ['README.md'],
@@ -10,12 +18,26 @@ module Ginatra
       :port => 9797
     }
 
-    def self.setup! # Very Destructive Method. Use with care!
+    # Dumps the Default configuration to +CONFIG_PATH+,
+    # WITHOUT regard for what's already there.
+    #
+    # Very Destructive Method. Use with care!
+    def self.setup!
       File.open(CONFIG_PATH, 'w') do |f|
         YAML.dump(DEFAULT_CONFIG, f)
       end
     end
 
+    unless File.exist?(CONFIG_PATH)
+      require 'fileutils'
+      FileUtils.mkdir_p(File.dirname(CONFIG_PATH))
+      setup!
+    end
+    
+    # Loads the configuration and merges it with
+    # the default configuration.
+    #
+    # @return [Hash] config a hash of the configuration options
     def self.load!
       @config = {}
       begin
@@ -25,12 +47,26 @@ module Ginatra
       @config = DEFAULT_CONFIG.merge(@config)
     end
 
+    # Dumps the _current_ configuration to +CONFIG_PATH+
+    # again WITHOUT regard for what's already there.
+    #
+    # Very Destructive Method. Use with care!
     def self.dump!
       File.open(CONFIG_PATH, 'w') do |f|
         YAML.dump(@config, f)
       end
     end
 
+    # Allows us to do many things.
+    #
+    # The first is respond to any hash methods
+    # and execute them on the +@config+ hash.
+    #
+    # The second is to do something like
+    # +Ginatra::Config.port+ instead of something
+    # like +Ginatra::Config[:port]+
+    #
+    # @return depends on what's in the config hash.
     def self.method_missing(sym, *args, &block)
       if @config.respond_to?(sym)
         @config.send(sym, *args, &block)
@@ -41,6 +77,10 @@ module Ginatra
       end
     end
 
+    # This is so that we can be clever by using
+    # +#try()+ and so that this mirrors +method_missing+.
+    #
+    # @see Ginatra::Config.method_missing
     def self.respond_to?(name)
       if @config.respond_to?(name)
         true

data/lib/ginatra/helpers.rb

@@ -1,21 +1,48 @@
 require "digest/md5"
 
 module Ginatra
-  # Actually useful stuff
+  # Helpers used in the views usually,
+  # but not exclusively.
   module Helpers
 
+    # takes an email and returns a url to a secure gravatar
+    #
+    # @param [String] email the email address
+    # @return [String] the url to the gravatar
     def gravatar_url(email)
       "https://secure.gravatar.com/avatar/#{Digest::MD5.hexdigest(email)}?s=40"
     end
 
+    # reformats the date into a user friendly date with html entities
+    #
+    # @param [#strftime] date object to format nicely
+    # @return [String] html string formatted using
+    #   +"%b %d, %Y – %H:%M"+
     def nicetime(date)
       date.strftime("%b %d, %Y – %H:%M")
     end
 
+    # displays the actor box easily.
+    #
+    # Internally, it calls the +#partial+ method
+    # @see Sinatra::Partials#partial
+    #
+    # @param [Grit::Actor] actor the Grit Actor Object
+    # @param [#to_s] role the role that the object has.
+    # @param [#strftime] date the date that the actor acted on.
+    #
+    # @return [String] a string that contains the box for the actor.
     def actor_box(actor, role, date)
       partial(:actor_box, :locals => { :actor => actor, :role => role, :date => date })
     end
 
+    # works out what actor boxes need to be displayed.
+    #
+    # Will always display the committer box, and will only display
+    # the author box if it's different to the committer
+    #
+    # @param [Grit::Commit] commit the commit in question
+    # @return [String] a string representing the HTML actor boxes
     def actor_boxes(commit)
       o = actor_box(commit.committer, :committer, commit.committed_date)
       if commit.author.name != commit.committer.name
@@ -23,26 +50,66 @@ module Ginatra
       end
     end
 
+    # spits out a link to a certain reference.
+    #
+    # @param [Grit::Ref] ref grit ref object
+    # @param [String] repo_param the url-sanitised-name for the repo
+    #   (for the link path)
+    #
+    # @return [String] HTML link to the given ref with class attached.
     def commit_ref(ref, repo_param)
       ref_class = ref.class.to_s.split("::")[1].to_s
       "<a class=\"ref #{ref_class}\" href=\"/#{repo_param}/#{ref.name}\">#{ref.name}</a>"
     end
 
+    # calls +Ginatra::Helpers#commit_ref+ for each ref in the commit
+    #
+    # @see Ginatra::Helpers#commit_ref
+    #
+    # @param [Grit::Commit] commit grit commit object
+    # @param [String] repo_param the url-sanitised-name for the repo
+    #   (for the link path)
+    #
+    # @return [String] HTML containing all the ref links
     def commit_refs(commit, repo_param)
       commit.refs.map{ |r| commit_ref(r, repo_param) }.join("\n")
     end
 
+    # returns a string including the link to download a certain 
+    # tree of the repo
+    #
+    # @param [Grit::Tree] tree the tree you want an archive link for
+    # @param [String] repo_param the url-sanitised-name of the repo
+    #   (for the link path)
+    #
+    # @return [String] the HTML link to the archive.
     def archive_link(tree, repo_param)
       "<a class=\"download\" href=\"/#{repo_param}/archive/#{tree.id}.tar.gz\" title=\"Download a tar.gz snapshot of this Tree\">Download Archive</a>"
     end
 
+    # returns a string including the link to download a patch for a certain
+    # commit to the repo
+    #
+    # @param [Grit::Commit] commit the commit you want a patch for
+    # @param [String] repo_param the url-sanitised name for the repo
+    #   (for the link path)
+    #
+    # @return [String] the HTML link to the patch
     def patch_link(commit, repo_param)
       "<a class=\"download\" href=\"/#{repo_param}/commit/#{commit.id}.patch\" title=\"Download a patch file of this Commit\">Download Patch</a>"
     end
 
-    # The only reason this doesn't work 100% of the time is because grit doesn't :/
-    # if i find a fix, it'll go upstream :D
+    # returns a HTML (+<ul>+) list of the files altered in a given commit.
+    #
+    # It includes classes for added/altered/deleted and also anchor links 
+    # to the diffs for further down the page.
+    #
+    # @param [Grit::Commit] commit the commit you want the list of files for
+    #
+    # @return [String] a +<ul>+ with lots of +<li>+ children.
     def file_listing(commit)
+      # The only reason this doesn't work 100% of the time is because grit doesn't :/
+      # if i find a fix, it'll go upstream :D
       count = 0
       out = commit.diffs.map do |diff|
         count = count + 1
@@ -55,14 +122,25 @@ module Ginatra
       end
       "<ul id='files'>#{out.join}</ul>"
     end
-    
+
+    # returns some html containing the Coderay'd diff files.
+    #
+    # @param [String] diff the diff you want highlighted
+    # @return [String] the highlighted diff
     def diff(diff)
       diff = CodeRay.scan(diff, :diff).div(:line_numbers => :table, :css => :class)
     end
 
+    # Formats the text to remove multiple spaces and newlines, and then inserts
+    # HTML linebreaks.
+    #
     # Stolen from rails: ActionView::Helpers::TextHelper#simple_format
-    #   and simplified to just use <p> tags without any options
-    # modified since
+    # and simplified to just use <p> tags without any options, then modified 
+    # more later.
+    #
+    # @param [String] text the text you want formatted
+    # 
+    # @return [String] the formatted text
     def simple_format(text)
       text.gsub!(/ +/, " ")
       text.gsub!(/\r\n?/, "\n")
@@ -70,9 +148,27 @@ module Ginatra
       text
     end
 
+    # Cleans up the particularly volatile parts of HTML 
+    # and replaces them with their entities. Replaces the following 
+    # characters:
+    #  - &
+    #  - >
+    #  - <
+    #  - '
+    #
+    # If you are using this with #simple_format, do not forget to call
+    # this one first, then put in unsanitised linebreaks. The other way around
+    # is full of fail.
+    #
     # stolen from rails: ERB::Util
-    def html_escape(s)
-      s.to_s.gsub(/[&"<>]/) do |special|
+    #
+    # @see Ginatra::Helpers#simple_format
+    #
+    # @param [#to_s] clean_me the object to clean.
+    #
+    # @return [String] the cleaned html text.
+    def html_escape(clean_me)
+      clean_me.to_s.gsub(/[&"<>]/) do |special|
         { '&' => '&amp;',
           '>' => '&gt;',
           '<' => '&lt;',
@@ -81,7 +177,15 @@ module Ginatra
     end
     alias :h :html_escape
 
+    # Truncates a given text to a certain number of letters, including a special ending if needed.
+    #
     # Stolen and bastardised from rails
+    # 
+    # @param [String] text the text to truncate
+    # @option options [Integer] :length   (30) the length you want the output string
+    # @option options [String]  :omission ("...") the string to show an omission.
+    #
+    # @return [String] the truncated text.
     def truncate(text, options={})
         options[:length] ||= 30
         options[:omission] ||= "..."
@@ -94,19 +198,36 @@ module Ginatra
       end
     end
 
+    # Returns the rfc representation of a date, for use in the atom feeds.
+    #
     # stolen from Marley
+    #
+    # @param [DateTime] datetime the date to format
+    # @return [String] the formatted datetime
     def rfc_date(datetime)
       datetime.strftime("%Y-%m-%dT%H:%M:%SZ") # 2003-12-13T18:30:02Z
     end
 
+    # Returns the Hostname of the given install. 
+    #
+    # @todo Where is this used?
+    #
     # stolen from Marley
+    # 
+    # @return [String] the hostname of the server. Respects HTTP-X-Forwarded-For
     def hostname
       (request.env['HTTP_X_FORWARDED_SERVER'] =~ /[a-z]*/) ? request.env['HTTP_X_FORWARDED_SERVER'] : request.env['HTTP_HOST']
     end
 
+    # Spits out a HTML link to the atom feed for a given ref of a given repo
+    #
+    # @param [Sting] repo_param the url-sanitised-name of a given repo
+    # @param [String] ref the ref to link to.
+    #
+    # @return [String] the HTML containing the link to the feed.
     def atom_feed_link(repo_param, ref=nil)
       "<a href=\"/#{repo_param}#{"/#{ref}" if !ref.nil?}.atom\" title=\"Atom Feed\" class=\"atom\">Feed</a>"
     end
 
   end
-end
+end

data/lib/ginatra/repo.rb

@@ -1,16 +1,24 @@
-# to make refs work!
 module Grit
   class Commit
+    # this lets us add a link between commits and refs directly
     attr_accessor :refs
   end
 end
 
 module Ginatra
-  # Convenience class for me!
+  # A thin wrapper to the Grit::repo class so that we can add a name and a url-sanitised-name
+  # to a repo, and also intercept and add refs to the commit objects.
   class Repo
 
     attr_reader :name, :param, :description
 
+    # Create a new repository, and sort out clever stuff including assigning
+    # the param, the name and the description.
+    #
+    # @todo cleanup!
+    #
+    # @param [String] path a path to the repository you want created
+    # @return [Ginatra::Repo] a repository instance
     def initialize(path)
       @repo = Grit::Repo.new(path)
       @param = File.split(path).last
@@ -20,6 +28,15 @@ module Ginatra
       @repo
     end
 
+    # Return a commit corresponding to the commit to the repo,
+    # but with the refs already attached.
+    # 
+    # @see Ginatra::Repo#add_refs
+    #
+    # @raise [Ginatra::InvalidCommit] if the commit doesn't exist.
+    #
+    # @param [String] id the commit id
+    # @return [Grit::Commit] the commit object.
     def commit(id)
       @commit = @repo.commit(id)
       raise(Ginatra::InvalidCommit.new(id)) if @commit.nil?
@@ -27,6 +44,15 @@ module Ginatra
       @commit
     end
 
+    # Return a list of commits to a certain branch, including pagination options and all the refs.
+    #
+    # @param [String] start the branch to look for commits in
+    # @param [Integer] max_count the maximum count of commits
+    # @param [Integer] skip the number of commits in the branch to skip before taking the count.
+    #
+    # @raise [Ginatra::Error] if max_count is less than 0. silly billy!
+    #
+    # @return [Array<Grit::Commit>] the array of commits.
     def commits(start = 'master', max_count = 10, skip = 0)
       raise(Ginatra::Error.new("max_count cannot be less than 0")) if max_count < 0
       @repo.commits(start, max_count, skip).each do |commit|
@@ -34,7 +60,12 @@ module Ginatra
       end
     end
     
-    # TODO: Perhaps move into commit class.
+    # Adds the refs corresponding to Grit::Commit objects to the respective Commit objects.
+    #
+    # @todo Perhaps move into commit class.
+    #
+    # @param [Grit::Commit] commit the commit you want refs added to
+    # @return [Array] the array of refs added to the commit. they are also on the commit object.
     def add_refs(commit)
       commit.refs = []
       refs = @repo.refs.select { |ref| ref.commit.id == commit.id }
@@ -42,9 +73,14 @@ module Ginatra
       commit.refs.flatten!
     end
 
+    # Catch all
+    #
+    # Warning! contains: Magic
+    #
+    # @todo update respond_to? method
     def method_missing(sym, *args, &block)
       @repo.send(sym, *args, &block)
     end
 
   end
-end
+end

data/lib/ginatra/repo_list.rb

@@ -1,21 +1,33 @@
 require 'singleton'
 
 module Ginatra
-  # Convenience class for me!
+  # A singleton class that lets us make and use a constantly updating 
+  # list of repositories.
   class RepoList
     include Singleton
     attr_accessor :list
     
+    # This creates the list, then does the first refresh to 
+    # populate it.
+    #
+    # It returns what refresh returns.
     def initialize
       self.list = []
       self.refresh
     end
     
+    # The preferred way to access the list publicly. 
+    # 
+    # @return [Array<Ginatra::Repo>] a list of ginatra repos.
     def self.list
       self.instance.refresh
       self.instance.list
     end
 
+    # searches through the configured directory globs to find all the repositories
+    # and adds them if they're not already there.
+    #
+    # @todo Docs: what the hell does this return?
     def refresh
       Ginatra::Config.git_dirs.map! do |git_dir|
         files = Dir.glob(git_dir)
@@ -23,16 +35,36 @@ module Ginatra
       end
     end
 
+    # adds a Repo corresponding to the path it found a git repo at in the configured
+    # globs. Checks to see that it's not there first
+    #
+    # @param [String] path the path of the git repo
+    # @param [String] param the param of the repo if it differs, 
+    #   for looking to see if it's already on the list
+    #
+    # @todo Docs: what does this return?
     def add(path, param = File.split(path).last)
       unless self.has_repo?(param)
         list << Repo.new(path)
       end
     end
 
+    # checks to see if the list contains a repo with a param 
+    # matching the one passed in.
+    #
+    # @param [String] local_param param to check.
+    #
+    # @return [true, false]
     def has_repo?(local_param)
       !list.find { |r| r.param == local_param }.nil?
     end
 
+    # quick way to look up if there is a repo with a given param in the list. 
+    # If not, it refreshes the list and tries again.
+    #
+    # @param [String] local_param the param to lookup
+    #
+    # @return [Ginatra::Repo] the repository corresponding to that param.
     def find(local_param)
       if repo = list.find { |r| r.param == local_param }
         repo
@@ -42,10 +74,19 @@ module Ginatra
       end
     end
 
+    # This just brings up the find method to the class scope.
+    #
+    # @see Ginatra::RepoList#find
     def self.find(local_param)
       self.instance.find(local_param)
     end
 
+    # allows missing methods to cascade to the instance,
+    #
+    # @todo do we need this?
+    # @todo update the respond_to? method if we do.
+    #
+    # Caution! contains: Magic
     def self.method_missing(sym, *args, &block)
       instance.send(sym, *args, &block)
     end