Merge branch 'main' into docs/add-skills-plugin-instructions

Author: djsauble

.flox/env/manifest.lock

@@ -1,14 +1,19 @@
-version = 1
+schema-version = "1.11.0"
 
 [install]
 coreutils.pkg-path = "coreutils"
+coreutils.outputs = "all"
 findutils.pkg-path = "findutils"
+findutils.outputs = "all"
 gnutar.pkg-path = "gnutar"
+gnutar.outputs = "all"
 pandoc.pkg-path = "pandoc"
 poetry.pkg-path = "poetry"
+poetry.outputs = "all"
 python.pkg-path = "python311"
 pngquant.pkg-path = "pngquant"
 gnused.pkg-path = "gnused"
+gnused.outputs = "all"
 d2.pkg-path = "d2"
 
 lychee.pkg-path = "lychee"
@@ -17,6 +22,7 @@ lychee.version = ">=0.23"
 markdownlint-cli2.pkg-path = "markdownlint-cli2"
 markdownlint-cli2.pkg-group = "lint"
 curl.pkg-path = "curl"
+curl.outputs = "all"
 
 [hook]
 on-activate = '''
@@ -35,9 +41,7 @@ echo "1. 👉 Python environment activated"
 # 
 # Set the version of Flox to the latest stable version
 #
-if [ ! -f "FLOX_VERSION" ]; then
-  curl -s --fail https://downloads.flox.dev/by-env/stable/LATEST_VERSION 2>/dev/null > FLOX_VERSION
-fi
+curl -s --fail https://downloads.flox.dev/by-env/stable/LATEST_VERSION 2>/dev/null > FLOX_VERSION
 export FLOX_VERSION=$(cat FLOX_VERSION | xargs)
 echo "2. 👉 FLOX_VERSION set to $FLOX_VERSION"
 

.flox/env/manifest.toml

@@ -30,7 +30,8 @@ runs:
   using: "composite"
   steps:
     - name: "Setup Tailscale"
-      uses: "tailscale/github-action@v4"
+      uses: tailscale/github-action@306e68a486fd2350f2bfc3b19fcd143891a4a2d8 # v4
+
       if: ${{ inputs.TAILSCALE_AUTH_KEY }}
       with:
         oauth-secret: "${{ inputs.TAILSCALE_AUTH_KEY }}"
@@ -39,10 +40,12 @@ runs:
         use-cache: true
 
     - name: "Install newer Nix"
-      uses: "cachix/install-nix-action@v24"
+      uses: cachix/install-nix-action@96951a368ba55167b55f1c916f7d416bac6505fe # v31.10.3
+
 
     - name: "Configure Nix"
-      uses: "flox/configure-nix-action@main"
+      uses: flox/configure-nix-action@1ee58d63463cb1870ab73d9df0acfd9d8ba671f8 # main
+
       with:
         github-access-token:    "${{ inputs.GITHUB_ACCESS_TOKEN }}"
         substituter:            "${{ inputs.SUBSTITUTER }}"

.github/actions/common-setup/action.yml

@@ -26,3 +26,9 @@ updates:
     all:
       patterns:
         - "*"
+
+
+- package-ecosystem: "github-actions"
+  directory: "/.github/actions/common-setup"
+  schedule:
+    interval: "weekly"

.github/dependabot.yml

@@ -14,7 +14,8 @@ jobs:
       issues: write
     steps:
     - name: Add label automatically to new issues and PRs
-      uses: actions-ecosystem/action-add-labels@v1
+      uses: actions-ecosystem/action-add-labels@18f1af5e3544586314bbe15c0273249c770b2daf # v1
+
       with:
         github_token: "${{ secrets.GITHUB_TOKEN }}"
         labels: "documentation"

.github/workflows/auto-label.yml

@@ -8,6 +8,7 @@ on:
       - "preview"
       - "k8s-docs"
   pull_request:
+  merge_group:
 
 permissions:
   contents: "write"
@@ -31,15 +32,18 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v6"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
         with:
           fetch-depth: 0
 
       - name: "Install Flox"
-        uses: "flox/install-flox-action@main"
+        uses: flox/install-flox-action@c94e7e1ab56ae14fe98bae4fd84384fd135f0c2a # main
+
 
       - name: "Build"
-        uses: "flox/activate-action@main"
+        uses: flox/activate-action@6ab4a3d38cfd06f31910d0a5fe7e57ffa76ad750 # main
+
         with:
           command: |
             mkdocs build
@@ -49,19 +53,22 @@ jobs:
             cp netlify.toml ./public/
 
       - name: "Check markdown lint"
-        uses: "flox/activate-action@main"
+        uses: flox/activate-action@6ab4a3d38cfd06f31910d0a5fe7e57ffa76ad750 # main
+
         with:
           command: "markdownlint-cli2"
 
       - name: "Check external links"
         if: ${{ github.event_name == 'pull_request' }}
-        uses: "flox/activate-action@main"
+        uses: flox/activate-action@6ab4a3d38cfd06f31910d0a5fe7e57ffa76ad750 # main
+
         with:
           command: "./check_links.sh"
 
       - name: "Publish to Netlify"
         if: ${{ github.repository_owner == 'flox' }}
-        uses: "nwtgck/actions-netlify@v3.0"
+        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0
+
         env:
           NETLIFY_AUTH_TOKEN: "${{ secrets.MANAGED_NETLIFY_TOKEN }}"
           NETLIFY_SITE_ID:    "${{    vars.MANAGED_NETLIFY_FLOXDOCS_ID }}"

.github/workflows/ci.yml

@@ -17,16 +17,19 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v6"
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
 
       - name: "Install flox"
-        uses: "flox/install-flox-action@main"
+        uses: flox/install-flox-action@c94e7e1ab56ae14fe98bae4fd84384fd135f0c2a # main
+
 
       - name: "Run upgrade"
         run: "flox -vvv upgrade"
 
       - name: "Create Pull Request"
-        uses: "peter-evans/create-pull-request@v8"
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8
+
         with:
           token: "${{ secrets.MANAGED_FLOXBOT_GITHUB_ACCESS_TOKEN_REPO_SCOPE }}"
           add-paths: ".flox"

.github/workflows/update.yml

@@ -6,10 +6,10 @@ Live at: [flox.dev/docs](https://flox.dev/docs).
 
 ```
 $ flox activate
-✅ You are now using the environment 'floxdocs'.
+✔ You are now using the environment 'floxdocs'.
 
 λ (floxdocs) $ flox services start mkdocs
-✅ Service 'mkdocs' started.
+✔ Service 'mkdocs' started.
 
 ```
 Once mkdocs service started you can preview the documentation at

README.md

@@ -14,8 +14,7 @@ it stands to reason that _how you use them_ is also an important part of Flox.
 
 There are four different ways to use an environment,
 and two different modes that an environment can be activated in.
-At the end of the day, though, it all boils down to properly configuring a
-shell.
+Regardless of the method, activation works by configuring a shell.
 The `hook` and `profile` scripts specified in your manifest are run as part of
 configuring that shell.
 Understanding when and why they're run will help you take full advantage
@@ -30,9 +29,15 @@ Flox configures a shell,
 making all of the packages and environment variables specified in your
 manifest available, as mentioned above.
 
-The most basic way to activate an environment is simply by calling
+Activation doesn't always mean creating a new shell.
+Depending on how you invoke `flox activate`,
+Flox may start a subshell, configure your current shell in-place,
+or directly exec a command without an intermediate shell at all.
+The [four methods](#four-different-ways-to-activate) are described below.
+
+The most common way to activate an environment is simply by calling
 `flox activate`,
-which puts you into a subshell with everything configured:
+which starts a new subshell with everything configured:
 
 ```{ .console .no-copy }
 $ flox activate
@@ -54,6 +59,15 @@ environment rather than from elsewhere on your system.
 ## Four different ways to activate
 
 We mentioned above that there are four different ways to use an environment.
+Each method differs in whether `hook.on-activate` and `profile` scripts are
+run:
+
+| Mode | Command | `hook.on-activate` | `profile.*` |
+| --- | --- | :---: | :---: |
+| Subshell | `flox activate` | :white_check_mark: | :white_check_mark: |
+| In-place | `eval "$(flox activate)"` | :white_check_mark: | :white_check_mark: |
+| Shell command | `flox activate -c` | :white_check_mark: | :white_check_mark: |
+| Exec | `flox activate --` | :white_check_mark: | :x: |
 
 ### Subshell
 
@@ -97,6 +111,14 @@ eval "$(flox activate)"
 In both cases Flox emits a script that configures the shell,
 and the shell executes that code to configure itself.
 
+!!! tip "direnv integration"
+
+    If you use [direnv](https://direnv.net/) with `use flox` in your
+    `.envrc`, the activation is in-place and both `hook.on-activate` and
+    `[profile]` scripts are run.
+    Note that `profile.common` must use shell-agnostic syntax — see
+    the [guidance below](#hook-vs-profile-in-a-nutshell).
+
 ```d2 scale="1.0"
 shape: sequence_diagram
 user_shell: User shell
@@ -283,7 +305,10 @@ here is some simple guidance:
 
 **profile**:
 
-- Syntax depends on the shell.
+- Syntax depends on the shell. `profile.common` is sourced by _all_ shells
+  (Bash, Zsh, Fish, and tcsh), so avoid constructs like `export VAR=value`
+  that are not portable. Use the shell-specific `profile.bash`, `profile.zsh`,
+  etc. sections for non-portable syntax.
 - Can define functions and aliases.
 - Can source scripts needed for other programs to work properly e.g. the `activate` script for a Python virtual environment.
 - _Can_ define environment variables that need to be computed.

docs/concepts/activation.md

@@ -130,6 +130,9 @@ This can be surprising, so check the manifests of the included environments and
 It's reasonable to assume that the manifests of the included environments will change over time and at some point you will want to bring in the latest versions of those manifests.
 This is accomplished with the `flox include upgrade` command.
 
-Running this command will check each of the included environments and determine if there were changes to their manifests.
-If the changes to the manifest have been built by the included environment, then the new manifest will be included.
+Running this command will check each of the included environments and check if the environments have changed.
+In order for changes to be pulled in, the included environment must have a lockfile corresponding to the latest changes to the manifest.
+For example, suppose an environment `my-go-project` includes a `go-tools` environment.
+If the `manifest.toml` for `go-tools` is modified without using `flox edit`, then `flox include upgrade` for `my-go-project` won't be able use the changes to the `go-tools` manifest.
+Using `flox edit` for `go-tools` would re-lock the environment using the latest manifest, and then `flox include upgrade` for `my-go-project` could pull in the changes.
 At this point the merge process runs again, a new merged manifest is produced, and the composed environment is rebuilt from the new merged manifest.