# workenv
[](https://pypi.org/project/workenv/)
[](https://github.com/radiac/workenv/actions/workflows/ci.yml)
[](https://codecov.io/gh/radiac/workenv)
A shortcut for jumping between local work environments in bash, and carrying out tasks
within them.
Requires Python 3.7+ and bash.
## Quick example
Example `~/.workenv_config.yml`:
```yaml
myproject:
path: /path/to/myproject
source: venv/bin/activate
run:
- nvm use
commands:
database:
run: docker-compose up database
otherproject:
file: /path/to/otherproject
```
Example usage:
```bash
# Jump to /path/to/myproject with the local python virtual environment and nvm
we myproject
# Jump to /path/to/myproject and run the database container
we myproject database
# Bash completion support
we m<tab> d<tab>
```
There is also support for a `_common` project with values applied to all projects, and
for projects which define their own settings locally in `,workenv.yml` files - see docs
below.
## Installation
**Recommended**: Install using [pipx](https://pypa.github.io/pipx/):
```bash
pipx install workenv
workenv --install
```
**Alternative**: Install to a virtual environment with::
```bash
cd path/to/installation
python -m venv venv
source venv/bin/activate
pip install workenv
workenv --install
```
Both of these options will add the command as `we` by adding a line to your `.bashrc`.
If you would prefer a different command name, you can specify it when installing:
```bash
workenv --install workon
```
Restart your shell session for your change to take effect.
To uninstall, remove the line from `.bashrc`, and either uninstall with pipx or delete
your virtual environment.
## Configuration
Add the current path as a new project:
```bash
we --add projectname
```
Add the current path as a new command::
```bash
we --add projectname command
```
Open your `.workenv_config.yml` for customisation::
```bash
we --edit
```
The top level of the YAML file are the names of the projects.
Values can substitute the project name with `{{project.name}}` or `{{project.slug}}`.
### Special rules
There are two special top-level YAML objects:
#### `_config`
Controls settings:
* `verbose` - if `true`, show bash commands when running them
* `history` - if `true`, add the commands to history
#### `_common`
Common project which can define a common `source`, `env`, `run` and `commands`
which will be added to all other projects, regardless of whether they define their
own.
The common project cannot specify a path.
### Project rules
A project can have the following attributes:
#### `path`
The path to set as the current working directory. This will be the first command run.
Example:
```yaml
myproject:
path: /path/to/foo
```
Bash equivalent:
```bash
cd /path/to/foo
```
#### `source`
Path or paths to call using `source`
Example:
```yaml
myproject:
source:
- venv/bin/activate
- .env
```
Bash equivalent:
```bash
source venv/bin/activate
source .env
```
#### `env`
Dict of environment variables to set
Example:
```yaml
myproject:
env:
COMPOSE_PROJECT_NAME: my_project
```
Bash equivalent:
```bash
export COMPOSE_PROJECT_NAME=my_project
```
#### `run`
Command or list of commands to run
Example:
```yaml
myproject:
run:
- nvm use
- yvm use
```
Bash equivalent::
```bash
nvm use
yvm use
```
#### `commands`
Dict of Command objects
Example:
```yaml
myproject:
commands:
database:
run: docker-compose up database
```
Usage:
```bash
we myproject database
```
Bash equivalent:
```bash
docker-compose up database
```
A command will inherit the `path` and `env` of its parent project, unless it defines its
own.
It will inherit the `source` of its parent project only if it does not specify its own
path or source.
A command can have the same attributes as a project, except it cannot define its own
`commands`.
## Full example
Putting together all the options above into a sample `.workenv_config.yml`:
```yaml
_config:
verbose: true
history: false
_common:
env:
COMPOSE_PROJECT_NAME: '{{project.slug}}'
PS1: '"\[\e[01;35m\]{{project.slug}}>\[\e[00m\]$PS1"'
commands:
open:
run: xdg-open .
myproject:
path: /path/to/myproject
source:
- venv/bin/activate
- .env
run:
- ./manage.py migrate
- ./manage.py runserver 0:8000
commands:
database:
run: docker compose up database
other:
path: /path/to/other
something-else:
config: /path/to/somethingelse
```
`we myproject` is equivalent to typing:
```bash
cd /path/to/myproject
source venv/bin/activate
source .env
export COMPOSE_PROJECT_NAME=myproject
./manage.py migrate
./manage.py runserver 0:8000
```
`we myproject database` is equivalent to typing:
```bash
cd /path/to/myproject
source venv/bin/activate
source .env
export COMPOSE_PROJECT_NAME=myproject
docker compose up database
```
`we other` is equivalent to typing:
```bash
cd /path/to/other
export COMPOSE_PROJECT_NAME=other
```
`we other open` is equivalent to:
```bash
cd /path/to/myproject
export COMPOSE_PROJECT_NAME=other
xdg-open .
```
and `something-else` will be configured in `/path/to/somethingelse/.workenv.yml`; `path`
will be automatically set to that dir:
```yaml
source:
- venv/bin/activate
- .env
run:
- ./manage.py migrate
- ./manage.py runserver 0:8000
commands:
database:
run: docker compose up database
```
Raw data
{
"_id": null,
"home_page": null,
"name": "workenv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "bash",
"author": null,
"author_email": "Richard Terry <code@radiac.net>",
"download_url": "https://files.pythonhosted.org/packages/6c/f2/b9b75bb9ea33cc4432412651f0cd92d9255e911fe796833676a2a3c92308/workenv-2.1.1.tar.gz",
"platform": null,
"description": "# workenv\n\n[](https://pypi.org/project/workenv/)\n[](https://github.com/radiac/workenv/actions/workflows/ci.yml)\n[](https://codecov.io/gh/radiac/workenv)\n\nA shortcut for jumping between local work environments in bash, and carrying out tasks\nwithin them.\n\nRequires Python 3.7+ and bash.\n\n\n## Quick example\n\nExample `~/.workenv_config.yml`:\n\n```yaml\nmyproject:\n path: /path/to/myproject\n source: venv/bin/activate\n run:\n - nvm use\n commands:\n database:\n run: docker-compose up database\notherproject:\n file: /path/to/otherproject\n```\n\nExample usage:\n\n```bash\n# Jump to /path/to/myproject with the local python virtual environment and nvm\nwe myproject\n\n# Jump to /path/to/myproject and run the database container\nwe myproject database\n\n# Bash completion support\nwe m<tab> d<tab>\n```\n\nThere is also support for a `_common` project with values applied to all projects, and\nfor projects which define their own settings locally in `,workenv.yml` files - see docs\nbelow.\n\n\n## Installation\n\n**Recommended**: Install using [pipx](https://pypa.github.io/pipx/):\n\n```bash\npipx install workenv\nworkenv --install\n```\n\n**Alternative**: Install to a virtual environment with::\n\n```bash\ncd path/to/installation\npython -m venv venv\nsource venv/bin/activate\npip install workenv\nworkenv --install\n```\n\nBoth of these options will add the command as `we` by adding a line to your `.bashrc`.\n\nIf you would prefer a different command name, you can specify it when installing:\n\n```bash\nworkenv --install workon\n```\n\nRestart your shell session for your change to take effect.\n\nTo uninstall, remove the line from `.bashrc`, and either uninstall with pipx or delete\nyour virtual environment.\n\n\n## Configuration\n\nAdd the current path as a new project:\n\n```bash\nwe --add projectname\n```\n\nAdd the current path as a new command::\n\n```bash\nwe --add projectname command\n```\n\nOpen your `.workenv_config.yml` for customisation::\n\n```bash\nwe --edit\n```\n\nThe top level of the YAML file are the names of the projects.\n\nValues can substitute the project name with `{{project.name}}` or `{{project.slug}}`.\n\n\n### Special rules\n\nThere are two special top-level YAML objects:\n\n#### `_config`\n\nControls settings:\n\n* `verbose` - if `true`, show bash commands when running them\n* `history` - if `true`, add the commands to history\n\n#### `_common`\n\nCommon project which can define a common `source`, `env`, `run` and `commands`\nwhich will be added to all other projects, regardless of whether they define their\nown.\n\nThe common project cannot specify a path.\n\n\n### Project rules\n\nA project can have the following attributes:\n\n#### `path`\n\nThe path to set as the current working directory. This will be the first command run.\n\nExample:\n\n```yaml\nmyproject:\n path: /path/to/foo\n```\n\nBash equivalent:\n\n```bash\ncd /path/to/foo\n```\n\n#### `source`\n\nPath or paths to call using `source`\n\nExample:\n\n```yaml\nmyproject:\n source:\n - venv/bin/activate\n - .env\n```\n\nBash equivalent:\n\n```bash\nsource venv/bin/activate\nsource .env\n```\n\n#### `env`\n\nDict of environment variables to set\n\nExample:\n\n```yaml\nmyproject:\n env:\n COMPOSE_PROJECT_NAME: my_project\n```\n\nBash equivalent:\n\n```bash\nexport COMPOSE_PROJECT_NAME=my_project\n```\n\n#### `run`\n\nCommand or list of commands to run\n\nExample:\n\n```yaml\nmyproject:\n run:\n - nvm use\n - yvm use\n```\n\nBash equivalent::\n\n```bash\nnvm use\nyvm use\n```\n\n#### `commands`\n\nDict of Command objects\n\nExample:\n\n```yaml\nmyproject:\n commands:\n database:\n run: docker-compose up database\n```\n\nUsage:\n\n```bash\nwe myproject database\n```\n\nBash equivalent:\n\n```bash\ndocker-compose up database\n```\n\nA command will inherit the `path` and `env` of its parent project, unless it defines its\nown.\n\nIt will inherit the `source` of its parent project only if it does not specify its own\npath or source.\n\nA command can have the same attributes as a project, except it cannot define its own\n`commands`.\n\n\n## Full example\n\nPutting together all the options above into a sample `.workenv_config.yml`:\n\n```yaml\n_config:\n verbose: true\n history: false\n_common:\n env:\n COMPOSE_PROJECT_NAME: '{{project.slug}}'\n PS1: '\"\\[\\e[01;35m\\]{{project.slug}}>\\[\\e[00m\\]$PS1\"'\n commands:\n open:\n run: xdg-open .\nmyproject:\n path: /path/to/myproject\n source:\n - venv/bin/activate\n - .env\n run:\n - ./manage.py migrate\n - ./manage.py runserver 0:8000\n commands:\n database:\n run: docker compose up database\nother:\n path: /path/to/other\nsomething-else:\n config: /path/to/somethingelse\n```\n\n`we myproject` is equivalent to typing:\n\n```bash\ncd /path/to/myproject\nsource venv/bin/activate\nsource .env\nexport COMPOSE_PROJECT_NAME=myproject\n./manage.py migrate\n./manage.py runserver 0:8000\n```\n\n`we myproject database` is equivalent to typing:\n\n```bash\ncd /path/to/myproject\nsource venv/bin/activate\nsource .env\nexport COMPOSE_PROJECT_NAME=myproject\ndocker compose up database\n```\n\n`we other` is equivalent to typing:\n\n```bash\ncd /path/to/other\nexport COMPOSE_PROJECT_NAME=other\n```\n\n`we other open` is equivalent to:\n\n```bash\ncd /path/to/myproject\nexport COMPOSE_PROJECT_NAME=other\nxdg-open .\n```\n\nand `something-else` will be configured in `/path/to/somethingelse/.workenv.yml`; `path`\nwill be automatically set to that dir:\n\n```yaml\nsource:\n- venv/bin/activate\n- .env\nrun:\n- ./manage.py migrate\n- ./manage.py runserver 0:8000\ncommands:\n database:\n run: docker compose up database\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Manage local work environments",
"version": "2.1.1",
"project_urls": {
"Changelog": "https://github.com/radiac/workenv/blob/main/changelog.rst",
"Homepage": "https://radiac.net/projects/workenv/",
"Issues": "https://github.com/radiac/workenv/issues",
"Repository": "https://github.com/radiac/workenv"
},
"split_keywords": [
"bash"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e9887b2cfdac2ad4544a9604808f543dab7131095393a2100118f0404ef51c87",
"md5": "399c414187cff3f5a046bcb587c8d00a",
"sha256": "65dc33dda6e2d9e168aad635ea4caaf43ea29608b8d4f77f3dc6efeffd1040bd"
},
"downloads": -1,
"filename": "workenv-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "399c414187cff3f5a046bcb587c8d00a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 12187,
"upload_time": "2024-10-29T01:07:24",
"upload_time_iso_8601": "2024-10-29T01:07:24.634336Z",
"url": "https://files.pythonhosted.org/packages/e9/88/7b2cfdac2ad4544a9604808f543dab7131095393a2100118f0404ef51c87/workenv-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6cf2b9b75bb9ea33cc4432412651f0cd92d9255e911fe796833676a2a3c92308",
"md5": "0c85956efc3e2562963f02a5d80f028e",
"sha256": "51ec947ea48e5fb45e293aebef1b001944e59620f7f56ccf72a5dac37edeef14"
},
"downloads": -1,
"filename": "workenv-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "0c85956efc3e2562963f02a5d80f028e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14454,
"upload_time": "2024-10-29T01:07:25",
"upload_time_iso_8601": "2024-10-29T01:07:25.626996Z",
"url": "https://files.pythonhosted.org/packages/6c/f2/b9b75bb9ea33cc4432412651f0cd92d9255e911fe796833676a2a3c92308/workenv-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 01:07:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "radiac",
"github_project": "workenv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "mypy",
"specs": []
},
{
"name": "types-PyYAML",
"specs": []
},
{
"name": "uv",
"specs": []
},
{
"name": "pyyaml",
"specs": []
}
],
"lcname": "workenv"
}
JSON
