Pond is a shell environment manager for the fish shell.
Group related functions together into named ponds and expose them to the shell environment using load
, unload
, enable
, or disable
commands. Use special autoload
and autounload
functions to set or unset environment variables when ponds are loaded or unloaded.
Pond started life as a small idea: to group related shell environment variables and functions into named collections (ponds) and to provide a simple mechanism for controlling when those collections are loaded into the shell environment. It does this by leveraging autoloaded functions as a means of encapsulating environment configuration and provides a simple set of subcommands to manage such configuration.
Install with Fisher:
$ fisher install marcransome/pond
Or with Oh My Fish:
$ omf install https://github.com/marcransome/pond
Create an empty pond using the create
command:
$ pond create my_app
Ponds are enabled by default, meaning any functions that are added will automatically be made available in new shell sessions. To disable this behaviour set the universal variable pond_enable_on_create
to no
:
$ set -U pond_enable_on_create no
Move to the pond directory for which you wish to add a function:
$ pond dir my_app
Add one or more related functions to the pond directory. For example:
$ vi start_my_app.fish
...
Provide a suitable function definition:
function start_my_app
...
end
Use the enable
command to make functions belonging to a pond accessible to new shell sessions:
$ pond enable my_app
Enabled pond: my_app
Use the disable
command to make functions belonging to a pond inaccessible to new shell sessions:
$ pond disable my_app
Disabled pond: my_app
Use the load
command to make pond functions available in the current shell session:
$ pond load my_app
Loaded pond: my_app
Use the unload
command to remove pond functions from the current shell session:
$ pond unload my_app
Unloaded pond: my_app
A pond may include an optional autoload function which is automatically executed in the current shell whenever the pond is loaded using the load
command. If a pond is enabled then its autoload function, if present, will be executed automatically in each new shell that is created. Autoload functions are the recommended way of exporting shell variables for a pond.
To create or edit an existing autoload function for a pond and open it in an interactive editor:
$ pond autoload my_app
Populate the autoload function with environment variables as required:
function my_app_autoload
set -xg MY_APP_ADDR localhost
set -xg MY_APP_PORT 9999
end
A pond may include an optional autounload function which is automatically executed in the current shell whenever the pond is unloaded using the unload
command. Autoload functions are the recommended way of erasing shell variables for a pond that were previously set using an autoload function.
To create or edit an existing autounload function for a pond and open it in an interactive editor:
$ pond autounload my_app
Populate the autounload function with the required cleanup commands:
function my_app_autounload
set -e MY_APP_ADDR
set -e MY_APP_PORT
end
This function is automatically executed if a pond is unloaded.
Use the status
command without arguments to view the global status of all ponds:
$ pond status
β pond 2.5.4
Health: good
Ponds: 1 (1 enabled; 1 loaded)
Loaded: /root/.config/fish/pond
βββ’ my_app
Use the status
command to view the status of a pond:
$ pond status my-app
β my_app (/root/.config/fish/pond/my_app)
Status: loaded, enabled
Health: good
Autoload: present
Autounload: absent
Functions: 1
Size: 8.0K
Use the list
command to list all available ponds:
$ pond list
my_app
Use one or more filter options to limit the output:
$ pond list --enabled
my_app
Use the remove
command to remove a pond:
$ pond remove my_app
Remove pond: my_app? y
Removed pond: my_app
To automatically accept the confirmation prompt use the -y
or --yes
option:
$ pond remove --yes my_app
Removed pond: my_app
Use the drain
command to drain all functions from a pond:
$ pond drain my_app
Drain pond: my_app? y
Drained pond: my_app
To automatically accept the confirmation prompt use the -y
or --yes
option:
$ pond drain --yes my_app
Drained pond: my_app
To view global configuration settings for pond
:
$ pond config
Pond home: /Users/<username>/.config/fish/pond
Enable ponds on creation: yes
Pond editor command: /usr/local/bin/vim
To open a pond directory:
$ pond dir my_app
The current working directory will be changed to the pond directory.
Only a small subset of operations is documented here. Additional documentation is provided through usage output when pond
is invoked with no arguments, or by invoking it with the --help
option. Use pond <command> --help
for details of a specific command.
An optional man page is provided and discussed in more detail below.
The pond(1)
man page is provided separately from the plugin installation for pond
itself. To install the latest version of the man page:
Using fish
:
curl https://github.com/raw/marcransome/pond/main/docs/install.fish | fish
Or, using bash
:
bash -c "$(curl https://github.com/raw/marcransome/pond/main/docs/install.sh)"
To install the man page corresponding to a specific version of pond
, replace the branch name main
in the above URLs with the semantic version number (use pond --version
to obtain the version string).
As an alternative to installing the man page, view the latest version of the man page online.
Pond emits events for many successful operations. Setup an event handler to repond to such events with your own code:
Event name | Description | Arguments |
---|---|---|
pond_created |
Emitted when a pond is created | argv[1] : pond nameargv[2] : pond path |
pond_removed |
Emitted when a pond is removed | argv[1] : pond nameargv[2] : pond path |
pond_enabled |
Emitted when a pond is enabled | argv[1] : pond nameargv[2] : pond path |
pond_disabled |
Emitted when a pond is disabled | argv[1] : pond nameargv[2] : pond path |
pond_loaded |
Emitted when a pond is loaded | argv[1] : pond nameargv[2] : pond path |
pond_unloaded |
Emitted when a pond is unloaded | argv[1] : pond nameargv[2] : pond path |
pond_drained |
Emitted when a pond is drained | argv[1] : pond nameargv[2] : pond path |
For example, to write the name of each new pond created to a file:
function pond_create_handler --on-event pond_created --argument-names pond_name pond_path
echo "$pond_name was created at $pond_path on "(date) >> ~/my-ponds
end
A pre-configured dev container is provided with all of the tools necessary to contribute changes to the project. Create a codespace from the main
branch of the repository and open a terminal window for a brief overview of where to begin:
Alternatively, clone the repository and build a local container image, then mount your local repository when starting a container:
cd .devcontainers
docker build -t pond .
cd ..
docker run --rm -it -v $(pwd):/workspaces/pond pond
The project sources will be mounted at /workspaces/pond
, and the container will be ready for you to begin making changes:
βββββββββββββββββββ
βββββββββββββββββββ dev container
βββββββββββββββββββ rockylinux:9.3-minimal
- See CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing changes
to the project
- Install/reinstall pond in the container by running: tools/install
- Start the full unit test suite by running: tools/test
- To run individual test files, invoke fishtape directly. For example, to
run the 'create' command tests: fishtape tests/create.fish
- To update the man pages, make your changes in the docs/pond.md file then
regenerate the html5 and roff format files in docs/ by running: tools/gen-doc
But most of all, have fun!
root@0890fd0c5306 /#
However you choose to work, contributions are most welcome.
- Pond icon made by Freepik from www.flaticon.com
- Pond's workflow uses the fishtape test runner and tap-diff to make things pretty
Pond is provided under the terms of the MIT License.
Email me at marc.ransome@fidgetbox.co.uk or create an issue.