docs(src/assets/): update uv official documentation

Author: KemingHe

src/assets/uv/_metadata.json

@@ -1,6 +1,6 @@
 {
   "source_repo": "astral-sh/uv",
   "docs_path": "docs",
-  "updated_at": "2025-08-26T22:05:11Z",
-  "commit_sha": "9eb5fc240ca28d8222f1be6d62379fd795e2f09e"
+  "updated_at": "2025-09-02T22:05:05Z",
+  "commit_sha": "f9e98d1fb6bf2b1350f60d5bf401f7038da2d3e8"
 }

src/assets/uv/concepts/authentication/certificates.md

@@ -0,0 +1,41 @@
+# TLS certificates
+
+By default, uv loads certificates from the bundled `webpki-roots` crate. The `webpki-roots` are a
+reliable set of trust roots from Mozilla, and including them in uv improves portability and
+performance (especially on macOS, where reading the system trust store incurs a significant delay).
+
+## System certificates
+
+In some cases, you may want to use the platform's native certificate store, especially if you're
+relying on a corporate trust root (e.g., for a mandatory proxy) that's included in your system's
+certificate store. To instruct uv to use the system's trust store, run uv with the `--native-tls`
+command-line flag, or set the `UV_NATIVE_TLS` environment variable to `true`.
+
+## Custom certificates
+
+If a direct path to the certificate is required (e.g., in CI), set the `SSL_CERT_FILE` environment
+variable to the path of the certificate bundle, to instruct uv to use that file instead of the
+system's trust store.
+
+If client certificate authentication (mTLS) is desired, set the `SSL_CLIENT_CERT` environment
+variable to the path of the PEM formatted file containing the certificate followed by the private
+key.
+
+## Insecure hosts
+
+If you're using a setup in which you want to trust a self-signed certificate or otherwise disable
+certificate verification, you can instruct uv to allow insecure connections to dedicated hosts via
+the `allow-insecure-host` configuration option. For example, adding the following to
+`pyproject.toml` will allow insecure connections to `example.com`:
+
+```toml
+[tool.uv]
+allow-insecure-host = ["example.com"]
+```
+
+`allow-insecure-host` expects to receive a hostname (e.g., `localhost`) or hostname-port pair (e.g.,
+`localhost:8080`), and is only applicable to HTTPS connections, as HTTP connections are inherently
+insecure.
+
+Use `allow-insecure-host` with caution and only in trusted environments, as it can expose you to
+security risks due to the lack of certificate verification.

src/assets/uv/concepts/authentication/cli.md

