{"id":17526013,"url":"https://github.com/marcransome/pond","last_synced_at":"2025-08-07T14:37:57.793Z","repository":{"id":37036890,"uuid":"337033269","full_name":"marcransome/pond","owner":"marcransome","description":"A shell environment manager for the fish shell. 🐟","archived":false,"fork":false,"pushed_at":"2024-09-13T18:48:00.000Z","size":1914,"stargazers_count":33,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-09-14T09:47:08.222Z","etag":null,"topics":["fish","fish-configuration","fish-functions","fish-plugin","fish-shell","fish-variables"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcransome.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"marcransome"}},"created_at":"2021-02-08T10:08:37.000Z","updated_at":"2024-09-13T18:48:03.000Z","dependencies_parsed_at":"2024-03-28T21:40:35.568Z","dependency_job_id":"c8550159-e84e-48b8-aabe-8b7a9783cad4","html_url":"https://github.com/marcransome/pond","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fpond","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fpond/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fpond/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcransome%2Fpond/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcransome","download_url":"https://codeload.github.com/marcransome/pond/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224019639,"owners_count":17242176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fish","fish-configuration","fish-functions","fish-plugin","fish-shell","fish-variables"],"created_at":"2024-10-20T15:01:13.185Z","updated_at":"2025-08-07T14:37:57.776Z","avatar_url":"https://github.com/marcransome.png","language":"Shell","funding_links":["https://github.com/sponsors/marcransome"],"categories":["Shell"],"sub_categories":[],"readme":"\u003cimg alt=\"pond\" src=\"images/pond.png\" width=\"180\" align=\"right\"\u003e\n\n# Pond\n\n[![Tests](https://img.shields.io/github/actions/workflow/status/marcransome/pond/test.yml?branch=main\u0026color=brightgreen\u0026label=tests)](https://github.com/marcransome/pond/actions) [![Issues](https://img.shields.io/github/issues/marcransome/pond)](https://github.com/marcransome/pond/issues) [![Dependabot](https://img.shields.io/badge/dependabot-active-brightgreen.svg)](https://github.com/marcransome/pond/network/dependencies) [![License](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/mit-license.php) [![fish](https://img.shields.io/badge/fish-3.6.4+-blue)](https://fishshell.com)\n\nPond is a shell environment manager for the [fish shell](https://fishshell.com).\n\n\u003chr\u003e\n\nGroup 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.\n\n## Background\n\nPond 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](https://fishshell.com/docs/current/language.html#autoloading-functions) as a means of encapsulating environment configuration and provides a simple set of subcommands to manage such configuration.\n\n## Installation\n\nInstall with [Fisher](https://github.com/jorgebucaran/fisher):\n\n```console\n$ fisher install marcransome/pond\n```\n\nOr with [Oh My Fish](https://github.com/oh-my-fish/oh-my-fish):\n\n```console\n$ omf install https://github.com/marcransome/pond\n```\n\n\u003e [!Note]\n\u003e Oh My Fish is currently [unmaintained](https://github.com/oh-my-fish/oh-my-fish/issues/947). Future updates may remove support for this plugin manager.\n\n### Creating ponds\n\nCreate an empty pond using the `create` command:\n\n```console\n$ pond create my_app\n```\n\nPonds 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`:\n\n```console\n$ set -U pond_enable_on_create no\n```\n\n### Adding functions to a pond\n\nMove to the pond directory for which you wish to add a function:\n\n```console\n$ pond dir my_app\n```\n\nAdd one or more related functions to the pond directory. For example:\n\n```\n$ vi start_my_app.fish\n...\n```\n\nProvide a suitable function definition:\n\n```fish\nfunction start_my_app\n  ...\nend\n```\n\n### Enabling ponds\n\nUse the `enable` command to make functions belonging to a pond accessible to new shell sessions:\n\n```console\n$ pond enable my_app\nEnabled pond: my_app\n```\n\n### Disabling ponds\n\nUse the `disable` command to make functions belonging to a pond inaccessible to new shell sessions:\n\n```console\n$ pond disable my_app\nDisabled pond: my_app\n```\n\n### Loading ponds\n\nUse the `load` command to make pond functions available in the current shell session:\n\n```console\n$ pond load my_app\nLoaded pond: my_app\n```\n\n### Unloading ponds\n\nUse the `unload` command to remove pond functions from the current shell session:\n\n```console\n$ pond unload my_app\nUnloaded pond: my_app\n```\n\n### Autoload functions\n\nA 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.\n\nTo create or edit an existing autoload function for a pond and open it in an interactive editor:\n\n```console\n$ pond autoload my_app\n```\n\nPopulate the autoload function with environment variables as required:\n\n```fish\nfunction my_app_autoload\n    set -xg MY_APP_ADDR localhost\n    set -xg MY_APP_PORT 9999\nend\n```\n\n### Autounload functions\n\nA 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.\n\nTo create or edit an existing autounload function for a pond and open it in an interactive editor:\n\n```console\n$ pond autounload my_app\n```\n\nPopulate the autounload function with the required cleanup commands:\n\n```fish\nfunction my_app_autounload\n    set -e MY_APP_ADDR\n    set -e MY_APP_PORT\nend\n```\n\nThis function is automatically executed if a pond is unloaded.\n\n### Viewing global status\n\nUse the `status` command without arguments to view the global status of all ponds:\n\n```console\n$ pond status\n● pond 2.6.2\n     Health: good\n      Ponds: 1 (1 enabled; 1 loaded)\n     Loaded: /root/.config/fish/pond\n             └─• my_app\n```\n\n### Viewing pond status\n\nUse the `status` command to view the status of a pond:\n\n```console\n$ pond status my-app\n● my_app (/root/.config/fish/pond/my_app)\n     Status: loaded, enabled\n     Health: good\n   Autoload: present\n Autounload: absent\n  Functions: 1\n       Size: 8.0K\n```\n\n### Listing ponds\n\nUse the `list` command to list all available ponds:\n\n```console\n$ pond list\nmy_app\n```\n\nUse one or more filter options to limit the output:\n\n```console\n$ pond list --enabled\nmy_app\n```\n\n### Removing ponds\n\nUse the `remove` command to remove a pond:\n\n```console\n$ pond remove my_app\nRemove pond: my_app? y\nRemoved pond: my_app\n```\n\nTo automatically accept the confirmation prompt use the `-y` or `--yes` option:\n\n```console\n$ pond remove --yes my_app\nRemoved pond: my_app\n```\n\n### Draining ponds\n\nUse the `drain` command to drain all functions from a pond:\n\n```console\n$ pond drain my_app\nDrain pond: my_app? y\nDrained pond: my_app\n```\n\nTo automatically accept the confirmation prompt use the `-y` or `--yes` option:\n\n```console\n$ pond drain --yes my_app\nDrained pond: my_app\n```\n\n### Viewing global configuration\n\nTo view global configuration settings for `pond`:\n\n```console\n$ pond config\nPond home: /Users/\u003cusername\u003e/.config/fish/pond\nEnable ponds on creation: yes\nPond editor command: /usr/local/bin/vim\n```\n\n### Opening a pond directory\n\nTo open a pond directory:\n\n```console\n$ pond dir my_app\n```\n\nThe current working directory will be changed to the pond directory.\n\n## Additional documentation\n\nOnly 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 \u003ccommand\u003e --help` for details of a specific command.\n\nAn optional man page is provided and discussed in more detail below.\n\n### Installing the man page\n\nThe `pond(1)` man page is provided separately from the plugin installation for `pond` itself. To install the _latest_ version of the man page:\n\nUsing `fish`:\n\n```console\ncurl https://raw.githubusercontent.com/marcransome/pond/main/docs/install.fish | fish\n```\n\nOr, using `bash`:\n\n```console\nbash -c \"$(curl https://raw.githubusercontent.com/marcransome/pond/main/docs/install.sh)\"\n```\n\nTo 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).\n\n### Viewing the man page online\n\nAs an alternative to installing the man page, [view the latest version of the man page online](http://htmlpreview.github.io/?https://github.com/marcransome/pond/blob/main/docs/pond.html).\n\n## Event handlers\n\nPond emits events for many successful operations. Setup an [event handler](https://fishshell.com/docs/current/language.html#event-handlers) to repond to such events with your own code:\n\nEvent name      | Description                     | Arguments\n--------------- | --------------------------------| ----------------------------------------------\n`pond_created`  | Emitted when a pond is created  | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n`pond_removed`  | Emitted when a pond is removed  | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n`pond_enabled`  | Emitted when a pond is enabled  | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n`pond_disabled` | Emitted when a pond is disabled | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n`pond_loaded`   | Emitted when a pond is loaded   | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n`pond_unloaded` | Emitted when a pond is unloaded | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n`pond_drained`  | Emitted when a pond is drained  | `argv[1]`: pond name\u003cbr /\u003e`argv[2]`: pond path\n\nFor example, to write the name of each new pond created to a file:\n\n```console\nfunction pond_create_handler --on-event pond_created --argument-names pond_name pond_path\n  echo \"$pond_name was created at $pond_path on \"(date) \u003e\u003e ~/my-ponds\nend\n```\n\n## Contributing\n\nA pre-configured [dev container](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers) is provided with all of the tools necessary to contribute changes to the project. [Create a codespace](https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository) from the `main` branch of the repository and open a terminal window for a brief overview of where to begin:\n\n\u003cimg alt=\"codespace\" src=\"images/codespace.png\"\u003e\n\nAlternatively, clone the repository and build a local container image, then mount your local repository when starting a container:\n\n```shell\ncd .devcontainer\ndocker build -t pond .\ncd ..\ndocker run --rm -it -v $(pwd):/workspaces/pond pond\n```\n\nThe project sources will be mounted at `/workspaces/pond`, and the container will be ready for you to begin making changes:\n\n```\n░▄▀▀▄░▄▀▀▄░█▀▀▄░█▀▄\n░█▄▄█░█░░█░█░▒█░█░█  dev container\n░█░░░░░▀▀░░▀░░▀░▀▀░  rockylinux/rockylinux:9.6-minimal\n\n - See CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing changes\n   to the project\n - Install/reinstall pond in the container by running: tools/install\n - Start the full unit test suite by running: tools/test\n - To run individual test files, invoke fishtape directly. For example, to\n   run the 'create' command tests: fishtape tests/create.fish\n - To update the man pages, make your changes in the docs/pond.md file then\n   regenerate the html5 and roff format files in docs/ by running: tools/gen-doc\n\n But most of all, have fun!\n\nroot@0890fd0c5306 /#\n```\n\nHowever you choose to work, contributions are most welcome.\n\n## Acknowledgements\n\n* Pond icon made by [Freepik](https://www.flaticon.com/authors/freepik) from [www.flaticon.com](https://www.flaticon.com/)\n* Pond's [workflow](https://github.com/marcransome/pond/actions) uses the [fishtape](https://github.com/jorgebucaran/fishtape) test runner and [tap-diff](https://github.com/axross/tap-diff) to make things pretty\n\n## License\n\nPond is provided under the terms of the [MIT License](https://opensource.org/licenses/mit-license.php).\n\n## Contact\n\nEmail me at [marc.ransome@fidgetbox.co.uk](mailto:marc.ransome@fidgetbox.co.uk) or [create an issue](https://github.com/marcransome/pond/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcransome%2Fpond","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcransome%2Fpond","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcransome%2Fpond/lists"}