snip-stitch

Idempotently add, update, or remove managed snippets inside shell-like text files.

Installers love to append lines to your shell profile. Uninstallers… don’t.

snip-stitch fixes this by wrapping each snippet in marker lines, so future runs can find, update, or cleanly remove exactly that section – and leave everything else alone.

# ---8<- nvm -- managed section, avoid editing
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
# -8<--- nvm --

No dependencies. Idempotent by design. One file, one job.

Installation

Run directly (no install required):

uvx snip-stitch --help

It can also be pip-installed, or ran ad-hoc (it uses std lib only).

Commands

Every invocation follows the same shape:

snip-stitch [options] <command> <tag> <target> [content]

• tag – identifies the managed section (3-32 lowercase chars: [a-z][a-z0-9._-]{2,31})

• target – the file to modify (e.g. ~/.bashrc, ~/.ssh/config)

• content – the snippet source (meaning depends on the command)

snip-stitch text rustup ~/.profile \
  '[ -f "$HOME/.cargo/env" ] && . "$HOME/.cargo/env"'

snip-stitch file sdkman ~/.bashrc sdkman-init.sh

snip-stitch file personal-github ~/.ssh/config personal-git.config

snip-stitch remove sdkman ~/.bashrc

Options

Options go before the command:

snip-stitch -n --force text mytag ~/.bashrc 'echo hello'

How it works

Given this command:

snip-stitch file nvm ~/.zshrc nvm-init.sh

The target file will contain:

# ---8<- nvm -- managed section, avoid editing
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
# -8<--- nvm --

Run it again with the same content? Nothing happens – the file is not rewritten. Change the content? Only the managed section is updated in place. Use remove? The markers and everything between them are deleted, the rest stays put.

Use cases

Shell installers – tools like nvm, sdkman, rustup, and Homebrew need to inject initialization lines into shell profiles. Instead of grep ... || echo ... >> ~/.zshrc (and hoping for the best at uninstall time), use snip-stitch for clean ownership.

Dotfile managers – keep your ~/.bashrc, ~/.zprofile, or ~/.ssh/config tidy by giving each concern its own tagged section.

CI/CD and automation – any setup script that needs to own a section of a config file without clobbering the rest of it.

Package managers – npm, Homebrew, and similar tools that modify shell config during install can use the same tag at uninstall time to cleanly remove their section.

Guarantees

• Same input produces same file contents (idempotent)

• Unchanged snippet content does not rewrite the file

• Removal leaves surrounding content intact

• Zero runtime dependencies