Split up documentation (#632)

Closes: #558

docs/environment-and-tools.md

@@ -0,0 +1,146 @@
+# Environment and Tools
+
+This document covers environment activation, tool directory configuration, and authentication options.
+
+## Activate environment
+
+You can set `activate-environment` to `true` to automatically activate a venv.
+This allows directly using it in later steps:
+
+```yaml
+- name: Install the latest version of uv and activate the environment
+  uses: astral-sh/setup-uv@v6
+  with:
+    activate-environment: true
+- run: uv pip install pip
+```
+
+> [!WARNING]
+>
+> Activating the environment adds your dependencies to the `PATH`, which could break some workflows.
+> For example, if you have a dependency which requires uv, e.g., `hatch`, activating the
+> environment will shadow the `uv` binary installed by this action and may result in a different uv
+> version being used.
+>
+> We do not recommend using this setting for most use-cases. Instead, use `uv run` to execute
+> commands in the environment.
+
+## GitHub authentication token
+
+This action uses the GitHub API to fetch the uv release artifacts. To avoid hitting the GitHub API
+rate limit too quickly, an authentication token can be provided via the `github-token` input. By
+default, the `GITHUB_TOKEN` secret is used, which is automatically provided by GitHub Actions.
+
+If the default
+[permissions for the GitHub token](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token)
+are not sufficient, you can provide a custom GitHub token with the necessary permissions.
+
+```yaml
+- name: Install the latest version of uv with a custom GitHub token
+  uses: astral-sh/setup-uv@v6
+  with:
+    github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
+```
+
+## UV_TOOL_DIR
+
+On Windows `UV_TOOL_DIR` is set to `uv-tool-dir` in the `TMP` dir (e.g. `D:\a\_temp\uv-tool-dir`).
+On GitHub hosted runners this is on the much faster `D:` drive.
+
+On all other platforms the tool environments are placed in the
+[default location](https://docs.astral.sh/uv/concepts/tools/#tools-directory).
+
+If you want to change this behaviour (especially on self-hosted runners) you can use the `tool-dir`
+input:
+
+```yaml
+- name: Install the latest version of uv with a custom tool dir
+  uses: astral-sh/setup-uv@v6
+  with:
+    tool-dir: "/path/to/tool/dir"
+```
+
+## UV_TOOL_BIN_DIR
+
+On Windows `UV_TOOL_BIN_DIR` is set to `uv-tool-bin-dir` in the `TMP` dir (e.g.
+`D:\a\_temp\uv-tool-bin-dir`). On GitHub hosted runners this is on the much faster `D:` drive. This
+path is also automatically added to the PATH.
+
+On all other platforms the tool binaries get installed to the
+[default location](https://docs.astral.sh/uv/concepts/tools/#the-bin-directory).
+
+If you want to change this behaviour (especially on self-hosted runners) you can use the
+`tool-bin-dir` input:
+
+```yaml
+- name: Install the latest version of uv with a custom tool bin dir
+  uses: astral-sh/setup-uv@v6
+  with:
+    tool-bin-dir: "/path/to/tool-bin/dir"
+```
+
+## Tilde Expansion
+
+This action supports expanding the `~` character to the user's home directory for the following inputs:
+
+- `version-file`
+- `cache-local-path`
+- `tool-dir`
+- `tool-bin-dir`
+- `cache-dependency-glob`
+
+```yaml
+- name: Expand the tilde character
+  uses: astral-sh/setup-uv@v6
+  with:
+    cache-local-path: "~/path/to/cache"
+    tool-dir: "~/path/to/tool/dir"
+    tool-bin-dir: "~/path/to/tool-bin/dir"
+    cache-dependency-glob: "~/my-cache-buster"
+```
+
+## Ignore empty workdir
+
+By default, the action will warn if the workdir is empty, because this is usually the case when
+`actions/checkout` is configured to run after `setup-uv`, which is not supported.
+
+If you want to ignore this, set the `ignore-empty-workdir` input to `true`.
+
+```yaml
+- name: Ignore empty workdir
+  uses: astral-sh/setup-uv@v6
+  with:
+    ignore-empty-workdir: true
+```
+
+## Environment Variables
+
+This action sets several environment variables that influence uv's behavior and can be used by subsequent steps:
+
+- `UV_PYTHON`: Set when `python-version` input is specified. Controls which Python version uv uses.
+- `UV_CACHE_DIR`: Set when caching is enabled (unless already configured in uv config files). Controls where uv stores its cache.
+- `UV_TOOL_DIR`: Set when `tool-dir` input is specified. Controls where uv installs tool environments.
+- `UV_TOOL_BIN_DIR`: Set when `tool-bin-dir` input is specified. Controls where uv installs tool binaries.
+- `UV_PYTHON_INSTALL_DIR`: Always set. Controls where uv installs Python versions.
+- `VIRTUAL_ENV`: Set when `activate-environment` is true. Points to the activated virtual environment.
+
+**Environment variables that affect the action behavior:**
+
+- `UV_NO_MODIFY_PATH`: If set, prevents the action from modifying PATH. Cannot be used with `activate-environment`.
+- `UV_CACHE_DIR`: If already set, the action will respect it instead of setting its own cache directory.
+
+```yaml
+- name: Example using environment variables
+  uses: astral-sh/setup-uv@v6
+  with:
+    python-version: "3.12"
+    tool-dir: "/custom/tool/dir"
+    enable-cache: true
+
+- name: Check environment variables
+  run: |
+    echo "UV_PYTHON: $UV_PYTHON"
+    echo "UV_CACHE_DIR: $UV_CACHE_DIR"
+    echo "UV_TOOL_DIR: $UV_TOOL_DIR"
+    echo "UV_PYTHON_INSTALL_DIR: $UV_PYTHON_INSTALL_DIR"
+```