NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules
Go modules, #1983 by repository stars
Latest stable
v0.55.1
Last release 18 days ago
04 Nov 2026
Ships fairly regularly
a new release about every 2 weeks
Some releases are documented
notes for 19 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
6 years old
203 releases · first in 2021
Drag across the ruler to compare, or tap a release to open it.
Nothing published for this version
fix: keep stubs when linking would change a binary's env
fix: keep stubs when linking would change a binary's env (#636)
Since v0.54.0, activated shells run package binaries straight from the
link farm, without their `bin/` stubs. A stub applies its own package's
environment variables last, so they take precedence. A linked binary
only sees the shell's merged environment, where the last package to set
a variable wins. This broke squareup/cash-server#142281: several tool
packages each set `CASH_SERVER_TOOLS_HOME` to their own root, so all but
one launched with another package's root and failed to find their JAR.
The link farm should only bypass a stub when doing so cannot change what
the binary sees. This PR adds three conditions:
- **Overridden variables.** A package is linked only if its stub would
run it with the same environment the shell already has. Otherwise it
keeps its stub. Differences only in the order of `:`-separated lists
such as `PATH` are ignored, because stubs move their package's entries
to the front but never drop any. Without this, any package that adds to
`PATH` would lose its link whenever a later package also adds to `PATH`.
- **Requirements that are not unpacked.** A stub unpacks everything its
package declares in `requires` before running it. A linked binary may
reach those packages through variables such as `JAVA_HOME` rather than
through their stubs. For example, after a pull bumps the JDK, a linked
Maven would find `JAVA_HOME` pointing at a directory that does not exist
yet. Such packages now keep their stubs until the next activation after
their requirements are unpacked.
- **Children of unactivated stubs.** A stub run outside an activated
shell adds the link farm to its binary's `PATH`. If that stub changes
any variable relative to the activated environment, through overridden
variables, runtime dependencies or a bundled Hermit environment, it now
leaves the link farm off. Its children then go through their own stubs
and get their own values. In activated shells this already happened,
because stubs put `bin/` back ahead of the link farm.
Link farms are still never modified once created. A package that becomes
unsafe to link is simply left out of the next farm.
New integration tests cover each condition, and each fails without its
fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Your coding agent can read these notes before it upgrades. Set up the MCP server →
style: simplify requirement match condition
style: simplify requirement match condition
Staticcheck's QF1001 rejected the negated disjunction, failing lint.
Naming the match condition keeps the check readable without changing
behaviour.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Nothing published for this version
Nothing published for this version
fix: use the link farm when running stubs unactivated
fix: use the link farm when running stubs unactivated (#634)
Running `./bin/<tool>` without activating the environment, as git hooks,
IDEs and agents often do, is far slower than the same command in an
activated shell. In a large repository whose `just fmt` recipe calls
many Hermit-managed tools, `./bin/just fmt` took about 22s unactivated
against 6.6s activated (18.5s against 4.4s on a quieter machine).
The tool's children got `bin/` on `PATH` but not the link farm, so every
tool they ran went back through a stub. Those stubs also took the slow
unactivated path, because `ACTIVE_HERMIT` is unset. On that path the
stub resolves every installed package's manifest again. Per call,
measured with `bin/bash -c true` in that repository:
| Path | Time |
|---|---|
| Unactivated stub | 0.28s |
| Activated stub | 0.05s |
| Link farm | 0.009s |
One unactivated `./bin/just fmt` started 59 Hermit processes. 45 were
`bash`, which that environment manages with Hermit and `just` uses to
run recipe lines. Most of the extra time is the repeated environment
reload, not process startup: activated shells before 0.54.0, which had
no link farm, were already close to the current activated time.
Unactivated `hermit exec` now does what activation does: it checks
linked channel packages for updates, creates the link farm, and puts it
on `PATH` directly ahead of `bin/`. Activation and `exec` share this
through a new `createLinkFarm` helper. Children then run other packages
directly, as in an activated shell. The child environment differs from
before only by the farm on `PATH` and `HERMIT_LINK_FARM`, and the farm
is the same directory activation uses. Activated execution is unchanged.
Results for `./bin/just fmt` in that repository, three runs each, on a
loaded machine:
| Build | Not activated | Activated |
|---|---|---|
| Before | 21.9s, 21.2s, 22.7s | 6.6s, 6.5s, 6.6s |
| After | 6.2s, 6.0s, 6.1s | 6.6s, 7.5s, 6.8s |
Hermit processes per unactivated run went from 59 to 2.
Known gap: a child that calls a stub by an explicit path, such as `xargs
bin/go`, still pays the full unactivated reload (about 0.28s against
0.05s activated). Fixing that needs a marker telling nested stubs the
environment is already loaded, without making child shells think Hermit
is activated, so it is left out of this change.
Tests: two new integration tests, run under bash and zsh, cover a child
of an unactivated stub running another package through the farm with its
environment variables set, and a due channel update being picked up when
the child runs a linked channel package. The first fails on the previous
code; the second fails if the update check is removed from `exec`.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
feat: run activated binaries through direct links
feat: run activated binaries through direct links (#630)
Every command in an activated Hermit shell goes through a `bin/` stub,
which starts a Hermit process to resolve the package, check for updates,
and set up the environment before running the real binary. That costs
roughly 150ms per invocation (measured with `just --version`:
~0.15–0.18s through the stub versus under 0.01s for the binary itself),
which adds up quickly in builds and scripts that call tools repeatedly.
This change makes activation build a per-environment directory of
symlinks pointing straight at unpacked package binaries, and puts it on
`PATH` directly ahead of `bin/`. Anything without a link falls through
to its stub, so behaviour is unchanged for those binaries.
- **Location.**
`<state>/environments/<env-name>-<env-path-hash>/<links-hash>`. The
directory name is a hash of the links themselves, so packages whose
contents change under the same reference (channels) still get a new
directory.
- **Only safe packages are linked.** Packages keep their stubs when the
stub does work at execution time: packages that are not unpacked yet
(the stub downloads them on first use), packages with `on exec`
triggers, runtime dependencies, or a bundled Hermit environment, and all
packages from inherited parent environments (their stubs apply the
parent's own variables, which the child's shell variables may override).
- **Link directories never change once created.** A shell's `PATH` entry
therefore always matches the package set its environment variables came
from. A package change creates a new directory, and the existing prompt
hooks switch the shell over at the next prompt.
- **Old directories are kept until `hermit clean`.** Deleting them on
package changes would break running shells and processes: bash caches
resolved command paths and fails with "No such file or directory" rather
than searching `PATH` again. `hermit clean --bin` removes the current
environment's directories, and `--packages`/`--transient` remove all of
them.
- **Side effects stay in activation.** `hermit activate` and `hermit env
--activate` create the directory. `hermit env --ops` only computes its
path. Activation also checks linked channel packages for updates,
because their stubs no longer run to do it.
- **zsh first-prompt hook.** `update_hermit_path` now includes the new
`HERMIT_LINK_FARM` entry, so it stays directly ahead of `bin/`.
Known gaps:
- A package unpacked by its stub's first run is not linked until the
shell re-activates, which happens on a new shell or when `bin/` changes.
- Commands on the same line as a package change, such as `hermit upgrade
foo && foo`, still use the previous links until the next prompt. That
matches how other packages' environment variables already behave.
- When linked channel packages are due for an update check, activation
now makes that network request.
Tests: unit tests in `linkfarm_test.go` cover which packages get linked,
that `EnvOps` has no side effects, that an upgrade leaves the old
directory unchanged, and both clean options. New integration tests, run
under bash and zsh, cover:
- running through the link directory, including upgrade, deactivation
and clean
- packages that are not unpacked falling back to stubs
- `on exec` trigger packages keeping their stubs
- channel updates being picked up at activation
The two zsh `PATH`-order tests were updated for the new entry. Fish is
not covered locally.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Nothing published for this version
Run the full activation lifecycle in 'hermit env --activate'
Run the full activation lifecycle in 'hermit env --activate' (#601)
Context: #597 — composing agent-skills-style content packages from
existing Hermit primitives.
`hermit activate` installs `install-on-activate` packages and runs `on
activate` triggers before emitting environment variables, but `hermit
env --activate` — used by the shell hooks in
`activate.tmpl.sh`/`activate.tmpl.fish` when the environment changes,
and commonly by CI via `eval $(hermit env --activate)` — only computed
and applied the envar operations. The two activation paths could
therefore drift: packages and triggers were skipped entirely on the `env
--activate` path.
This extracts the shared lifecycle into `Env.Activate` and uses it from
both paths. Trigger messages are printed to stderr on the `env
--activate` path since stdout is reserved for shell commands.
An integration test starts with installed stubs and an empty package
cache, verifies that env --activate unpacks the package and runs its
trigger, checks emitted shell commands and stderr messages, and verifies
that env --ops has no activation side effects. All cases run through the
existing `./integration` harness against a freshly built CLI in Bash and
Zsh. The new regression cases were also checked against current master
without this PR’s implementation and failed at the behavior this PR
fixes.
Validation: `bin/go test ./...`, `bin/go test -count=1 -tags integration
./integration -run '^TestIntegration$'`, and `bin/golangci-lint run`.
The September 18 refresh also passed the full Go integration suite,
including Fish, plus shell lint.
Tracking: AGNTOPS-430.
September 18 refresh: merged current master without rewriting history.
Resolved overlapping lifecycle and channel-freshness test insertions by
retaining both. Full unit tests, full Go integration tests (Bash, Zsh,
and the Fish regression), golangci-lint, and shell lint passed at
joahg@7011a77.
Co-authored-by: Amp <amp@ampcode.com>
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
fix: re-validate archive paths after applying strip
fix: re-validate archive paths after applying strip (#575)
Archive path computation validated the entry path before applying
`strip`, then joined the remainder to the destination without
re-checking, so the result could fall outside the destination directory.
This applies to all multi-file extractors (tar, zip, 7z, rpm) via the
shared path helper.
Re-validates the path after `strip`, and tightens `sanitizeExtractPath`
to require a path separator after the destination so a sibling sharing
its name as a prefix is not accepted.
Adds regression tests.
Co-authored-by: Amp <amp@ampcode.com>
fix(zsh): stop ../-path completion stalling and double chpwd registra…
fix(zsh): stop ../-path completion stalling and double chpwd registra…
…tion (#574)
Two zsh shell-hook issues that compound on machines where Hermit hooks
are evaluated more than once (e.g. a corporate-managed /etc/zshrc plus a
per-user ~/.zshrc install).
1. ../-path tab completion paused ~1s. zsh's _cd completer canonicalises
a `../` prefix by running `cd` in a $(...) subshell, which fires
chpwd_functions -> change_hermit_env and pays for a full Hermit env
switch (validate + source activate-hermit) that is then discarded. Guard
change_hermit_env with `${compstate+_}`, which zsh sets only while its
completion system is running and which is inherited into the _cd
subshell. Interactive `cd`, `(cd ... && cmd)` and `$(cd ... && cmd)` all
leave compstate unset and are unaffected.
2. change_hermit_env was registered twice in chpwd_functions, doubling
the
cost of every real cd. The hook block is evaluated once per startup file
that sources it (system-wide + per-user), and the old
`chpwd_functions+=(change_hermit_env)` is not idempotent. Register via
add-zsh-hook instead, which checks membership before appending. Note a
plain `typeset -gU chpwd_functions` does not help: += bypasses the
unique
flag in zsh 5.9.
Nothing published for this version
fix: deadlock between Task.Size and redrawProgress under parallel ins…
fix: deadlock between Task.Size and redrawProgress under parallel ins…
…tall (#564)
## Summary
#558 parallelised `hermit install`, which lets many goroutines drive
per-package download progress concurrently. `cache/http.go` calls
`task.Size(total)` followed by `task.Add(n)` for each chunk received;
with a single active task the cycle below could never close, but with
many it closes in two hops.
Lock orderings:
```
Task.Size: task.lock -> ui.lock (via UI.swapSize)
UI.redrawProgress: ui.lock -> task_i.lock (via liveOperations / op.status)
```
Goroutine A inside `task_A.Size` holds `task_A.lock` waiting on
`ui.lock`. Goroutine B, having just returned from its own `task.Add`'s
critical section, enters `redrawProgress` holding `ui.lock` and iterates
operations waiting on `task_A.lock`. Deadlock is silent because the UI
itself is blocked, so no progress output is produced before the job is
killed — matches the wild symptom of `hermit install` stalling with zero
output after `v0.52.0` on CI jobs that install many packages at once.
## Fix
Release `task.lock` in `Task.Size` before calling `UI.swapSize`. The
`oldSize → newSize` delta passed to `swapSize` is additive and
commutative, so doing the swap outside the task's critical section loses
nothing.
## Test
`ui/task_test.go::TestConcurrentTaskSizeAndAddNoDeadlock` fans out
goroutines each interleaving `Size`/`Add` on their own task (mirroring
`cache/http.go`'s download loop).
- Pre-fix: hangs for the test's 10s self-deadline and fails with an
annotated goroutine dump showing the expected `ui.lock` ↔ `task.lock`
cycle.
- Post-fix: completes in ~0s.
Passes `go test -race ./ui/` and existing `go test ./app/`.
---------
Co-authored-by: Josh Friend <jfriend@block.xyz>
feat: parrallellize hermit install downloads
feat: parrallellize hermit install downloads (#558)
Download package archives concurrently during install using errgroup,
with concurrency defaulting to `runtime.NumCPU()`. A new `-j` flag
allows overriding the parallelism level.
Only the download phase is parallelised. Extraction and linking remain
serial because unpack triggers may execute binaries from dependency
packages.
Both install paths benefit:
- **No-args** (re-install existing): parallel download, then serial
CacheAndUnpack.
- **With packages**: parallel download, then serial install/link loop.
A new `State.Download` method is added to expose download-only
functionality, separate from `CacheAndUnpack`.
Co-authored-by: Amp <amp@ampcode.com>
Guard zsh prompt prefix updates
Guard zsh prompt prefix updates (#555)
## Summary
- only capture `_HERMIT_OLD_PS1` and prepend the Hermit prompt once in
`update_hermit_ps1`
- avoid re-prepending the Hermit prompt on later precmd runs once the
original prompt has been recorded
## Testing
- `go test ./...`
Co-authored-by: Amp <amp@ampcode.com>
fix: sync sources on ListInstalled resolution failure
fix: sync sources on ListInstalled resolution failure (#552)
Co-authored-by: Amp <amp@ampcode.com>
fix: move download outside global lock in CacheAndUnpack
fix: move download outside global lock in CacheAndUnpack (#551)
## Summary
- Move the network download step outside the global file lock in
`CacheAndUnpack()` so slow downloads no longer block other hermit
processes
- Only the fast local extract + link operations remain under the lock,
preventing "timed out acquiring lock" errors in CI
- Consistent with `CacheAndDigest()` which already downloads outside any
lock
This is safe because cache paths are content-addressed (SHA256-based)
and the cache layer uses temp files + atomic `os.Rename` (see
`cache/http.go` `downloadHTTP()`).
per
[ADR-0098](https://docs.google.com/document/d/1CxeLv3gArVytK8pJLw-MMA3t6j4OqE65rK1Kbs6RcrM/edit)
and the [Workspace
Contract](https://docs.google.com/document/d/18Susz4iTeWoINhchvIFmSen_fHU657hAurvNlZFliuY/edit).
## Test plan
- [x] \`go build ./...\` compiles successfully
- [x] \`go test ./state/... ./cache/...\` passes
- [ ] Verify in CI that parallel hermit installs no longer produce lock
timeout errors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Nothing published for this version
Quote activation exports and paths for space-containing roots by @robmaceachern in https://github.com/cashapp/hermit/pull/545
Full Changelog: https://github.com/cashapp/hermit/compare/v0.49.3...v0.49.4
cache: do not print spurious '%s' format verb by @marco-m in https://github.com/cashapp/hermit/pull/544
Full Changelog: https://github.com/cashapp/hermit/compare/v0.49.2...v0.49.3
Nothing published for this version
Nothing published for this version
Nothing published for this version
Revert "Use chpwd_functions for change_hermit_env instead of precmd_functions" by @sw-square in https://github.com/cashapp/hermit/pull/536
Full Changelog: https://github.com/cashapp/hermit/compare/v0.48.0...v0.48.1
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
fix: use HERMIT_GITHUB_TOKEN for git operations during exec by @steved in https://github.com/cashapp/hermit/pull/498
hermit bundle <dir> [<pkg> ...] command by @alecthomas in https://github.com/cashapp/hermit/pull/505Full Changelog: https://github.com/cashapp/hermit/compare/v0.44.12...v0.45.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
chore(deps): update all non-major dependencies by @renovate in https://github.com/cashapp/hermit/pull/469
Full Changelog: https://github.com/cashapp/hermit/compare/v0.44.5...v0.44.6
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
perf: speedup hermit exec by @nickajacks1 in https://github.com/cashapp/hermit/pull/431
Full Changelog: https://github.com/cashapp/hermit/compare/v0.43.0...v0.44.0
Full Changelog: https://github.com/cashapp/hermit/compare/v0.42.1...v0.43.0
Full Changelog: https://github.com/cashapp/hermit/compare/v0.42.1...v0.43.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.