@@ -0,0 +1,69 @@
+# The `uv auth` CLI
+
+uv provides a high-level interface for storing and retrieving credentials from services.
+
+## Logging in to a service
+
+To add credentials for service, use the `uv auth login` command:
+
+```console
+$ uv auth login example.com
+```
+
+This will prompt for the credentials.
+
+The credentials can also be provided using the `--username` and `--password` options, or the
+`--token` option for services which use a `__token__` or arbitrary username.
+
+!!! note
+
+    We recommend providing the secret via stdin. Use `-` to indicate the value should be read from
+    stdin, e.g., for `--password`:
+
+    ```console
+    $ echo 'my-password' | uv auth login example.com --password -
+    ```
+
+    The same pattern can be used with `--token`.
+
+Once credentials are added, uv will use them for packaging operations that require fetching content
+from the given service. At this time, only HTTPS Basic authentication is supported. The credentials
+will not yet be used for Git requests.
+
+!!! note
+
+    The credentials will not be validated, i.e., incorrect credentials will not fail.
+
+## Logging out of a service
+
+To remove credentials, use the `uv auth logout` command:
+
+```console
+$ uv auth logout example.com
+```
+
+!!! note
+
+    The credentials will not be invalidated with the remote server, i.e., they will only be removed
+    from local storage not rendered unusable.
+
+## Showing credentials for a service
+
+To show the credential stored for a given URL, use the `uv auth token` command:
+
+```console
+$ uv auth token example.com
+```
+
+If a username was used to log in, it will need to be provided as well, e.g.:
+
+```console
+$ uv auth token --username foo example.com
+```
+
+## Configuring the storage backend
+
+Credentials are persisted to the uv [credentials store](./http.md#the-uv-credentials-store).
+
+By default, credentials are written to a plaintext file. An encrypted system-native storage backend
+can be enabled with `UV_PREVIEW_FEATURES=native-auth`.

src/assets/uv/concepts/authentication/git.md

@@ -0,0 +1,70 @@
+# Git credentials
+
+uv allows packages to be installed from private Git repositories using SSH or HTTP authentication.
+
+## SSH authentication
+
+To authenticate using an SSH key, use the `ssh://` protocol:
+
+- `git+ssh://git@<hostname>/...` (e.g., `git+ssh://git@github.com/astral-sh/uv`)
+- `git+ssh://git@<host>/...` (e.g., `git+ssh://git@github.com-key-2/astral-sh/uv`)
+
+SSH authentication requires using the username `git`.
+
+See the
+[GitHub SSH documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh)
+for more details on how to configure SSH.
+
+### HTTP authentication
+
+To authenticate over HTTP Basic authentication using a password or token:
+
+- `git+https://<user>:<token>@<hostname>/...` (e.g.,
+  `git+https://git:github_pat_asdf@github.com/astral-sh/uv`)
+- `git+https://<token>@<hostname>/...` (e.g., `git+https://github_pat_asdf@github.com/astral-sh/uv`)
+- `git+https://<user>@<hostname>/...` (e.g., `git+https://git@github.com/astral-sh/uv`)
+
+!!! note
+
+    When using a GitHub personal access token, the username is arbitrary. GitHub doesn't allow you to
+    use your account name and password in URLs like this, although other hosts may.
+
+If there are no credentials present in the URL and authentication is needed, the
+[Git credential helper](#git-credential-helpers) will be queried.
+
+## Persistence of credentials
+
+When using `uv add`, uv _will not_ persist Git credentials to the `pyproject.toml` or `uv.lock`.
+These files are often included in source control and distributions, so it is generally unsafe to
+include credentials in them.
+
+If you have a Git credential helper configured, your credentials may be automatically persisted,
+resulting in successful subsequent fetches of the dependency. However, if you do not have a Git
+credential helper or the project is used on a machine without credentials seeded, uv will fail to
+fetch the dependency.
+
+You _may_ force uv to persist Git credentials by passing the `--raw` option to `uv add`. However, we
+strongly recommend setting up a [credential helper](#git-credential-helpers) instead.
+
+## Git credential helpers
+
+Git credential helpers are used to store and retrieve Git credentials. See the
+[Git documentation](https://git-scm.com/doc/credential-helpers) to learn more.
+
+If you're using GitHub, the simplest way to set up a credential helper is to
+[install the `gh` CLI](https://github.com/cli/cli#installation) and use:
+
+```console
+$ gh auth login
+```
+
+See the [`gh auth login`](https://cli.github.com/manual/gh_auth_login) documentation for more
+details.
+
+!!! note
+
+    When using `gh auth login` interactively, the credential helper will be configured automatically.
+    But when using `gh auth login --with-token`, as in the uv
+    [GitHub Actions guide](../../guides/integration/github.md#private-repos), the
+    [`gh auth setup-git`](https://cli.github.com/manual/gh_auth_setup-git) command will need to be
+    run afterwards to configure the credential helper.

src/assets/uv/concepts/authentication/http.md

@@ -0,0 +1,85 @@
+# HTTP credentials
+
+uv supports credentials over HTTP when querying package registries.
+
+Authentication can come from the following sources, in order of precedence:
+
+- The URL, e.g., `https://<user>:<password>@<hostname>/...`
+- A [netrc](#netrc-files) configuration file
+- The uv credentials store
+- A [keyring provider](#keyring-providers) (off by default)
+
+Authentication may be used for hosts specified in the following contexts:
+
+- `[index]`
+- `index-url`
+- `extra-index-url`
+- `find-links`
+- `package @ https://...`
+
+## netrc files
+
+[`.netrc`](https://everything.curl.dev/usingcurl/netrc) files are a long-standing plain text format
+for storing credentials on a system.
+
+Reading credentials from `.netrc` files is always enabled. The target file path will be loaded from
+the `NETRC` environment variable if defined, falling back to `~/.netrc` if not.
+
+## The uv credentials store
+
+uv can read and write credentials from a store using the [`uv auth` commands](./cli.md).
+
+Credentials are stored in a plaintext file in uv's state directory, e.g.,
+`~/.local/share/uv/credentials/credentials.toml` on Unix. This file is currently not intended to be
+edited manually.
+
+!!! note
+
+    A secure, system native storage mechanism is in [preview](../preview.md) — it is still
+    experimental and being actively developed. In the future, this will become the default storage
+    mechanism.
+
+    When enabled, uv will use the secret storage mechanism native to your operating system. On
+    macOS, it uses the Keychain Services. On Windows, it uses the Windows Credential Manager. On
+    Linux, it uses the DBus-based Secret Service API.
+
+    Currently, uv only searches the native store for credentials it has added to the secret store —
+    it will not retrieve credentials persisted by other applications.
+
+    Set `UV_PREVIEW_FEATURES=native-auth` to use this storage mechanism.
+
+## Keyring providers
+
+A keyring provider is a concept from `pip` allowing retrieval of credentials from an interface
+matching the popular [keyring](https://github.com/jaraco/keyring) Python package.
+
+The "subprocess" keyring provider invokes the `keyring` command to fetch credentials. uv does not
+support additional keyring provider types at this time.
+
+Set `--keyring-provider subprocess`, `UV_KEYRING_PROVIDER=subprocess`, or
+`tool.uv.keyring-provider = "subprocess"` to use the provider.
+
+## Persistence of credentials
+
+If authentication is found for a single index URL or net location (scheme, host, and port), it will
+be cached for the duration of the command and used for other queries to that index or net location.
+Authentication is not cached across invocations of uv.
+
+When using `uv add`, uv _will not_ persist index credentials to the `pyproject.toml` or `uv.lock`.
+These files are often included in source control and distributions, so it is generally unsafe to
+include credentials in them. However, uv _will_ persist credentials for direct URLs, i.e.,
+`package @ https://username:password:example.com/foo.whl`, as there is not currently a way to
+otherwise provide those credentials.
+
+If credentials were attached to an index URL during `uv add`, uv may fail to fetch dependencies from
+indexes which require authentication on subsequent operations. See the
+[index authentication documentation](../indexes.md#authentication) for details on persistent
+authentication for indexes.
+
+## Learn more
+
+See the [index authentication documentation](../indexes.md#authentication) for details on
+authenticating index URLs.
+
+See the [`pip` compatibility guide](../../pip/compatibility.md#registry-authentication) for details
+on differences from `pip`.

src/assets/uv/concepts/authentication/index.md

@@ -0,0 +1,11 @@
+# Authentication
+
+Authentication is required when working with private repositories or package indexes.
+
+Learn more about authentication in uv:
+
+- [Using the `uv auth` CLI](./cli.md)
+- [HTTP authentication](./http.md)
+- [Git authentication](./git.md)
+- [TLS certificates](./certificates.md)
+- [Third-party services](./third-party.md)

src/assets/uv/concepts/authentication/third-party.md

@@ -0,0 +1,21 @@
+# Third-party services
+
+## Authentication with alternative package indexes
+
+See the [alternative indexes integration guide](../../guides/integration/alternative-indexes.md) for
+details on authentication with popular alternative Python package indexes.
+
+## Hugging Face support
+
+uv supports automatic authentication for the Hugging Face Hub. Specifically, if the `HF_TOKEN`
+environment variable is set, uv will propagate it to requests to `huggingface.co`.
+
+This is particularly useful for accessing private scripts in Hugging Face Datasets. For example, you
+can run the following command to execute the script `main.py` script from a private dataset:
+
+```console
+$ HF_TOKEN=hf_... uv run https://huggingface.co/datasets/<user>/<name>/resolve/<branch>/main.py
+```
+
+You can disable automatic Hugging Face authentication by setting the `UV_NO_HF_TOKEN=1` environment
+variable.

src/assets/uv/concepts/build-backend.md

@@ -31,7 +31,7 @@ To use uv as a build backend in an existing project, add `uv_build` to the
 
 ```toml title="pyproject.toml"
 [build-system]
-requires = ["uv_build>=0.8.13,<0.9.0"]
+requires = ["uv_build>=0.8.14,<0.9.0"]
 build-backend = "uv_build"
 ```
 
@@ -237,6 +237,13 @@ must either be under the module root or in the appropriate
 [data directory](../reference/settings.md#build-backend_data). Most packages store small data in the
 module root alongside the source code.
 
+!!! tip
+
+    When using the uv build backend through a frontend that is not uv, such as pip or
+    `python -m build`, debug logging can be enabled through environment variables with
+    `RUST_LOG=uv=debug` or `RUST_LOG=uv=verbose`. When used through uv, the uv build backend shares
+    the verbosity level of uv.
+
 ### Include and exclude syntax
 
 Includes are anchored, which means that `pyproject.toml` includes only `<root>/pyproject.toml` and

src/assets/uv/concepts/index.md

@@ -9,7 +9,7 @@ Read the concept documents to learn more about uv's features:
 - [Package indexes](./indexes.md)
 - [Resolution](./resolution.md)
 - [The uv build backend](./build-backend.md)
-- [Authentication](./authentication.md)
+- [Authentication](./authentication/index.md)
 - [Caching](./cache.md)
 - [The pip interface](../pip/index.md)
 

src/assets/uv/concepts/indexes.md

@@ -184,8 +184,8 @@ access to the authenticated URL at installation time.
 ### Using credential providers
 
 In addition to providing credentials directly, uv supports discovery of credentials from netrc and
-keyring. See the [HTTP authentication](./authentication.md#http-authentication) documentation for
-details on setting up specific credential providers.
+keyring. See the [HTTP authentication](./authentication/http.md) documentation for details on
+setting up specific credential providers.
 
 By default, uv will attempt an unauthenticated request before querying providers. If the request
 fails, uv will search for credentials. If credentials are found, an authenticated request will be