by Tim Henderson (tim.tadh@gmail.com)
- Introduction
- Examples
- Install
- 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.
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.
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
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
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
project1
root : /path/to/code/project1
start_cmd : echo 'project1 setup'; source .swork.activate
teardown_cmd : echo 'project1 teardown'; source .swork.deactivate
project2
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
/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: 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.
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>