Improve display order of top-level commands (#5830)

Closes https://github.com/astral-sh/uv/issues/5702

Since Clap 4, the default order follows the declarations.

Also improves some descriptions.

crates/uv-cli/src/lib.rs

@@ -213,12 +213,9 @@ impl From<ColorChoice> for anstream::ColorChoice {
 #[derive(Subcommand)]
 #[allow(clippy::large_enum_variant)]
 pub enum Commands {
-    /// Manage Python packages with a pip-compatible interface.
+    /// Manage Python projects.
-    #[command(
+    #[command(flatten)]
-        after_help = "Use `uv help pip`` for more details.",
+    Project(Box<ProjectCommand>),
-        after_long_help = ""
-    )]
-    Pip(PipNamespace),
     /// Run and manage tools provided by Python packages (experimental).
     #[command(
         after_help = "Use `uv help tool` for more details.",
@@ -231,9 +228,12 @@ pub enum Commands {
         after_long_help = ""
     )]
     Python(PythonNamespace),
-    /// Manage Python projects.
+    /// Manage Python packages with a pip-compatible interface.
-    #[command(flatten)]
+    #[command(
-    Project(Box<ProjectCommand>),
+        after_help = "Use `uv help pip`` for more details.",
+        after_long_help = ""
+    )]
+    Pip(PipNamespace),
     /// Create a virtual environment.
     #[command(
         alias = "virtualenv",
@@ -242,7 +242,7 @@ pub enum Commands {
         after_long_help = ""
     )]
     Venv(VenvArgs),
-    /// Manage the cache.
+    /// Manage uv's cache.
     #[command(
         after_help = "Use `uv help cache` for more details.",
         after_long_help = ""
@@ -415,39 +415,39 @@ pub enum PipCommand {
 
 #[derive(Subcommand)]
 pub enum ProjectCommand {
-    /// Create a new project (experimental).
+    /// Run a command or script (experimental).
-    Init(InitArgs),
-    /// Run a command in an environment (experimental).
     #[command(
         after_help = "Use `uv help run` for more details.",
         after_long_help = ""
     )]
     Run(RunArgs),
-    /// Update the project's environment to match the project's dependencies (experimental).
+    /// Create a new project (experimental).
-    #[command(
+    Init(InitArgs),
-        after_help = "Use `uv help sync` for more details.",
+    /// Add dependencies to the project (experimental).
-        after_long_help = ""
-    )]
-    Sync(SyncArgs),
-    /// Create or update a lockfile for the project's dependencies (experimental).
-    #[command(
-        after_help = "Use `uv help lock` for more details.",
-        after_long_help = ""
-    )]
-    Lock(LockArgs),
-    /// Add one or more packages to the project's dependencies (experimental).
     #[command(
         after_help = "Use `uv help add` for more details.",
         after_long_help = ""
     )]
     Add(AddArgs),
-    /// Remove one or more packages from the project's dependencies (experimental).
+    /// Remove dependencies from the project (experimental).
     #[command(
         after_help = "Use `uv help remove` for more details.",
         after_long_help = ""
     )]
     Remove(RemoveArgs),
-    /// Display the dependency tree for the project (experimental).
+    /// Update the project's environment (experimental).
+    #[command(
+        after_help = "Use `uv help sync` for more details.",
+        after_long_help = ""
+    )]
+    Sync(SyncArgs),
+    /// Update the project's lockfile (experimental).
+    #[command(
+        after_help = "Use `uv help lock` for more details.",
+        after_long_help = ""
+    )]
+    Lock(LockArgs),
+    /// Display the project's dependency tree (experimental).
     Tree(TreeArgs),
 }
 

crates/uv/tests/help.rs

