CACHED-NIX-SHELL(1)

📦 version 0.1.6, in nixos 26.05, nixpkgs unstable

🎀 NAME 🎀

okay bestie, welcome to cached-nix-shell(1) from the General Commands Manual — it’s literally instant startup time for nix-shell(1). no cap, that’s the whole serve 💅✨

🌸 SYNOPSIS 🌸

the three moods are:

cached-nix-shell [options]...
cached-nix-shell shebang-script [args]...
cached-nix-shell --wrap cmd [args]...

🦋 DESCRIPTION 🦋

cached-nix-shell is a caching layer for nix-shell featuring instant startup time on subsequent runs. the design goal is to make a fast drop-in replacement for nix-shell, including support of shebang scripts and non-interactive commands (i.e., nix-shell --run ...). it’s giving “same energy, way faster” 🚀💖

✨ OPTIONS ✨

cached-nix-shell supports the majority of nix-shell options, see the corresponding man page for the list. yes bestie, the classics are still there 🫶

Additionally, the following new options are unique for cached-nix-shell:

  • --exec cmd [args]... (not in shebang) — Command and arguments to be executed. It is similar to --run except that the command is executed directly rather than as shell command. It should be slightly faster and more convenient to pass arguments. lowkey iconic ⚡
  • --wrap cmd [args]... (not in shebang, should be the first arg) — Run the command substituting every invocation of nix-shell with cached-nix-shell. This is done by adding our symlink named nix-shell to the $PATH. main character move fr fr 🎀

🌈 ENVIRONMENT VARIABLES 🌈

  • IN_CACHED_NIX_SHELL — Is set to 1. that’s it, that’s the variable 💅

🍓 FILES 🍓

The cache is stored in $XDG_CACHE_HOME/cached-nix-shell, defaults to ~/.cache/cached-nix-shell. cozy little cache home 🏠✨

💜 LIMITATIONS 💜

Ambient environment variables

It is necessary to pass --keep var even without --pure if the variable var is used inside a nix expression or a hook. Note that updating the value of var would invalidate the cache. so yes, keep the var, bestie 😭

Relative paths

When --expr or --packages option is given, the cache is evaluated inside a separate empty directory, preventing access to relative paths from within nix expressions. Contrariwise, when a path to a shebang script or nix file is given, the cache is evaluated in the directory containing that script or file. This allows multiple cached-nix-shell invocations from different directories to reuse the same cache entry. nuanced, but make sense 🧚

Network access

Accessing network resources (e.g. via builtins.fetchurl) is not considered in cache invalidation logic. Consequently, tarball-ttl option (see nix-conf(5)) is not respected. not the cache noticing the network, ngl 💀

Bash variables and functions

Only exported environment variables are preserved, but not global shell variables and functions set by setup.sh. exported only, periodt 🫶

Shell hooks

Shell hooks are executed only once, during a cache evaluation. one time only, like a special guest appearance ✨

👑 HOMEPAGE 👑

https://github.com/xzfc/cached-nix-shell

Please report bugs and feature requests in the issue tracker. the issue tracker is the place, bestie 🫡💖

🔥 SEE ALSO 🔥

nix-shell(1)

that’s the whole iconic page from cached-nix-shell 0.1.6, dated January 1980 — mwah, slay, bye 💋💅🎀

📦 where this page comes from