README.markdown

Sublime Text 2 Guard Plugin

This project provides integration of Guard into the Sublime Text 2 editor. I wrote this as
a convenience tool to help improve my daily workflow while deving on numerous projects
using BDD and TDD.

This plugin provides an interface for controlling Guard and viewing Guards output within the
Sublime Text 2 editor. Not having to switch between a terminal and an editor to see Red/Green
states improves workflow drastically.

All of the commands are available via the command palette (super+shift+p).

When performing some operations in Sublime Text 2, like search, it hides the Guard output.
Therefore, this plugin provides a default key binding (super+shift+c) to show or reshow the Guard output.
It also has an auto show feature that shows or reshows the Guard output automatically when any new content
comes in from the Guard process.

Commands available when Guard is NOT running

Start Guard

Commands available all of the time

Hide Guard Output (disable auto show)

Show Guard Output (enable auto show) (super+shift+c)

Commands available when Guard IS running

Stop Guard

Run all Tests

Run all Tests & Show Guard Output (does NOT enable auto show) (ctrl+shift+g)

Package Control Installation

Open the Command Palette using super+shift+p and select Package Control: Install Package

Select Guard from the popup menu and press return

Wait for the status bar in the lower left conrner to notify you the install is complete.

Package Control Upgrade

If installed via Sublime Package Control. The plugin will be upgraded to
the latest version automatically at Sublime Text 2 startup. Therefore, if you want to force an upgrade of the plugins simply
Quit Sublime Text 2 and start it up again.

Manual Installation

To install this Sublime Text 2 plugin, simply run the following commands:

Manual Upgrade

Usage

Command Palette

As mentioned above the primary way of using this plugin is via the command palette (super+shift+p).
Once the command palette is up, fuzzy match the intendend command, and press the return key.

Starting Guard

If Guard is not currently running, start Guard using the "Start Guard" command. It will bring up a pane at
the bottom of the screen and show the output of Guard as it runs.

Show/Hide Guard Output

The Guard output can be shown and hidden using the "Show Guard Output" and "Hide Guard Output" command respectively.
The "Show Guard Output" command is also available via the default key binding (super+shift+c).

Run all Tests & Show Guard Output

Some users prefer a workflow in which the guard pane is hidden the majority of the time and it is just shown when they
run all the tests. For those users we have the "Run all Tests & Show Guard Output" command. This command shows the guard
output similar to the "Show Guard Output" command except this command does NOT enable auto show. This command is available
as always via the command pallete, but also via the key binding (ctrl+shift+g).

Other Useful Commands

A few of my favorites commands are "Run all Tests", "Reload Guard", and "Pause/Unpause". The
"Run all Tests" command will simply request that Guard run all of the tests. The "Reload Guard" command
is useful if changes have been made to Rails config initializers or something else that requires reloading. The
"Pause/Unpause" command is primarily useful when switching branches or rebasing. It will
temporarily prevent Guard from monitoring the project files for changes.

RVM Support

This plugin supports RVM out of the box. Basically, it means that it first checks to see if RVM is installed and loads it.
Once RVM is loaded it then looks to see if any of the top level folders in Sublime Text 2 contain a project specific .rvmrc. If one does it will
load that .rvmrc and attempt to run Guard on that project.

In the case where it can't find RVM it simply tries to run Guard assuming it is installed as a system gem.

rbenv Support

This plugin supports rbenv out of the box. This means it checks to see if $HOME/.rbenv exists and appropriately
modifies the PATH environment variable to include $HOME/.rbenv/bin in the path. It also runs rbenv init - for
you.

In the case where it can't find rbenv it simply tries to run Guard assuming it is installed as a system gem.

Clear Output when Matched String Found

The user must create a json file called Guard.sublime-settings in the user
config directory Packages/User/. This file has the following format:

{
"clear_when_find_this_text": "Running: .*_spec.rb"
}

Some suggested matches are as follows:

Running: .*_spec.rb

Running: .*_spec.rb|Failures:

Running: .*_spec.rb|Failures:|Reloading Spork for RSpec

If you do NOT want to use this feature simply do not define the clear_when_find_this_text setting.

FAQs

Does the Guard process die/exit when Sublime Text 2 dies/exits?

Yes.

Why would I get "Failed to find Guardfile and Gemfile in any of the open folders." as an error?

This error message is a result of the project currently loaded in Sublime Text 2 missing either the Guardfile, the Gemfile, or both.
Currently, this plugin requires a Guardfile and a Gemfile to be present in the projects root path to run Guard.