@@ -16,18 +16,18 @@ fn help() {
     Usage: uv [OPTIONS] <COMMAND>
 
     Commands:
-      pip      Manage Python packages with a pip-compatible interface
+      run      Run a command or script (experimental)
+      init     Create a new project (experimental)
+      add      Add dependencies to the project (experimental)
+      remove   Remove dependencies from the project (experimental)
+      sync     Update the project's environment (experimental)
+      lock     Update the project's lockfile (experimental)
+      tree     Display the project's dependency tree (experimental)
       tool     Run and manage tools provided by Python packages (experimental)
       python   Manage Python versions and installations (experimental)
-      init     Create a new project (experimental)
+      pip      Manage Python packages with a pip-compatible interface
-      run      Run a command in an environment (experimental)
-      sync     Update the project's environment to match the project's dependencies (experimental)
-      lock     Create or update a lockfile for the project's dependencies (experimental)
-      add      Add one or more packages to the project's dependencies (experimental)
-      remove   Remove one or more packages from the project's dependencies (experimental)
-      tree     Display the dependency tree for the project (experimental)
       venv     Create a virtual environment
-      cache    Manage the cache
+      cache    Manage uv's cache
       version  Display uv's version
       help     Display documentation for a command
 
@@ -82,18 +82,18 @@ fn help_flag() {
     Usage: uv [OPTIONS] <COMMAND>
 
     Commands:
-      pip      Manage Python packages with a pip-compatible interface
+      run      Run a command or script (experimental)
+      init     Create a new project (experimental)
+      add      Add dependencies to the project (experimental)
+      remove   Remove dependencies from the project (experimental)
+      sync     Update the project's environment (experimental)
+      lock     Update the project's lockfile (experimental)
+      tree     Display the project's dependency tree (experimental)
       tool     Run and manage tools provided by Python packages (experimental)
       python   Manage Python versions and installations (experimental)
-      init     Create a new project (experimental)
+      pip      Manage Python packages with a pip-compatible interface
-      run      Run a command in an environment (experimental)
-      sync     Update the project's environment to match the project's dependencies (experimental)
-      lock     Create or update a lockfile for the project's dependencies (experimental)
-      add      Add one or more packages to the project's dependencies (experimental)
-      remove   Remove one or more packages from the project's dependencies (experimental)
-      tree     Display the dependency tree for the project (experimental)
       venv     Create a virtual environment
-      cache    Manage the cache
+      cache    Manage uv's cache
       version  Display uv's version
       help     Display documentation for a command
 
@@ -147,18 +147,18 @@ fn help_short_flag() {
     Usage: uv [OPTIONS] <COMMAND>
 
     Commands:
-      pip      Manage Python packages with a pip-compatible interface
+      run      Run a command or script (experimental)
+      init     Create a new project (experimental)
+      add      Add dependencies to the project (experimental)
+      remove   Remove dependencies from the project (experimental)
+      sync     Update the project's environment (experimental)
+      lock     Update the project's lockfile (experimental)
+      tree     Display the project's dependency tree (experimental)
       tool     Run and manage tools provided by Python packages (experimental)
       python   Manage Python versions and installations (experimental)
-      init     Create a new project (experimental)
+      pip      Manage Python packages with a pip-compatible interface
-      run      Run a command in an environment (experimental)
-      sync     Update the project's environment to match the project's dependencies (experimental)
-      lock     Create or update a lockfile for the project's dependencies (experimental)
-      add      Add one or more packages to the project's dependencies (experimental)
-      remove   Remove one or more packages from the project's dependencies (experimental)
-      tree     Display the dependency tree for the project (experimental)
       venv     Create a virtual environment
-      cache    Manage the cache
+      cache    Manage uv's cache
       version  Display uv's version
       help     Display documentation for a command
 
@@ -565,16 +565,16 @@ fn help_unknown_subcommand() {
 
     ----- stderr -----
     error: There is no command `foobar` for `uv`. Did you mean one of:
-        pip
-        tool
-        python
-        init
         run
-        sync
+        init
-        lock
         add
         remove
+        sync
+        lock
         tree
+        tool
+        python
+        pip
         venv
         cache
         version
@@ -587,16 +587,16 @@ fn help_unknown_subcommand() {
 
     ----- stderr -----
     error: There is no command `foo bar` for `uv`. Did you mean one of:
-        pip
-        tool
-        python
-        init
         run
-        sync
+        init
-        lock
         add
         remove
+        sync
+        lock
         tree
+        tool
+        python
+        pip
         venv
         cache
         version
@@ -636,18 +636,18 @@ fn help_with_global_option() {
     Usage: uv [OPTIONS] <COMMAND>
 
     Commands:
-      pip      Manage Python packages with a pip-compatible interface
+      run      Run a command or script (experimental)
+      init     Create a new project (experimental)
+      add      Add dependencies to the project (experimental)
+      remove   Remove dependencies from the project (experimental)
+      sync     Update the project's environment (experimental)
+      lock     Update the project's lockfile (experimental)
+      tree     Display the project's dependency tree (experimental)
       tool     Run and manage tools provided by Python packages (experimental)
       python   Manage Python versions and installations (experimental)
-      init     Create a new project (experimental)
+      pip      Manage Python packages with a pip-compatible interface
-      run      Run a command in an environment (experimental)
-      sync     Update the project's environment to match the project's dependencies (experimental)
-      lock     Create or update a lockfile for the project's dependencies (experimental)
-      add      Add one or more packages to the project's dependencies (experimental)
-      remove   Remove one or more packages from the project's dependencies (experimental)
-      tree     Display the dependency tree for the project (experimental)
       venv     Create a virtual environment
-      cache    Manage the cache
+      cache    Manage uv's cache
       version  Display uv's version
       help     Display documentation for a command
 
@@ -738,18 +738,18 @@ fn help_with_no_pager() {
     Usage: uv [OPTIONS] <COMMAND>
 
     Commands:
-      pip      Manage Python packages with a pip-compatible interface
+      run      Run a command or script (experimental)
+      init     Create a new project (experimental)
+      add      Add dependencies to the project (experimental)
+      remove   Remove dependencies from the project (experimental)
+      sync     Update the project's environment (experimental)
+      lock     Update the project's lockfile (experimental)
+      tree     Display the project's dependency tree (experimental)
       tool     Run and manage tools provided by Python packages (experimental)
       python   Manage Python versions and installations (experimental)
-      init     Create a new project (experimental)
+      pip      Manage Python packages with a pip-compatible interface
-      run      Run a command in an environment (experimental)
-      sync     Update the project's environment to match the project's dependencies (experimental)
-      lock     Create or update a lockfile for the project's dependencies (experimental)
-      add      Add one or more packages to the project's dependencies (experimental)
-      remove   Remove one or more packages from the project's dependencies (experimental)
-      tree     Display the dependency tree for the project (experimental)
       venv     Create a virtual environment
-      cache    Manage the cache
+      cache    Manage uv's cache
       version  Display uv's version
       help     Display documentation for a command