Improve globset documentation and help message (#1808)

Closes #1545.

README.md

@@ -343,21 +343,21 @@ Options:
           Disable cache reads
       --isolated
           Ignore all configuration files
-      --select <SELECT>
+      --select <RULE_CODE>
           Comma-separated list of rule codes to enable (or ALL, to enable all rules)
-      --extend-select <EXTEND_SELECT>
+      --extend-select <RULE_CODE>
           Like --select, but adds additional rule codes on top of the selected ones
-      --ignore <IGNORE>
+      --ignore <RULE_CODE>
           Comma-separated list of rule codes to disable
-      --extend-ignore <EXTEND_IGNORE>
+      --extend-ignore <RULE_CODE>
           Like --ignore, but adds additional rule codes on top of the ignored ones
-      --exclude <EXCLUDE>
+      --exclude <FILE_PATTERN>
           List of paths, used to omit files and/or directories from analysis
-      --extend-exclude <EXTEND_EXCLUDE>
+      --extend-exclude <FILE_PATTERN>
           Like --exclude, but adds additional files and directories on top of those already excluded
-      --fixable <FIXABLE>
+      --fixable <RULE_CODE>
           List of rule codes to treat as eligible for autofix. Only applicable when autofix itself is enabled (e.g., via `--fix`)
-      --unfixable <UNFIXABLE>
+      --unfixable <RULE_CODE>
           List of rule codes to treat as ineligible for autofix. Only applicable when autofix itself is enabled (e.g., via `--fix`)
       --per-file-ignores <PER_FILE_IGNORES>
           List of mappings from file pattern to code to exclude
@@ -1825,6 +1825,8 @@ Exclusions are based on globs, and can be either:
   `directory`). Note that these paths are relative to the project root
   (e.g., the directory containing your `pyproject.toml`).
 
