git-runner 0.0.6 → 0.1.0

data/README.md

@@ -1,39 +1,124 @@
 # Git Runner
 
-git-runner is a ruby framework to implement and run tasks after code has been pushed to a Git repository. It works by invoking `git-runner` through `hooks/post-update` in your remote Git repository.
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/JamesBrooks/git-runner)
 
-[Demonstration Video, Using git-runner to perform automatic deploys](http://ascii.io/a/1349)
 
-Configuration for git-runner is read from a pre-determined file within the repository (at this time, that file is config/deploy.rb but this will soon be configurable). Any instructions detected are then processed and ran.
+Git Runner is a ruby framework to create and run tasks after commits are pushed to a git repository.
+
+It works by having the git server-side post-update hook (`hooks/post-update`) invoke `git-runner`. Git Runner inspects all of the pushed branches (`refs/heads/*`) and looks for any Git Runner tasks (called instructions) to run. Such an instruction is `Deploy`, which allows for the application to be deployed after a push.
+
+Git Runner instructions are distrubuted as separate gems, see **Available Instructions** below for what instructions are currently available for use.
+
+Have a look at this short [demonistration video](http://ascii.io/a/1349) for what it looks like for a user pushing to a Git Runner enabled repository (using `git-runner-deploy`).
+
+
+## Why?
+
+#### Origins
+
+Git Runner originated from a need to simply the deployment process (capistrano) within my organisation for people who don't have their environments setup with ruby and the required gems. I wanted to make the process work for even those who are using GUI git clients.
+
+
+#### Wouldn't a simple script do the job?
+
+While you certainly could create a ruby script at `hooks/post-update` and have that run after a push with good results, Git Runner provides a robust framework for authoring re-usable tasks that you can share between all of your code repositories and run only when you need to run them.
+
+You could do it all in a script of your own if you like, but Git Runner is there to help you out and make the process less error-prone and more maintainable.
+
+
+## How
+
+After pushing to a git repository various server-side hooks are ran, including a hook named `post-update`. `post-update` needs to run `git-runner` with it's arguments.
+
+Git Runner looks for pushes to any branches (`refs/heads/*`). For each branch it greps the repository for one or more Git Runner instructions within a instruction file.
+
+The instruction file and instruction markers are configurable (see **Configuration** below), by default the configuration file is `config/deploy.rb` and Git Runner instructions begin with `# GitRunner:`, e.g.
+
+```
+# GitRunner: Deploy
+... rest of the file ...
+```
+
+*Instructions can be on any line within the instruction file and multiple instructions are present (instructions are ran in order).*
+
+Any instructions that are found within the instruction file are then processed and ran if able, with any messages being displayed to the user currently pushing the repository.
+
+Any errors encountered will also be displayed with all relevent details being written to a log on the server.
+
+
+## Features
+
+* Robust framework for running tasks (instructions) after updates are made to a repository.
+* Have all of your tasks available to all of your repositories, only use the ones you need on a per repository basis.
+* Activiation through instructions contained within the repository.
+* Branch detection, behave differently for different branches if you like.
+* Simple authoring of additional instructions.
+* Error handling, notification and logging.
+
+
+## Available Instructions
+
+Name                                                       | Gem               | Description
+---------------------------------------------------------- | ----------------- | ---------------------------------------
+[Deploy](https://github.com/JamesBrooks/git-runner-deploy) | git-runner-deploy | Application deployment using capistrano
 
-Instructions are contained within `lib/git-runner/instructions`. By default the instructions contained here and only used for support purposes, real functionality is abstracted into separate gems (at this time the only real instuction is deploy).
 
 ## Installation
 
-    $ gem install git-runner
+This section needs a lot more fleshing out as installation overly trivial. The main thing to worry about is making sure that `hooks/post-update` in each of your repositories is able to run `git-runner` (and pass it's arguments on).
+
+
+#### Install the git-runner
 
-## Install any additional modules (you'll want to do this to get any real functionality)
+Install the gem and any other additional instruction gems that you need, for example if we want Git Runner with capistrano deploy support:
 
-### Deploy using Capistrano
-[https://github.com/JamesBrooks/git-runner-deploy](https://github.com/JamesBrooks/git-runner-deploy)
+```
+gem install git-runner
+gem install git-runner-deploy
+```
 
-    gem install git-runner-deploy
+#### Hook up git-runner to fire on hooks/post-update
 
+There are a few ways to accomplish this, such as directly symlinking `hooks/post-update` to the executable path for git-runner. Currently I prefer the following approach of creating a script that loads rubygems and git-runner + calls git runner. The following is the contents of my `hooks/post-update` file:
 
-## Usage
+```
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'git-runner'
+
+GitRunner::Base.new(ARGV).run
+```
 
-Symlink `hooks/post-update` to `git-runner`, or if `post-update` is already in use modify it to run `git-runner` with the arguments supplied to the hook.
 
 ## Configuration
 
-Configuration can be overwritten through a YAML file at either `/etc/git-runner.yml` or `$HOME/.git-runner.yml`. The current configuration options are:
+Configuration can be changed through a YAML file at either `/etc/git-runner.yml` or `$HOME/.git-runner.yml`. The default configuration settings are:
+
+Option             | Default Value    | Description
+------------------ | ---------------- | --------------------------------------------------------------------------
+git_executable     | /usr/bin/env git | Location of the git executable to use
+instruction_file   | config/deploy.rb | Where to look for Git Runner instructions within each repository
+instruction_prefix | # GitRunner:     | What Git Runner instructions will be prefixed with in the instruction file
+tmp_directory      | /tmp/git-runner  | Working directory for git-runner
+
+
+## TODOs
+
+* Support to monitor a command (stdout and stderr) as the command is running, not just at the end.
+* Instruction file path is globally set, make this overwritable on a per-repository basis?
+* Instruction prefix is globally set, make this overwritable on a per-repository basis?
+* Have core functionality fire useful hooks.
+* Improve the output/text library, it can work better!
+* Simplify Base#run (CodeClimate)
+
+
+## Support
+
+Check out [GitHub Issues](https://github.com/JamesBrooks/git-runner/issues) to see if anyone else has had the same problem you have, or create a new issue.
 
-  * **git_executable** (default: '/usr/bin/env git')
-  * **instruction_file** (default: 'config/deploy.rb')
-  * **instruction_prefix** (default: '# GitRunner:')
-  * **tmp_directory** (default: '/tmp/git-runner')
+Also feel free to contact me directly (james at jamesbrooks dot net) for non-support comments or support of a more sensitive nature.
 
-## TODO
 
 ## Contributing
 

data/git-runner.gemspec

@@ -16,5 +16,5 @@ Gem::Specification.new do |gem|
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.require_paths = ["lib"]
 
-  gem.add_dependency 'session'
+  gem.add_dependency 'session', '>= 3.1.0'
 end

data/lib/git-runner/base.rb

@@ -26,31 +26,13 @@ module GitRunner
 
 
       rescue GitRunner::Instruction::Failure => ex
-        Text.new_line
-        Text.out("Stopping runner, no further instructions will be performed\n")
-        Text.new_line
+        handle_instruction_failure_exception(ex)
 
       rescue GitRunner::Command::Failure => ex
-        Text.new_line
-        Text.out(Text.red("\u2716 Command failed: " + Text.red(ex.result.command)), :heading)
-
-        write_error_log do |log|
-          log << Command.history_to_s
-        end
-
-        Text.new_line
+        handle_command_failure_exception(ex)
 
       rescue Exception => ex
-        Text.new_line
-        Text.out(Text.red("\u2716 Unknown exception occured: #{ex}"), :heading)
-
-        write_error_log do |log|
-          log << Command.history_to_s
-          log << ex.message + "\n"
-          log << ex.backtrace.map { |line| "    #{line}\n" }.join
-        end
-
-        Text.new_line
+        handle_unknown_exception(ex)
 
       ensure
         Text.finish
@@ -64,6 +46,36 @@ module GitRunner
       Gem::Specification._all.map(&:name).select { |gem| gem =~ /^git-runner-/ }.each { |name| require(name) }
     end
 
+    def handle_instruction_failure_exception(ex)
+      Text.new_line
+      Text.out("Stopping runner, no further instructions will be performed\n")
+      Text.new_line
+    end
+
+    def handle_command_failure_exception(ex)
+      Text.new_line
+      Text.out(Text.red("\u2716 Command failed: " + Text.red(ex.result.command)), :heading)
+
+      write_error_log do |log|
+        log << Command.history_to_s
+      end
+
+      Text.new_line
+    end
+
+    def handle_unknown_exception(ex)
+      Text.new_line
+      Text.out(Text.red("\u2716 Unknown exception occured: #{ex}"), :heading)
+
+      write_error_log do |log|
+        log << Command.history_to_s
+        log << ex.message + "\n"
+        log << ex.backtrace.map { |line| "    #{line}\n" }.join
+      end
+
+      Text.new_line
+    end
+
     def write_error_log
       log_directory = File.join(Configuration.tmp_directory, 'logs')
       error_log     = File.join(log_directory, Time.now.strftime("%Y%m%d%H%M%S") + '-error.log')

data/lib/git-runner/branch.rb

@@ -32,10 +32,9 @@ module GitRunner
 
       # Process the output to generate instructions
       output.split("\n").map do |line|
-        instruction        = Instruction.from_raw(line)
-        instruction.branch = self
-
-        instruction
+        Instruction.from_raw(line).tap do |instruction|
+          instruction.branch = self
+        end
       end
     end
   end

data/lib/git-runner/command.rb

@@ -6,17 +6,21 @@ module GitRunner
 
 
     def execute(*commands)
-      commands.each do |command|
-        out = StringIO::new
+      # Extract options (if any)
+      opts = commands.last.is_a?(Hash) ? commands.pop : {}
 
-        session.execute command, :stdout => out, :stderr => out
+      # Set session callback procs
+      session.outproc = opts[:outproc]
+      session.errproc = opts[:errproc]
 
-        result = Result.new(command, out.string, session.exit_status)
-        history << result
+      # Cycle through and run commands
+      execute_commands(commands)
 
-        raise Failure.new(result) if result.failure?
-      end
+      # Clear session callback procs
+      session.outproc = nil
+      session.errproc = nil
 
+      # Return full output of the last ran command (should this be all commands perhaps?)
       history.last.out
     end
 
@@ -25,13 +29,27 @@ module GitRunner
     end
 
     def history_to_s
-      history.map do |result|
-        "Status: #{result.status}; Command: #{result.command}\n#{result.out}\n--------------------\n"
-      end.join
+      history.map(&:to_s).join("\n#{'-' * 20}\n")
     end
 
 
   private
+    def execute_commands(commands)
+      commands.each do |command|
+        out = StringIO::new
+
+        # Run the command through the active shell session
+        session.execute(command, :stdout => out, :stderr => out)
+
+        # Construct result and store is as part of the command history
+        result = Result.new(command, out.string, session.exit_status)
+        history << result
+
+        # Bubble up a failure exception if the command failed
+        raise Failure.new(result) if result.failure?
+      end
+    end
+
     def session
       @session ||= Session::Bash::Login.new
     end
@@ -57,8 +75,13 @@ module GitRunner
       def failure?
         !success?
       end
+
+      def to_s
+        "Status: #{status}; Command: #{command}\n#{out}"
+      end
     end
 
+
     class Failure < StandardError
       attr_accessor :result
 

data/lib/git-runner/text.rb

@@ -1,5 +1,7 @@
 module GitRunner
-  class Text
+  module Text
+    extend self
+
     COLOR_START = "\033["
     COLOR_END   = "m"
     COLOR_RESET = "#{COLOR_START}0#{COLOR_END}"
@@ -22,45 +24,53 @@ module GitRunner
     }
 
 
-    class << self
-      def begin
-        STDOUT.sync = true
-        print("\e[1G       \e[1G")
-      end
+    def begin
+      STDOUT.sync = true
+      print("\e[1G       \e[1G")
+    end
 
-      def finish
-        print("\n")
-      end
+    def finish
+      print("\n")
+    end
 
-      def out(str, style=nil)
-        # Ensure that new lines overwrite the default 'remote: ' text
-        str = str.gsub("\n", "\n\e[1G#{padding(nil)}")
+    def out(str, style=nil)
+      # Ensure that new lines overwrite the default 'remote: ' text
+      str = str.gsub("\n", "\n\e[1G#{padding(nil)}")
 
-        print "\n\e[1G#{padding(style).ljust(7)}#{str}"
-      end
+      print "\n\e[1G#{padding(style).ljust(7 + (@indentation || 0))}#{str}"
+    end
 
-      def new_line
-        out('')
-      end
+    def new_line
+      out('')
+    end
 
-      # Color methods
-      COLORS.each do |color, code|
-        class_eval <<-EOF
-          def #{color}(str, style=:normal)
-            "#{COLOR_START}\#{STYLES[style]};#{code}#{COLOR_END}\#{str}#{COLOR_RESET}"
-          end
-        EOF
-      end
+    def indent(spaces=2)
+      @indentation ||= 0
+      @indentation  += spaces
 
+      yield
+
+      @indentation -= spaces
+      Text.new_line
+    end
 
-    private
-      def padding(style)
-        case style
-        when :heading
-          '----->'
-        else
-          ''
+    # Color methods
+    COLORS.each do |color, code|
+      class_eval <<-EOF
+        def #{color}(str, style=:normal)
+          "#{COLOR_START}\#{STYLES[style]};#{code}#{COLOR_END}\#{str}#{COLOR_RESET}"
         end
+      EOF
+    end
+
+
+  private
+    def padding(style)
+      case style
+      when :heading
+        '----->'
+      else
+        ''
       end
     end
   end

data/lib/git-runner/version.rb

@@ -1,3 +1,3 @@
 module GitRunner
-  VERSION = '0.0.6'
+  VERSION = '0.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: git-runner
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-09 00:00:00.000000000 Z
+date: 2012-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: session
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 3.1.0
 description: GitRunner is a ruby framework to implement and run tasks after code has
   been pushed to a Git repository. It works by invoking `git-runner` through `hooks/post-update`
   in your remote Git repository.