project

project copied to clipboard

h1. Project

• Overview
• Installation
• Usage
• Changelog
• Bugs
• Contributors
• Note on Patches/Pull Requests

h2. Overview

Project aims to make working with multiple projects as simple as possible. By registering projects with workflows you can quickly create a set of commands that will be run against each project. Check out the "blog post":http://blog.josh-nesbitt.net/2010/08/21/project-simplified-project-workflows/ for a bit more background on how @project@ came to life.

h2. Installation

The project is hosted on "rubygems.org":http://rubygems.org. Getting it is simple:

pre. gem install project

Once the gem is installed run:

pre. project install

Assuming you haven't already had the gem installed this will create a file at @~/.project@ (or @~/.config/project/config.yaml@, if you're using X). This is the main configuration file used to drive project.

h2. Usage

Project uses a YAML file for its configuration. Edit the file located in at @~/.project@ to you liking.

h3. Projects

A project can be anything revolving around a particular context. A typical use case would be opening your default environment for a project. An example project configuration might look like this:

pre. :name: :path: /path/to/project :workflow: default

The only required key within a project is workflow. This is important as you need to tell the @project@ binary which workflow to apply against the project. Any other variables specified here will be passed through to a workflow (more on this below).

h3. Workflows

A workflow is a set of commands you want run against a particular project. An example workflow might look something like this:

pre. :default:

• cd %path
• mate .
• gitx

Which translates to:

• @cd /path/to/project@
• @mate .@
• @gitx@

A workflow is just a YAML array of templated commands. Any variable used in a workflow will get looked up on the project that's running it. In the example above the @%path@ variable is replaced by the path specified within the project. Using this method you can quickly build up a set of common workflows to use against many projects.

Each workflow runs within its own subshell. This means that every command executed will run in the environment as it was left by the previous command. Given the above workflow, first a command executes which changes the current directory then commands are executed relative to that directory.

My default workflow looks something like this:

pre. :default:

• cd %path
• mate .
• gitx
• open 'http://%basecamp_url'
• open 'http://%app'
• rails server

Which:

• changes to the project directory
• opens the project in Textmate
• opens it's Git history in GitX
• opens the Basecamp project for the app
• starts the Rails server (and opens it up in the default browser)

Note: at the moment commands do not support being daemonised, hence why the call to @rails server@ is the last command executed.

h3. Running a project

Running a project is simple, just specify the name of the project you want to load and the workflow will run for it:

pre. project name

h2. Changelog

h3. 1.3.0

• Added support for an alternative configuration file on X based systems (within @XDG_CONFIG_HOME@) thanks to Simon Hafner.

h3. 1.2.0

• Added the ability for each workflow command to run within the same sub-shell. Commands executed within a sequence now respect the last ran command.

h3. 1.1.0

• Fixed issue in the template regular expression where numerics were being ignored.

h2. Bugs

If you have any problems with Project, please file an "issue":http://github.com/joshnesbitt/project/issues.

h2. Contributors

• Simon Hafner ("Tass":http://github.com/Tass)

h2. Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

h2. Author

Josh Nesbitt / "[email protected]":mailto:[email protected] / "josh-nesbitt.net":http://josh-nesbitt.net