{"id":24409507,"url":"https://github.com/tetzng/pez","last_synced_at":"2025-10-25T22:47:20.872Z","repository":{"id":270897473,"uuid":"908415306","full_name":"tetzng/pez","owner":"tetzng","description":"A Rust-based plugin manager for fish","archived":false,"fork":false,"pushed_at":"2025-04-07T23:45:43.000Z","size":403,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T17:16:10.973Z","etag":null,"topics":["fish","fish-shell","plugin-manager"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/pez","language":"Rust","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/tetzng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-26T02:55:53.000Z","updated_at":"2025-04-04T12:51:02.000Z","dependencies_parsed_at":"2025-01-03T21:41:24.556Z","dependency_job_id":"86d4b96a-216f-4854-a02d-064d58ce62ca","html_url":"https://github.com/tetzng/pez","commit_stats":null,"previous_names":["tetzng/pez"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetzng%2Fpez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetzng%2Fpez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetzng%2Fpez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetzng%2Fpez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tetzng","download_url":"https://codeload.github.com/tetzng/pez/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248262433,"owners_count":21074308,"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-shell","plugin-manager"],"created_at":"2025-01-20T05:58:14.877Z","updated_at":"2025-10-25T22:47:20.855Z","avatar_url":"https://github.com/tetzng.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003epez\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eA Rust-based plugin manager for \u003ca href=\"https://fishshell.com/\"\u003efish\u003c/a\u003e\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eExperimental\u003c/em\u003e — use at your own risk.\n\u003c/p\u003e\n\n## Installation\n\nEnsure you have Rust installed on your system. You can install pez using Cargo:\n\n```sh\n# From crates.io (if available)\ncargo install pez\n\n# From source (in this repo)\ncargo install --path .\n```\n\n## Quickstart\n\n```fish\n# 1) Initialize configuration (creates pez.toml)\npez init\n\n# 2) Add a plugin to pez.toml (choose one of repo/url/path)\n#    [[plugins]]\n#    repo = \"owner/repo\"      # GitHub shorthand\n#    # version = \"v3\"        # Or: tag = \"...\", branch = \"...\", commit = \"...\"\n#\n#    # [[plugins]]\n#    # url = \"https://gitlab.com/owner/repo\"  # Any Git host URL\n#    # branch = \"main\"\n#\n#    # [[plugins]]\n#    # path = \"~/path/to/local/plugin\"       # Local directory (absolute or ~/ only)\n#    # Note: when specifying a relative path at the CLI (e.g., ./plugin), pez normalizes it to an absolute path in pez.toml.\n\n# 3) Install plugins listed in pez.toml\npez install\n\n# 4) Verify installation\npez list --format table\n\n# 5) (Optional) Enable completions for pez itself\npez completions fish \u003e ~/.config/fish/completions/pez.fish\n```\n\n## Shell Completions\n\n```fish\npez completions fish \u003e ~/.config/fish/completions/pez.fish\n```\n\n## Docs \u0026 FAQ\n\n- [Getting started](docs/getting-started.md)\n  - [CLI usage](docs/getting-started.md#cli-usage-examples)\n  - [Completions](docs/getting-started.md#quick-start)\n- [Command reference](docs/commands.md)\n- [Configuration](docs/configuration.md)\n- [Architecture](docs/architecture.md)\n- [Install \u0026 build](docs/install.md)\n- [FAQ](docs/faq.md)\n\n## Usage (overview)\n\n```fish\nUsage: pez [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  init | install | uninstall | upgrade | list | prune | completions | doctor | migrate\n\nOptions:\n  -v, --verbose  Increase output verbosity (-v for info, -vv for debug)\n  -h, --help     Print help\n  -V, --version  Print version\n```\n\nCommon examples\n\n```fish\npez init\npez install                 # install from pez.toml\npez install owner/repo      # install a specific plugin\npez upgrade                 # update non-local plugins to remote HEAD\npez list --outdated --format table\npez prune --dry-run\n```\n\nSee the full command reference in [docs/commands.md](docs/commands.md).\n\n## Configuration\n\npez uses two main configuration files: `pez.toml` and `pez-lock.toml`.\nBy default, these files are created in the fish configuration directory,\nbut you can specify a different location using environment variables.\n\nConfiguration file locations\n\npez looks for `pez.toml` and `pez-lock.toml` in the following order:\n`$PEZ_CONFIG_DIR` \u003e `$__fish_config_dir` \u003e `$XDG_CONFIG_HOME/fish` \u003e `~/.config/fish`.\n\n`PEZ_TARGET_DIR` only affects where plugin files are copied. If you previously relied on\n`PEZ_TARGET_DIR` to relocate your configuration files, move `pez.toml` and\n`pez-lock.toml` into the directory referenced by `PEZ_CONFIG_DIR` (or set\n`PEZ_CONFIG_DIR` to that path) before running newer versions of pez.\n\n### pez.toml (Schema)\n\n`pez.toml` is the primary configuration file where you define the plugins\nyou want to manage. Below is an example structure:\n\n```toml\n# GitHub shorthand\n[[plugins]]\nrepo = \"owner/repo\"\n# version = \"latest\"   # default if omitted\n# version = \"v3\"       # branch or tag name; branches preferred over tags\n# branch  = \"develop\"\n# tag     = \"v1.0.0\"\n# commit  = \"\u003csha\u003e\"    # 7+ chars recommended (unique per repo)\n\n# Generic Git host URL\n[[plugins]]\nurl = \"https://gitlab.com/owner/repo\"\n# branch = \"main\"\n\n# Local path (absolute or ~/ only)\n[[plugins]]\npath = \"~/path/to/local/plugin\"\n```\n\n### pez-lock.toml\n\n`pez-lock.toml` is automatically generated and maintained by pez.\nIt records detailed information about the installed plugins,\nincluding their source repositories and specific commit SHAs.\nDo not edit this file manually.\n\n## Data Directory\n\npez clones plugin repositories into a designated data directory,\nprioritized as follows:\n`$PEZ_DATA_DIR` \u003e `$__fish_user_data_dir/pez` \u003e `$XDG_DATA_HOME/fish/pez` \u003e `~/.local/share/fish/pez`\n\nWhen you install a plugin, pez clones its repository into `pez_data_dir`.\nIf the directory doesn’t exist, pez will create it.\nRemote repositories that specify a host are stored under `\u003chost\u003e/\u003cowner\u003e/\u003crepo\u003e`\nwithin that data directory (for example `gitlab.com/owner/tool`). GitHub shorthand\ntargets (`owner/repo`) continue to resolve to `github.com/owner/repo`.\nIf the repository is already cloned:\n\n- For explicit CLI targets (`pez install owner/repo ...`), pez logs a warning and skips the reinstall unless you pass `--force`.\n- For installs driven by `pez.toml` (`pez install` with no targets), entries that already exist in `pez-lock.toml` and on disk are treated as up to date and skipped unless you pass `--force`. If a clone exists without a matching lockfile entry, pez returns an error unless you pass `--force`.\n\nAfter cloning, if the repository contains functions, completions, conf.d,\nor themes directories, pez will recursively copy files from these directories\nto the corresponding fish configuration directories:\n\n- `~/.config/fish/functions`\n- `~/.config/fish/completions`\n- `~/.config/fish/conf.d`\n- `~/.config/fish/themes`\n\nWhen installing plugins (either from pez.toml or explicit targets), pez detects\nduplicate destination paths across all plugins in the same run and skips the\nconflicting plugin with a warning to avoid overwriting existing files.\n\nThe destination fish configuration directory can be overridden using\n`PEZ_TARGET_DIR`; when it is unset, pez falls back to\n`$__fish_config_dir` \u003e `$XDG_CONFIG_HOME/fish` \u003e `~/.config/fish`.\n\nAdditionally, `pez-lock.toml` records information about the installed plugins\nand the files copied. It is created in the same directory as `pez.toml`\nand is updated if it already exists.\n\n### Concurrency\n\nControl job parallelism with the global `--jobs \u003cN\u003e` flag or the `PEZ_JOBS`\nenvironment variable (default: 4). The CLI flag takes precedence over the\nenvironment variable.\n\n- `install` (when CLI explicit targets are given): cloning is bounded by the\n  configured job limit\n- `upgrade` / `uninstall` / `prune` also honor the same job limit\n\n### Existing Clone Behavior\n\n- CLI explicit targets: skip with a warning unless `--force` (re‑clone).\n- From `pez.toml` (no targets): entries already tracked in `pez-lock.toml` with an existing clone are skipped unless you pass `--force`. If a clone exists without a matching lockfile entry, pez returns an error unless you pass `--force`.\n\n## Acknowledgements\n\npez is inspired by the following projects:\n\n- [fisher](https://github.com/jorgebucaran/fisher)\n- [oh-my-fish](https://github.com/oh-my-fish/oh-my-fish)\n- [fundle](https://github.com/danhper/fundle)\n\n## License\n\nMIT\n\n## Author\n\ntetzng\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetzng%2Fpez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftetzng%2Fpez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetzng%2Fpez/lists"}