create-zush-repo

Create a zush repo plugin

Any git repo with a committed .zush/ directory is a zush plugin — no Python required. The folder layout under .zush/ is the command tree, and the script files are the commands. zush sync <repo> clones the repo with gh into ~/.zush/repos/<name> and rebuilds ~/.zush/repoindex.json.

Canonical reference:

• https://github.com/ZackaryW/zush/blob/main/docs/repos.md
• https://github.com/ZackaryW/zush/blob/main/docs/commands.md

Steps

1. Pick the install name. It is the tail of the repo URL minus .git (https://github.com/you/tools.git → tools). It becomes the first segment of every command from this repo.

2. Add a script under .zush/. The path under .zush/ maps to the dotted command: .zush/git/clean.sh in a repo installed as tools becomes tools.git.clean.

   # .zush/git/clean.sh
   #!/usr/bin/env bash
   echo "cleaning $1"
   

3. Commit and push the script.

4. Install and run. Re-running zush sync on an already-installed repo pulls the latest and re-indexes:

   zush sync https://github.com/you/tools     # installs as "tools"
   zush tools.git.clean ./tmp                 # -> cleaning ./tmp
   

Runner by file extension

Scripts run by extension, with the remaining CLI args passed through verbatim — zush does not parse a script's flags (there is no signature to read), so the script parses its own arguments.

Extension	Runner
.py	the Python interpreter running zush
.sh	bash
.ps1	pwsh -File

Notes

• gh and the relevant runner (bash / pwsh) must be on PATH.
• .zush/hooks/ is reserved — it is not indexed as commands. See https://github.com/ZackaryW/zush/blob/main/docs/hooks.md
• Override the store / index location with ZUSH_REPOS and ZUSH_REPO_INDEX (useful for testing against an isolated store).