Skip to content

Shims and shells

CacheCow 0.1.0 is published. Native CoW and process-lifecycle acceptance remain unverified; package installation does not establish native support or performance benefits.

Install and inspect

Shims are optional. Explicit ccow run remains available without them. Install the real tools first, then install CacheCow's cargo, rspack, and rsbuild shims:

ccow shim install
ccow shim list
ccow shim doctor

The shims belong in a current-user-private directory. Installation must not overwrite original tools. Reinstalling CacheCow-owned shims is idempotent. A conflicting file owned by another tool must cause an actionable error; do not remove that file without identifying its owner.

Activate the current session

ccow shell init prints activation code. Diagnostics must remain separate from that code. After reviewing the generated code, apply it in the matching shell.

Bash:

eval "$(ccow shell init bash)"

Zsh:

eval "$(ccow shell init zsh)"

For PowerShell 7, review ccow shell init powershell, then evaluate its output to activate the shims. Fish and cmd.exe-specific activation are outside the first release.

ccow shell init powershell | Out-String | Invoke-Expression

After activation, run ccow shim doctor to inspect PATH priority and the selected real executables. Shell aliases or functions can still take priority over PATH shims. Session activation alone does not configure future shells.

Persistent setup

For Bash and Zsh, the intended commands are:

ccow shell setup bash
ccow shell setup zsh

For PowerShell 7, use ccow shell setup powershell --file "$PROFILE". Use --yes for a noninteractive update after reviewing the target and proposed change. Setup creates the profile file but not its directory. A new PowerShell 7 installation can lack that directory. In that case setup stops before it asks for confirmation. Create the directory first, for example with New-Item -ItemType Directory -Force (Split-Path $PROFILE), and run setup again.

Setup must show the target file and proposed change and request confirmation when the file would change. The proposed change is only the CacheCow-owned block: added lines start with + , and the lines of a replaced block start with - . CacheCow also notes when it adds a separator line break to a file without a final newline. It never prints other lines of your shell configuration, even with --yes or --json. If nothing changes, it shows the target and a no-change notice, asks for no confirmation, and does not require --yes. Setup adds only a CacheCow-owned block and preserves unrelated content. Repeated setup is idempotent. If automatic file selection is ambiguous, choose the intended shell configuration file with --file.

For example, after choosing a Bash configuration file yourself:

ccow shell setup bash --file "./chosen-shell-config" --yes

The path is a placeholder, not a recommendation for a startup filename. Noninteractive setup requires --yes when it would change the file; it authorizes the displayed class of shell-file update, not cache replacement or deletion. Failed writes must preserve the original file.

Persistent setup applies to new shells. For the current session, use the matching shell init command above, or open a new shell. Confirm PATH order with ccow shim doctor.

Tool selection

Each invocation selects the first real executable in PATH after excluding CacheCow shims. Installation does not pin a tool path. The CacheCow shim directory in PATH does not affect cache compatibility, so a cache built with explicit ccow run and the same command through an activated shim can share a source cache. Changing PATH or a version-manager selection must affect the next invocation. CacheCow must prevent recursion while preserving rustup toolchain selection, including explicit toolchain arguments.

In the next source version, nightly Cargo newer than the 1.99.1 stable floor can also enter managed discovery. This is not available in the published 0.1.0 binary. Nightly must report both cache directories and pass the same configuration checks; unstable -Z and -C command-line options remain unsupported. Different nightly compiler builds cannot reuse each other's caches. The stable support guarantee is unchanged. Use cargo +nightly check, RUSTUP_TOOLCHAIN, directory overrides, or a toolchain file as usual.

A shim preserves the tool's arguments, working directory, stdout, stderr, and exit code. On Unix, a pass-through call delivers non-UTF-8 argument and environment bytes to the real tool unchanged. CacheCow skips PATH entries that are not valid UTF-8 when it looks for the real tool, so a tool installed only under such a directory is not found. Tool arguments must not become CacheCow options. Put CacheCow options before -- in explicit ccow run, or use saved configuration. If no real executable exists, diagnostics must explain how to restore one and return command-not-found status 127.

Managed and pass-through commands

Recognized cache-using operations, such as builds, checks, tests, and development servers, enter the same managed lifecycle as ccow run. A bare rsbuild call, or one with only options such as --port 3000, starts Rsbuild's default dev server and is managed like rsbuild dev. For Rspack and Rsbuild, a version flag (-v or --version) only prints the version when no command is given; with a command, such as rspack build --version or rsbuild -v dev, the tool runs that command, so it is managed.

