repos.zsh

A zsh shell function that makes it fast to jump between git repos. Shows a numbered list of favourites and recently visited repos, so you can cd or open in VS Code with a single short command.

Demo #

Example #

With fzf installed, repos opens the interactive picker shown above. Without it (or with output piped), you get a numbered list instead:

$ repos
Favourites:
  [1]  frontend             work/frontend
  [2]  site                 personal/my-site

Recently accessed:
  [3]  api-service
  [4]  docs

$ repos frontend    # cd to frontend
$ repos 2           # cd to site
$ repos add api     # bookmark current dir as 'api' — applies immediately
$ code frontend     # open the frontend repo in VS Code

Installation #

1. Download repos.zsh and source it in your .zshrc:

source ~/path/to/repos.zsh

2. Reload your shell:

source ~/.zshrc

On first run, ~/.reposrc is created automatically with defaults you can customise.

Configuration #

Edit ~/.reposrc (or run repos edit):

# Root folder that contains all your repos
REPOS_DIR="$HOME/code"

# Subfolders of REPOS_DIR that themselves contain repos
# e.g. if you have Code/work/project-a, Code/work/project-b
REPOS_GROUPS=("work" "personal")

# Favourites — short aliases for repos you use most
fav frontend "work/frontend"
fav site     "personal/my-site"

Usage #

repos              Interactive fuzzy picker (fzf), or the numbered list as a fallback
repos -a           List all repos (numbered)
repos <name>       cd to a repo by name or favourite alias
repos <number>     cd to a repo by number from the last list
repos <path>       cd to a directory by path (e.g. repos ~/work/thing)
repos -            Jump back to the previous repo (toggles, like cd -)
repos .            Add the current directory to recent history (stays put)
repos add <name>   Add current directory as a favourite
repos remove <name>  Remove a favourite (or recent-history entry)
repos edit         Open ~/.reposrc in $EDITOR
repos --help       Show usage

When fzf is installed, a bare repos in an interactive terminal opens a fuzzy picker. It shows your favourites (★) and recent repos (↺) by default and reveals every repo once you start typing. Searching matches repo names only — not numbers or paths — and typing just a number jumps straight to that row, ready for Enter. Arrow keys move (wrapping at either end), and:

• ↵ Enter — cd to the repo
• a number — jump to that numbered row
• Ctrl-G — cd and open in VS Code
• Ctrl-O — open in VS Code without moving your shell
• Ctrl-F — make it a favourite
• Ctrl-X — remove the highlighted favourite or recent
• Shift-↑ / Shift-↓ — move a favourite up or down
• ? — show help

Without fzf (or when output is piped) it prints the numbered list instead; use repos -a any time you want the numbered list.

code works the same way but opens the repo in VS Code instead of cd-ing to it:

code tools       # open the 'tools' favourite in VS Code
code 3           # open item 3 from the last list
code .           # open the current repo — also recorded in recent history

Features #

• Fuzzy picker — with fzf installed, a bare repos opens an interactive picker: favourites and recents by default, all repos on search, with keys to cd, open in VS Code, favourite, or reorder favourites; falls back to the numbered list otherwise
• Numbered navigation — run repos -a to get a list, then repos 3 to jump there; the index persists between repos and code calls
• Jump back — repos - toggles to the previous repo, like cd -
• Colour output — section headings in yellow, repo names in cyan, indices dimmed; makes lists easy to scan at a glance
• Favourites with aliases — map short names to long paths via fav in ~/.reposrc
• Recent history — automatically tracks the last 8 repos visited (including any directory opened by path, e.g. code .); repos outside your tree are remembered by full path
• Group support — walk into subfolders (e.g. work/, personal/) to find repos without them being top-level
• Tab completion — subcommands, aliases and folder names complete with <Tab>; favourites show their path in the completion menu
• Config auto-reload — edits to ~/.reposrc (including repos add/remove) apply immediately, no shell reload needed

Version history #

Version	Date	Notes
0.4.0	2026-07-10	Picker refinements: typing a number jumps to that row (search no longer matches index labels or paths — names only, with match highlighting); arrows wrap and skip the group dividers, which are now blank lines; clearer, evenly sized markers (★ favourites, ↺ recents, • repos); numbered navigation (repos 3, code 3) stays in sync after favouriting, removing or reordering in the picker
0.3.0	2026-07-08	Interactive fzf picker for a bare repos (numbered-list fallback): favourites and recents by default, all repos on search, with keys to cd, open in VS Code, favourite a repo, or reorder favourites; path-based recents remember repos anywhere (not just under REPOS_DIR), navigable by number or path; add repos - to jump back to the previous repo
0.2.1	2026-07-08	code . (and other paths to a known repo) now records the repo in recent history; add repos . to note the current directory without navigating
0.2.0	2026-07-05	Config auto-reloads on every run (no more source ~/.zshrc); add repos remove; tab completion covers subcommands and shows favourite paths; hide empty list sections; code prefers a real file over a same-named repo; friendlier errors for stale favourites; internal cleanup
0.1.4	2026-07-05	Fix code wrapper treating option flags (e.g. --list-extensions) as repo names; stop suppressing VS Code CLI errors
0.1.3	2026-03-10	Fix bug with handling of . and ~
0.1.2	2026-03-08	Tweak formatting
0.1.1	2026-03-08	Fix bug with absolute paths and tweak colours
0.1	2026-03-08	Initial release