Pond

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.

Background

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.

Installation

Install with Fisher:

$ fisher install marcransome/pond

Or with Oh My Fish:

$ omf install https://github.com/marcransome/pond

Creating ponds

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

Adding functions to a pond

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

Enabling ponds

Use the enable command to make functions belonging to a pond accessible to new shell sessions:

$ pond enable my_app
Enabled pond: my_app

Disabling ponds

Use the disable command to make functions belonging to a pond inaccessible to new shell sessions:

$ pond disable my_app
Disabled pond: my_app

Loading ponds

Use the load command to make pond functions available in the current shell session:

$ pond load my_app
Loaded pond: my_app

Unloading ponds

Use the unload command to remove pond functions from the current shell session:

$ pond unload my_app
Unloaded pond: my_app

Autoload functions

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

Autounload functions

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.

Viewing global status

Use the status command without arguments to view the global status of all ponds:

$ pond status
● pond 2.5.0
     Health: good
      Ponds: 1 (1 enabled; 1 loaded)
     Loaded: /root/.config/fish/pond
             └─• my_app

Viewing pond status

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

Listing ponds

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

Removing ponds

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

Draining ponds

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

Viewing global configuration

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

Opening a pond directory

To open a pond directory:

$ pond dir my_app

The current working directory will be changed to the pond directory.

Additional documentation

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.

Installing the man page

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://raw.githubusercontent.com/marcransome/pond/main/docs/install.fish | fish

Or, using bash:

bash -c "$(curl https://raw.githubusercontent.com/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).

Viewing the man page online

As an alternative to installing the man page, view the latest version of the man page online.

Event handlers

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 name argv[2]: pond path
pond_removed	Emitted when a pond is removed	argv[1]: pond name argv[2]: pond path
pond_enabled	Emitted when a pond is enabled	argv[1]: pond name argv[2]: pond path
pond_disabled	Emitted when a pond is disabled	argv[1]: pond name argv[2]: pond path
pond_loaded	Emitted when a pond is loaded	argv[1]: pond name argv[2]: pond path
pond_unloaded	Emitted when a pond is unloaded	argv[1]: pond name argv[2]: pond path
pond_drained	Emitted when a pond is drained	argv[1]: pond name argv[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

Contributing

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.

Acknowledgements

• Pond icon made by Freepik from www.flaticon.com
• Pond's workflow uses the fishtape test runner and tap-diff to make things pretty

License

Pond is provided under the terms of the MIT License.

Contact

Email me at marc.ransome@fidgetbox.co.uk or create an issue.