Version/help requests and cache-nonmutating queries pass through without preparation, prompts, or cache locks. The next source version also passes built-in Cargo commands such as cargo check through silently when there is no Cargo.toml in the current directory or any parent and no explicit --manifest-path, -C, or -Z selection. Configurable short aliases such as cargo c and the external clippy command stay managed. Cargo then prints its own missing-project error and returns its original exit status. This behavior is not in the published 0.1.0 binary. Calls outside Git also pass through; that does not provide managed-cache support outside Git. Unknown commands and custom Cargo subcommands pass through without automatic protection. Use explicit ccow run if such a command needs cache management and its preset can be verified.

The managed built-in Cargo commands are build, check, test, bench, run, doc, rustc, rustdoc, clippy, fix, package, and publish, including their short aliases such as b, c, t, r, and d. cargo package and cargo publish write the .crate file into <target-dir>/package and, unless --no-verify is set, run a verification build into the target and build directories. Both stay managed with --no-verify, and cargo publish --dry-run stays managed too. cargo publish holds the cache lease until the upload finishes. cargo package --list (or -l) only prints the file list, so it is a query and passes through.

cargo install is not managed automatically. A cargo install --path build writes that workspace's target directory without protection, so do not run it concurrently with managed sessions. Use CCOW_BYPASS=1 only when no managed access to the same cache is running.

Managed commands need UTF-8 arguments and environment. If a managed call receives an argument or environment value that is not valid UTF-8, CacheCow exits with status 2 and names the argument position (ARG #n, where ARG #0 is the command) or the variable, without printing the value, and it does not start the tool. Use CCOW_BYPASS=1 to pass such a call through when no managed access to the same cache is running.

Shim-dispatched cargo clean waits for the relevant lock without preparing or cloning a cache. It preserves Cargo's original arguments and deletion behavior. ccow clean instead refuses an in-use cache immediately.

Same-session/same-cache nesting reuses protection without preparation. Different-cache nesting remains managed. See process ownership before running nested tools or watch servers.

Bypass and interception limits

Set CCOW_BYPASS=1 to pass through to the real tool without cache management. In Bash or Zsh, a one-command example is:

CCOW_BYPASS=1 cargo build

In PowerShell 7, set $env:CCOW_BYPASS to "1" for the intended invocation, then restore its previous value or remove it if it was previously unset. Do not leave bypass enabled unintentionally. Never run a bypassed cache writer concurrently with managed access to the same cache.

PATH shims cannot guarantee interception of shell aliases/functions, absolute executable paths, package-manager-local binaries, npm/pnpm/yarn scripts, or JavaScript API calls. First-release automatic script and node_modules/.bin integration is excluded. Use explicit ccow run and the Rspack/Rsbuild configuration integration where applicable; wrapping alone does not resolve unknown cache configuration.

Remove activation and shims

Remove persistent registration before uninstalling the CLI:

ccow shell remove bash
ccow shell remove zsh

Use only the shell you configured. For PowerShell 7, use ccow shell remove powershell --file "$PROFILE". If setup used --file, select that same file for removal. Removal shows the target and the removed CacheCow-owned block (lines start with - , plus a note when a separator line break is removed) without any other shell configuration content, requires interactive confirmation or noninteractive --yes when it removes a block (a removal that finds no block needs neither), removes only the owned block, and preserves unrelated text. Repeated removal is idempotent; failed writes preserve the original file.

Removal affects new shells. In the current session, remove the CacheCow shim directory from PATH and refresh shell command lookup, or open a new shell after persistent removal. Do not erase unrelated PATH entries.

ccow shim uninstall

Shim uninstall removes only CacheCow-owned shims. It preserves caches, settings, and shell registration blocks. If blocks remain, use ccow shell remove before removing the CLI. Recheck tool selection in a new shell.

Recovery

If an unexpected tool runs, inspect ccow shim doctor, PATH order, shell aliases/functions, and version-manager selection. Refresh the shell's cached command lookup or open a new shell after changing PATH. If a real tool is missing, restore its installation or PATH entry; repeatedly reinstalling shims does not install the tool.

If setup/removal fails, retain the original configuration file, correct its permissions or choose an unambiguous file with --file, and retry. Do not replace the whole startup file. If uninstall reports a foreign file, identify it before acting; ownership checks must preserve unrelated files.