From 3368c6bc66c820db185fca13911ca1ecbba6f4d2 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Wed, 20 May 2026 16:20:03 -0700 Subject: [PATCH 1/3] docs(deactivate): add deactivation concept section and nav entry - Add a "Deactivating environments" section to concepts/activation.mdx covering reversibility, profile.deactivate scripts, layered envs, and the subshell shorthand for `exit`. - Add a one-line mention next to the existing `exit` / `Ctrl-D` callout in the Subshell section. - Register the new man/flox-deactivate page in docs.json under the Environments group of the CLI reference nav. Co-Authored-By: Claude Opus 4.7 (1M context) --- concepts/activation.mdx | 27 +++++++++++++++++++++++++++ docs.json | 1 + 2 files changed, 28 insertions(+) diff --git a/concepts/activation.mdx b/concepts/activation.mdx index 4a75600..41515c2 100644 --- a/concepts/activation.mdx +++ b/concepts/activation.mdx @@ -75,6 +75,8 @@ When you activate this way your existing shell is paused and you're put into a new one configured by Flox. Once this shell exits (via `exit` or `Ctrl-D`, for example), your original shell is resumed and your are put back into it. +Running [`flox deactivate`](/man/flox-deactivate) inside the subshell has the +same effect. ```mermaid %%{init: {'theme':'base','themeVariables':{'primaryColor':'#e8eef6','primaryBorderColor':'#7d96b8','primaryTextColor':'#1f2937','lineColor':'#7d96b8','noteBkgColor':'#e8eef6','noteTextColor':'#1f2937','noteBorderColor':'#7d96b8','actorBkg':'#e8eef6','actorBorder':'#7d96b8','actorTextColor':'#1f2937','actorLineColor':'#7d96b8','signalColor':'#1f2937','signalTextColor':'#1f2937','labelBoxBkgColor':'#e8eef6','labelBoxBorderColor':'#7d96b8','labelTextColor':'#1f2937','loopTextColor':'#1f2937','sequenceNumberColor':'#1f2937'},'sequence':{'mirrorActors':false}}}%% @@ -358,6 +360,31 @@ If you edit your manifest and activate in a new shell, the whole activation process is run again and subsequent activations will attach to this new version of the environment. +## Deactivating environments + +Activation is reversible. +[`flox deactivate`](/man/flox-deactivate) tears down the most recently +activated environment in your shell, +restoring the environment variables and shell customizations that activation +changed. +If the manifest defines a `profile.deactivate.${shell}` script, +it is sourced first so the environment can undo any modifications it made +during activation. + +When several environments are layered, +`flox deactivate` peels off the innermost (most recently activated) one. +Running it again deactivates the next layer in, and so on. + +The same command works for all activation modes: + +- In a subshell (interactive `flox activate`), `flox deactivate` is shorthand + for `exit` — it leaves the subshell and restores the parent shell's + previously active environments. +- For in-place activations, it reverts the activation diff in the current + shell. + +See [`flox deactivate`](/man/flox-deactivate) for the full command reference. + ## Development vs. runtime mode See the [`options.activate.mode`](/man/manifest.toml#options) option in the manifest. diff --git a/docs.json b/docs.json index 746f79a..2bae27c 100644 --- a/docs.json +++ b/docs.json @@ -164,6 +164,7 @@ "group": "Environments", "pages": [ "man/flox-activate", + "man/flox-deactivate", "man/flox-edit", "man/flox-delete", "man/flox-envs" From dd74d91fbbfc22578ee5377740ce7a8f9a235f84 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Wed, 20 May 2026 16:20:03 -0700 Subject: [PATCH 2/3] docs(deactivate): add flox-deactivate man page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add man/flox-deactivate.mdx mirroring the pandoc source at cli/flox/doc/flox-deactivate.md in flox/flox. - Add a DESCRIPTION note and SEE ALSO entry in man/flox-activate.mdx pointing at the new page. Scoped to the initial behavior — only deactivates the innermost environment. Layered/non-innermost selection (-d/-r) is deferred. These pages are duplicated from flox/flox today (the two repos hold parallel hand-maintained copies). This commit is kept last so it can be cleanly reverted if we later land automation that pulls man pages directly from flox/flox into this repo. Co-Authored-By: Claude Opus 4.7 (1M context) --- man/flox-activate.mdx | 5 +++ man/flox-deactivate.mdx | 82 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) create mode 100644 man/flox-deactivate.mdx diff --git a/man/flox-activate.mdx b/man/flox-activate.mdx index 7430fa1..2100ea9 100644 --- a/man/flox-activate.mdx +++ b/man/flox-activate.mdx @@ -67,6 +67,10 @@ for the environment in which the shell hook was defined. See [`manifest.toml(5)`](/man/manifest.toml) for more details on shell hooks. +To reverse activation, run +[`flox deactivate`](/man/flox-deactivate). Inside a `flox activate` +subshell, `flox deactivate` is equivalent to `exit`. + ## OPTIONS ### Activate Options @@ -239,5 +243,6 @@ eval "$(flox activate)" ## SEE ALSO +[`flox-deactivate(1)`](/man/flox-deactivate), [`flox-push(1)`](/man/flox-push), [`flox-pull(1)`](/man/flox-pull), [`flox-edit(1)`](/man/flox-edit), [`flox-delete(1)`](/man/flox-delete) diff --git a/man/flox-deactivate.mdx b/man/flox-deactivate.mdx new file mode 100644 index 0000000..83f3db0 --- /dev/null +++ b/man/flox-deactivate.mdx @@ -0,0 +1,82 @@ +--- +title: "flox deactivate" +--- + +## NAME + +flox-deactivate - deactivate an environment + +## SYNOPSIS + +```text +flox [] deactivate +``` + +## DESCRIPTION + +Deactivates an active Flox environment in the current shell, reversing +the changes made by [`flox activate`](/man/flox-activate). + +`flox deactivate` deactivates the innermost (most recently activated) +environment. When multiple environments are layered, running +`flox deactivate` repeatedly deactivates them one at a time, innermost +first. + +Deactivation performs the following steps: + +- Runs the `profile.deactivate.${shell}` script from the environment's + manifest, if defined, allowing the environment to undo modifications + it made during activation. +- Restores environment variables and shell state to their pre-activation + values. Only variables that activation set are reverted; variables that + activation did not touch are left alone. +- Reverts shell customizations: the prompt is restored from its saved + value (or recomputed from the remaining active environments if any + remain), command hashing is re-enabled, and any zsh `FPATH` entries, + completion caches, and precmd hooks installed by activation are + removed. +- Detaches the current shell from the activation. When the last shell + detaches, services started by the activation are stopped. + +### Interactive subshells + +Inside a subshell created by an interactive `flox activate`, +`flox deactivate` is equivalent to `exit`: it exits the subshell and +returns to the parent shell, where any previously active environments +are restored automatically. + +## OPTIONS + +### General Options + +`-h`, `--help` +: Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +: Increase logging verbosity. + Invoke multiple times for increasing detail. + +`-q`, `--quiet` +: Silence logs except for errors. + +## EXAMPLES + +Deactivate the innermost active environment: + +```bash +flox deactivate +``` + +Exit a `flox activate` subshell (equivalent to running `exit`): + +```console +flox [myenv] $ flox deactivate +$ +``` + +## SEE ALSO + +[`flox-activate(1)`](/man/flox-activate) From 10ac46ed26e3984454ef3b99e6d2ccb42d6fc1e6 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Wed, 20 May 2026 16:23:00 -0700 Subject: [PATCH 3/3] Apply suggestion from @djsauble --- concepts/activation.mdx | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/concepts/activation.mdx b/concepts/activation.mdx index 41515c2..1f0113c 100644 --- a/concepts/activation.mdx +++ b/concepts/activation.mdx @@ -367,22 +367,6 @@ Activation is reversible. activated environment in your shell, restoring the environment variables and shell customizations that activation changed. -If the manifest defines a `profile.deactivate.${shell}` script, -it is sourced first so the environment can undo any modifications it made -during activation. - -When several environments are layered, -`flox deactivate` peels off the innermost (most recently activated) one. -Running it again deactivates the next layer in, and so on. - -The same command works for all activation modes: - -- In a subshell (interactive `flox activate`), `flox deactivate` is shorthand - for `exit` — it leaves the subshell and restores the parent shell's - previously active environments. -- For in-place activations, it reverts the activation diff in the current - shell. - See [`flox deactivate`](/man/flox-deactivate) for the full command reference. ## Development vs. runtime mode