sprs

A repo-aware git sparse-checkout helper for Zsh. It detects the repository you're standing in and applies one of two saved path sets:

• lean — just the directories you're actively editing
• full — lean plus the extra directories needed to actually run the code

This keeps large monorepos fast and focused: you check out the slice you care about, with a one-command path to a fuller checkout when you need to run things end to end.

Installation

sprs is a single sourced script with no framework dependencies, so any zsh plugin manager works. Pick the one you use.

Oh My Zsh

Clone this repo to your Oh My Zsh custom plugins directory:

git clone https://github.com/ppagni/zsh-sprs.git $ZSH_CUSTOM/plugins/sprs

Then enable it in ~/.zshrc:

plugins=(... sprs)

Then restart your shell, or for the current session only:

omz plugin load sprs

Zinit

zinit light ppagni/zsh-sprs

Antidote

Add to your bundle file (~/.zsh_plugins.txt):

ppagni/zsh-sprs

Any zsh (manual)

Clone anywhere and source the plugin file from ~/.zshrc:

git clone https://github.com/ppagni/zsh-sprs.git ~/.zsh/sprs
echo 'source ~/.zsh/sprs/sprs.plugin.zsh' >> ~/.zshrc

This also covers managers not listed above (zplug, zim, zgenom, …) — point them at sprs.plugin.zsh.

fzf is optional but recommended — it powers the interactive picker in sprs init. Without it, sprs init falls back to a numbered menu.

Usage

sprs init            interactive setup: pick lean dirs + full extras, save & apply
sprs lean            apply the saved lean checkout
sprs full            apply the saved lean + full checkout
sprs add <path>...   add paths to the current checkout ad-hoc
sprs show            list current sparse-checkout cone paths
sprs list            show this repo's saved lean/full sets
sprs disable         turn sparse-checkout off, restore full tree
sprs help            usage text

First-time setup

Inside a repo, run:

sprs init

You'll pick the lean directories (the ones you edit), then the full extras (dependencies, macros, packages — whatever you need to run the code on top of lean). Both sets are saved, and the lean checkout is applied immediately so the repo is usable right away. Re-running sprs init prompts before overwriting an existing config.

Switching levels

sprs lean    # narrow back to just what you're editing
sprs full    # widen to lean + the run dependencies

full applies the union of the lean and full sets, so you never lose your editing scope when you widen.

Ad-hoc and teardown

sprs add path/to/dir    # pull in one more directory without editing config
sprs show               # what's currently checked out
sprs disable            # restore the full working tree

Configuration

sprs init writes to a central config file at:

${XDG_CONFIG_HOME:-$HOME/.config}/sprs/config

Entries are tab-separated, one line per repo per level:

<repo-key>	lean	models/finance models/shared
<repo-key>	full	dbt_packages macros

The full line stores only the extras — applying full uses lean ∪ full. You can edit this file by hand if you prefer.

Repo key, bare repos, and worktrees

• The repo key is derived from the shared git common directory, so every worktree of the same clone maps to the same key. All worktrees share one saved lean/full config, while each worktree still applies its own sparse-checkout independently (sparse-checkout state is per-worktree).
• Bare repositories have no working tree, so sparse-checkout doesn't apply. sprs detects this and exits with a clear message.

License

MIT