From 3228fc5f350beddd49aea20dc58484e5dad5203b Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Fri, 9 Aug 2024 12:15:22 -0500 Subject: [PATCH] Improve the `uv venv` CLI documentation (#5963) This was actually in pretty good shape already! --- crates/uv-cli/src/lib.rs | 24 +++++++++++++++++------- docs/reference/cli.md | 26 ++++++++++---------------- 2 files changed, 27 insertions(+), 23 deletions(-) diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs index 3c5f2e371..85bd353f2 100644 --- a/crates/uv-cli/src/lib.rs +++ b/crates/uv-cli/src/lib.rs @@ -298,6 +298,16 @@ pub enum Commands { )] Pip(PipNamespace), /// Create a virtual environment. + /// + /// By default, creates a virtual environment named `.venv` in the working + /// directory. An alternative path may be provided positionally. + /// + /// If a virtual environment exists at the target path, it will be removed + /// and a new, empty virtual environment will be created. + /// + /// When using uv, the virtual environment does not need to be activated. uv + /// will find a virtual environment (named `.venv`) in the working directory + /// or any parent directories. #[command( alias = "virtualenv", alias = "v", @@ -1887,13 +1897,13 @@ pub struct VenvArgs { /// Provide an alternative prompt prefix for the virtual environment. /// - /// The default behavior depends on whether the virtual environment path is provided: - /// - If provided (`uv venv project`), the prompt is set to the virtual environment's directory name. - /// - If not provided (`uv venv`), the prompt is set to the current directory's name. + /// By default, the prompt is dependent on whether a path was provided to + /// `uv venv`. If provided (e.g, `uv venv project`), the prompt is set to + /// the directory name. If not provided (`uv venv`), the prompt is set to + /// the current directory's name. /// - /// Possible values: - /// - `.`: Use the current directory name. - /// - Any string: Use the given string. + /// If "." is provided, the the current directory name will be used + /// regardless of whether a path was provided to `uv venv`. #[arg(long, verbatim_doc_comment)] pub prompt: Option, @@ -1902,7 +1912,7 @@ pub struct VenvArgs { /// Unlike `pip`, when a virtual environment is created with `--system-site-packages`, uv will /// _not_ take system site packages into account when running commands like `uv pip list` or /// `uv pip install`. The `--system-site-packages` flag will provide the virtual environment - /// with access to the system site packages directory at runtime, but it will not affect the + /// with access to the system site packages directory at runtime, but will not affect the /// behavior of uv commands. #[arg(long)] pub system_site_packages: bool, diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 57f870ed9..767802b5d 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -5273,7 +5273,13 @@ uv pip check [OPTIONS] ## uv venv -Create a virtual environment +Create a virtual environment. + +By default, creates a virtual environment named `.venv` in the working directory. An alternative path may be provided positionally. + +If a virtual environment exists at the target path, it will be removed and a new, empty virtual environment will be created. + +When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named `.venv`) in the working directory or any parent directories.

Usage

@@ -5406,21 +5412,9 @@ uv venv [OPTIONS] [NAME]
--prompt prompt

Provide an alternative prompt prefix for the virtual environment.

-

The default behavior depends on whether the virtual environment path is provided:

+

By default, the prompt is dependent on whether a path was provided to uv venv. If provided (e.g, uv venv project), the prompt is set to the directory name. If not provided (uv venv), the prompt is set to the current directory’s name.

-
    -
  • If provided (uv venv project), the prompt is set to the virtual environment’s directory name.
    • - -
  • If not provided (uv venv), the prompt is set to the current directory’s name.
    • -
- -

Possible values:

- -
    -
  • .: Use the current directory name.
    • - -
  • Any string: Use the given string.
    • -
+

If "." is provided, the the current directory name will be used regardless of whether a path was provided to uv venv.

--python, -p python

The Python interpreter to use for the virtual environment.

@@ -5468,7 +5462,7 @@ uv venv [OPTIONS] [NAME]
--system-site-packages

Give the virtual environment access to the system site packages directory.

-

Unlike pip, when a virtual environment is created with --system-site-packages, uv will not take system site packages into account when running commands like uv pip list or uv pip install. The --system-site-packages flag will provide the virtual environment with access to the system site packages directory at runtime, but it will not affect the behavior of uv commands.

+

Unlike pip, when a virtual environment is created with --system-site-packages, uv will not take system site packages into account when running commands like uv pip list or uv pip install. The --system-site-packages flag will provide the virtual environment with access to the system site packages directory at runtime, but will not affect the behavior of uv commands.

--verbose, -v

Use verbose output.