+For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).
+
 Note that you'll typically want to use
 [`extend-exclude`](#extend-exclude) to modify the excluded paths.
 
@@ -1872,6 +1874,18 @@ line-length = 100
 A list of file patterns to omit from linting, in addition to those
 specified by `exclude`.
 
+Exclusions are based on globs, and can be either:
+
+- Single-path patterns, like `.mypy_cache` (to exclude any directory
+  named `.mypy_cache` in the tree), `foo.py` (to exclude any file named
+  `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ).
+- Relative patterns, like `directory/foo.py` (to exclude that specific
+  file) or `directory/*.py` (to exclude any Python files in
+  `directory`). Note that these paths are relative to the project root
+  (e.g., the directory containing your `pyproject.toml`).
+
+For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).
+
 **Default value**: `[]`
 
 **Type**: `Vec<FilePattern>`

ruff.schema.json

@@ -40,7 +40,7 @@
       ]
     },
     "exclude": {
-      "description": "A list of file patterns to exclude from linting.\n\nExclusions are based on globs, and can be either:\n\n- Single-path patterns, like `.mypy_cache` (to exclude any directory named `.mypy_cache` in the tree), `foo.py` (to exclude any file named `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ). - Relative patterns, like `directory/foo.py` (to exclude that specific file) or `directory/*.py` (to exclude any Python files in `directory`). Note that these paths are relative to the project root (e.g., the directory containing your `pyproject.toml`).\n\nNote that you'll typically want to use [`extend-exclude`](#extend-exclude) to modify the excluded paths.",
+      "description": "A list of file patterns to exclude from linting.\n\nExclusions are based on globs, and can be either:\n\n- Single-path patterns, like `.mypy_cache` (to exclude any directory named `.mypy_cache` in the tree), `foo.py` (to exclude any file named `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ). - Relative patterns, like `directory/foo.py` (to exclude that specific file) or `directory/*.py` (to exclude any Python files in `directory`). Note that these paths are relative to the project root (e.g., the directory containing your `pyproject.toml`).\n\nFor more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).\n\nNote that you'll typically want to use [`extend-exclude`](#extend-exclude) to modify the excluded paths.",
       "type": [
         "array",
         "null"
@@ -57,7 +57,7 @@
       ]
     },
     "extend-exclude": {
-      "description": "A list of file patterns to omit from linting, in addition to those specified by `exclude`.",
+      "description": "A list of file patterns to omit from linting, in addition to those specified by `exclude`.\n\nExclusions are based on globs, and can be either:\n\n- Single-path patterns, like `.mypy_cache` (to exclude any directory named `.mypy_cache` in the tree), `foo.py` (to exclude any file named `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ). - Relative patterns, like `directory/foo.py` (to exclude that specific file) or `directory/*.py` (to exclude any Python files in `directory`). Note that these paths are relative to the project root (e.g., the directory containing your `pyproject.toml`).\n\nFor more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).",
       "type": [
         "array",
         "null"

src/cli.rs

@@ -61,33 +61,33 @@ pub struct Cli {
     pub isolated: bool,
     /// Comma-separated list of rule codes to enable (or ALL, to enable all
     /// rules).
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")]
     pub select: Option<Vec<RuleCodePrefix>>,
     /// Like --select, but adds additional rule codes on top of the selected
     /// ones.
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")]
     pub extend_select: Option<Vec<RuleCodePrefix>>,
     /// Comma-separated list of rule codes to disable.
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")]
     pub ignore: Option<Vec<RuleCodePrefix>>,
     /// Like --ignore, but adds additional rule codes on top of the ignored
     /// ones.
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")]
     pub extend_ignore: Option<Vec<RuleCodePrefix>>,
     /// List of paths, used to omit files and/or directories from analysis.
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "FILE_PATTERN")]
     pub exclude: Option<Vec<FilePattern>>,
     /// Like --exclude, but adds additional files and directories on top of
     /// those already excluded.
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "FILE_PATTERN")]
     pub extend_exclude: Option<Vec<FilePattern>>,
     /// List of rule codes to treat as eligible for autofix. Only applicable
     /// when autofix itself is enabled (e.g., via `--fix`).
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")]
     pub fixable: Option<Vec<RuleCodePrefix>>,
     /// List of rule codes to treat as ineligible for autofix. Only applicable
     /// when autofix itself is enabled (e.g., via `--fix`).
-    #[arg(long, value_delimiter = ',')]
+    #[arg(long, value_delimiter = ',', value_name = "RULE_CODE")]
     pub unfixable: Option<Vec<RuleCodePrefix>>,
     /// List of mappings from file pattern to code to exclude
     #[arg(long, value_delimiter = ',')]

src/settings/options.rs

@@ -87,6 +87,8 @@ pub struct Options {
     ///   `directory`). Note that these paths are relative to the project root
     ///   (e.g., the directory containing your `pyproject.toml`).
     ///
+    /// For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).
+    ///
     /// Note that you'll typically want to use
     /// [`extend-exclude`](#extend-exclude) to modify the excluded paths.
     pub exclude: Option<Vec<String>>,
@@ -118,6 +120,18 @@ pub struct Options {
     )]
     /// A list of file patterns to omit from linting, in addition to those
     /// specified by `exclude`.
+    ///
+    /// Exclusions are based on globs, and can be either:
+    ///
+    /// - Single-path patterns, like `.mypy_cache` (to exclude any directory
+    ///   named `.mypy_cache` in the tree), `foo.py` (to exclude any file named
+    ///   `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ).
+    /// - Relative patterns, like `directory/foo.py` (to exclude that specific
+    ///   file) or `directory/*.py` (to exclude any Python files in
+    ///   `directory`). Note that these paths are relative to the project root
+    ///   (e.g., the directory containing your `pyproject.toml`).
+    ///
+    /// For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax).
     pub extend_exclude: Option<Vec<String>>,
     #[option(
         default = "[]",