Mention pixi exec in docs (#131)

Author: pavelzw

.github/workflows/test.yml

@@ -456,6 +456,27 @@ jobs:
       - run: |
           python --version | Select-String "3.11"
         shell: pixi run pwsh -Command {0}
+
+  pixi-shell-exec:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        with:
+          run-install: false
+      - run: |
+          python --version | grep -q "3.11"
+        shell: pixi exec --spec python=3.11.* -- bash -e {0}
+      - run: |
+          import ruamel.yaml
+        shell: pixi exec --spec python --spec ruamel.yaml -- python {0}
+      - run: |
+          python --version | Select-String "3.11"
+        shell: pixi exec --spec python=3.11.* -- pwsh -Command {0}
+
   post-cleanup-linux:
     runs-on: ubuntu-latest
     strategy:

README.md

@@ -229,6 +229,25 @@ If you want to use PowerShell, you need to specify `-Command` as well.
 > There are some custom shells provided by GitHub that have slightly different behavior, see [`jobs.<job_id>.steps[*].shell`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell) in the documentation.
 > See the [official documentation](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#custom-shell) and [ADR 0277](https://github.com/actions/runner/blob/main/docs/adrs/0277-run-action-shell-options.md) for more information about how the `shell:` input works in GitHub Actions.
 
+#### One-off shell wrapper using `pixi exec`
+
+With `pixi exec`, you can also run a one-off command inside a temporary pixi environment.
+
+```yml
+- run: | # everything here will be run inside of the temporary pixi environment
+    zstd --version
+  shell: pixi exec --spec zstd -- bash -e {0}
+```
+
+```yml
+- run: | # everything here will be run inside of the temporary pixi environment
+    import ruamel.yaml
+    # ...
+  shell: pixi exec --spec python=3.11.* --spec ruamel.yaml -- python {0}
+```
+
+See [here](https://pixi.sh/latest/reference/cli#exec) for more information about `pixi exec`.
+
 ### Environment activation
 
 Instead of using a custom shell wrapper, you can also make all pixi-installed binaries available to subsequent steps by "activating" the installed environment in the currently running job.