A shell enviroment manager. Easily manage the shell enviroment (variables etc.) for working on various projects. Stands for start work.
Python Shell
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



by Tim Henderson (tim.tadh@gmail.com)

Table of Contents

  1. Introduction
  2. Examples
  3. Install
  4. Usage


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.

pip install --src="$HOME/.src" -e git://github.com/timtadh/swork.git@r0.5#egg=swork

then modify your .bashrc to make the command an alias for

source swork [args]

I call my alias sw for convience eg.

alias sw="source `which swork`"

for the lazy

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

Now to get started using swork add a project!

$ cd to a project
$ sw add project_name

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.

pip install --src="$HOME/.src" --upgrade -e git://github.com/timtadh/swork.git@r0.5#egg=swork

You can check if there are updates available using:

sw update [--sudo] --check

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


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.)

List your projects:

$ sw list
    root : /path/to/code/project1
    start_cmd : echo 'project1 setup'; source .swork.activate
    teardown_cmd : echo 'project1 teardown'; source .swork.deactivate
    root : /path/to/code/project2
    start_cmd : echo 'project2 setup'; source .swork.activate
    teardown_cmd : echo 'project2 teardown'; source .swork.deactivate

Setup the enviroment:

$ sw start project1

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

cd to a sub-dir of a project:

$ sw cd proj1/sub/directory
$ pwd

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

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


sw --help

usage: swork [-h] [start|add|restore|list|cd|update] [project_name]

setups the enviroment to work on a particular project

     -h, help                      shows help message
     --help-config                 show the help on the config file
     --help-examples               show some usage examples

     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" : {
            "start_cmd":"source /path/to/project/root/then/setenv"
            "teardown_cmd":"echo 'project1 teardown'"
        "project2" : {
            "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>