README.md

SWORK

Table of Contents

Introduction

Examples

Install

Usage

Introduction

Command line utility to start up enviroments for particular projects. Project
configuration scripts can be any executable file and are associated with a
particular project via ~/.sworkrc file. The utility saves the enviroment
variables that exist before its execution and restores them as necessary. It can
also call teardown scripts as necessary when switching projects (or restoring
the original shell).

I have previously written very complex enviroment management tools for
particular projects. Facing the prospect of making yet another project specific
tool, I decided to write a general purpose extensible tool.

Swork is licensed under the terms of GPLv2, see the license file for details.

Current Limitations

swork only supports the Bash shell right now. It would be fairly trivially to
add another shell however, I will only do so if there is a user for it. If you
would like to swork with another shell besides bash please email me. (or you
know this is the 2013 you could fork it and add it yourself).

swork may also support zsh although this is entirely untested.

Installing from PyPI

Install the package

pip install swork

Then make an alias for source swork. I call my alias sw for convience eg.

alias sw="source `which swork`"

for the lazy

echo 'alias sw="source `which swork`"' >> ~/.bashrc

Installing from Github

first use pip to install the packages (this installs the current stable version
0.5). If you would like to install the master remove "@r0.5". Or simply update
aftwards with swork update [-s] --release=master.

Updating, Staying Current

You can update one of two ways. First you can use the built in update command.
Giving it the sudo option causes it to automatically preprend sudo to the
generated command. This checks out the head of the release branch you are on.
(eg. 0.2). See the Usage section for more details on the update command.

sw update [--sudo]

The other way is to use pip. The command below is an example command, and is in
fact the command generated by swork update.

Note: You will need to use --sudo when updating and checking for updates if
you installed swork as root.

Examples

Add a project:

$ cd to a project directory
$ sw add project_name

you will be prompted to write scripts for startup and teardown. The scripts you
write will be saved to the projects directory as .swork.activate and
.swork.deactivate. (You can add project manually and customize them further by
editing ~/.sworkrc. See sw --help-config for more details.)

This saves all the enivroment variables and sources start_cmd in the
configuration file (.sworkrc). If you added the project using sw add then it
will source your .swork.activate file. Additionally, (no matter how you
created project) it will create a new enviroment variable SW_PROJECT_ROOT
containing the path to the root of your project.

Restore the original enviroment:

$ sw restore

cd to a project:

$ sw cd proj1
$ pwd
/path/to/proj1

cd to a sub-dir of a project:

$ sw cd proj1/sub/directory
$ pwd
/path/to/proj1/sub/directory

Finally you can have swork automatically cd to a project sub-dir when starting a
project by:

$ swork start -c proj1/sub/dir
$ pwd
/path/to/proj1/sub/dir

Usage

sw --help

usage: swork [-h] [start|add|restore|list|cd|update] [project_name]
setups the enviroment to work on a particular project
Options
-h, help shows help message
--help-config show the help on the config file
--help-examples show some usage examples
Commands
restore Restores the original environment for the shell
list List all available projects.
update start the autoupdater
cd cd the path to the project
start start work on a project
add add a new project.
path echo the path to the project
rm remove a project from the rc file.

sw --help-config

The RC File.
Swork is capable of setting up its own configuration file. (Just use the `add`
command). However, here is now the configuration file is structured in case you
want to edit it.
Location: `$HOME/.sworkrc`
{
"project1" : {
"root":"/path/to/project/root",
"start_cmd":"source /path/to/project/root/then/setenv"
"teardown_cmd":"echo 'project1 teardown'"
},
"project2" : {
"root":"/path/to/project/root",
"start_cmd":"source /path/to/project/root/then/setenv"
"teardown_cmd":"echo 'project2 teardown'"
}
}
The contents must be valid json (as recognized by the python json lib) and
must have the schema:
project_name1 ->
root -> string
start_cmd -> string
teardown_cmd -> string
project_name2 ->
root -> string
start_cmd -> string
teardown_cmd -> string
- project_name is a string and the name of the project.
- root is the file system path to the root directory of the project.
- start_cmd will be sourced by the shell on startup.
- teardown_command will be sourced by the shell at teardown.
`sw add` uses the following templates to generate start_cmd/teardown_cmd(s)
echo "start/stop <project-name>"; source <path-to-[de]activate>