cli: refer to revset argument using REVSET(S) in synopsis

This should help clarify that the arguments are not just simple change
ids or commit ids.

cli/src/commands/abandon.rs

@@ -37,7 +37,11 @@ use crate::ui::Ui;
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct AbandonArgs {
     /// The revision(s) to abandon
-    #[arg(default_value = "@", add = ArgValueCandidates::new(complete::mutable_revisions))]
+    #[arg(
+        default_value = "@",
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::mutable_revisions)
+    )]
     revisions: Vec<RevisionArg>,
     /// Do not print every abandoned commit on a separate line
     #[arg(long, short)]

cli/src/commands/absorb.rs

@@ -39,6 +39,7 @@ pub(crate) struct AbsorbArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::mutable_revisions),
     )]
     from: RevisionArg,
@@ -48,6 +49,7 @@ pub(crate) struct AbsorbArgs {
     #[arg(
         long, short = 't', visible_alias = "to",
         default_value = "mutable()",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::mutable_revisions),
     )]
     into: Vec<RevisionArg>,

cli/src/commands/backout.rs

@@ -31,6 +31,7 @@ pub(crate) struct BackoutArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     revisions: Vec<RevisionArg>,
@@ -40,6 +41,7 @@ pub(crate) struct BackoutArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     destination: Vec<RevisionArg>,

cli/src/commands/bookmark/create.rs

@@ -35,6 +35,7 @@ pub struct BookmarkCreateArgs {
     #[arg(
         long, short,
         visible_alias = "to",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     revision: Option<RevisionArg>,

cli/src/commands/bookmark/list.rs

@@ -84,7 +84,7 @@ pub struct BookmarkListArgs {
     ///
     /// Note that `-r deleted_bookmark` will not work since `deleted_bookmark`
     /// wouldn't have a local target.
-    #[arg(long, short)]
+    #[arg(long, short, value_name = "REVSETS")]
     revisions: Option<Vec<RevisionArg>>,
 
     /// Render each bookmark using the given template

cli/src/commands/bookmark/move.rs

@@ -49,7 +49,7 @@ pub struct BookmarkMoveArgs {
     #[arg(
         long,
         group = "source",
-        value_name = "REVISIONS",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     from: Vec<RevisionArg>,
@@ -60,7 +60,7 @@ pub struct BookmarkMoveArgs {
     #[arg(
         long,
         default_value = "@",
-        value_name = "REVISION",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     to: RevisionArg,

cli/src/commands/bookmark/set.rs

@@ -33,6 +33,7 @@ pub struct BookmarkSetArgs {
     #[arg(
         long, short,
         visible_alias = "to",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     revision: Option<RevisionArg>,

cli/src/commands/debug/copy_detection.rs

@@ -28,7 +28,7 @@ use crate::ui::Ui;
 #[derive(clap::Args, Clone, Debug)]
 pub struct CopyDetectionArgs {
     /// Show changes in this revision, compared to its parent(s)
-    #[arg(default_value = "@")]
+    #[arg(default_value = "@", value_name = "REVSET")]
     revision: RevisionArg,
 }
 

cli/src/commands/debug/tree.rs

@@ -29,7 +29,7 @@ use crate::ui::Ui;
 /// List the recursive entries of a tree.
 #[derive(clap::Args, Clone, Debug)]
 pub struct DebugTreeArgs {
-    #[arg(long, short = 'r')]
+    #[arg(long, short = 'r', value_name = "REVSET")]
     revision: Option<RevisionArg>,
     #[arg(long, conflicts_with = "revision")]
     id: Option<String>,

cli/src/commands/describe.rs

@@ -44,7 +44,11 @@ use crate::ui::Ui;
 #[command(visible_aliases = &["desc"])]
 pub(crate) struct DescribeArgs {
     /// The revision(s) whose description to edit
-    #[arg(default_value = "@", add = ArgValueCandidates::new(complete::mutable_revisions))]
+    #[arg(
+        default_value = "@",
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::mutable_revisions)
+    )]
     revisions: Vec<RevisionArg>,
     /// Ignored (but lets you pass `-r` for consistency with other commands)
     #[arg(short = 'r', hide = true, action = clap::ArgAction::Count)]

cli/src/commands/diff.rs

@@ -49,13 +49,30 @@ pub(crate) struct DiffArgs {
     /// If the revision is a merge commit, this shows changes *from* the
     /// automatic merge of the contents of all of its parents *to* the contents
     /// of the revision itself.
-    #[arg(long, short, add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     revision: Option<RevisionArg>,
     /// Show changes from this revision
-    #[arg(long, short, conflicts_with = "revision", add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        conflicts_with = "revision",
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     from: Option<RevisionArg>,
     /// Show changes to this revision
-    #[arg(long, short, conflicts_with = "revision", add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        conflicts_with = "revision",
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     to: Option<RevisionArg>,
     /// Restrict the diff to these paths
     #[arg(

cli/src/commands/diffedit.rs

@@ -50,14 +50,20 @@ pub(crate) struct DiffeditArgs {
     /// The revision to touch up
     ///
     /// Defaults to @ if neither --to nor --from are specified.
-    #[arg(long, short, add = ArgValueCandidates::new(complete::mutable_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::mutable_revisions)
+    )]
     revision: Option<RevisionArg>,
     /// Show changes from this revision
     ///
     /// Defaults to @ if --to is specified.
     #[arg(
         long, short,
         conflicts_with = "revision",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     from: Option<RevisionArg>,
@@ -67,6 +73,7 @@ pub(crate) struct DiffeditArgs {
     #[arg(
         long, short,
         conflicts_with = "revision",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::mutable_revisions),
     )]
     to: Option<RevisionArg>,

cli/src/commands/duplicate.rs

@@ -52,13 +52,21 @@ use crate::ui::Ui;
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct DuplicateArgs {
     /// The revision(s) to duplicate (default: @)
-    #[arg(value_name = "REVISIONS", add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     revisions_pos: Vec<RevisionArg>,
-    #[arg(short = 'r', hide = true)]
+    #[arg(short = 'r', hide = true, value_name = "REVSETS")]
     revisions_opt: Vec<RevisionArg>,
     /// The revision(s) to duplicate onto (can be repeated to create a merge
     /// commit)
-    #[arg(long, short, add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     destination: Vec<RevisionArg>,
     /// The revision(s) to insert after (can be repeated to create a merge
     /// commit)
@@ -67,6 +75,7 @@ pub(crate) struct DuplicateArgs {
         short = 'A',
         visible_alias = "after",
         conflicts_with = "destination",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     insert_after: Vec<RevisionArg>,
@@ -77,6 +86,7 @@ pub(crate) struct DuplicateArgs {
         short = 'B',
         visible_alias = "before",
         conflicts_with = "destination",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::mutable_revisions)
     )]
     insert_before: Vec<RevisionArg>,

cli/src/commands/edit.rs

@@ -33,7 +33,7 @@ use crate::ui::Ui;
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct EditArgs {
     /// The commit to edit
-    #[arg(add = ArgValueCandidates::new(complete::mutable_revisions))]
+    #[arg(value_name = "REVSET", add = ArgValueCandidates::new(complete::mutable_revisions))]
     revision: RevisionArg,
     /// Ignored (but lets you pass `-r` for consistency with other commands)
     #[arg(short = 'r', hide = true)]

cli/src/commands/evolog.rs

@@ -42,6 +42,7 @@ pub(crate) struct EvologArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     revision: RevisionArg,

cli/src/commands/file/annotate.rs

@@ -44,7 +44,12 @@ pub(crate) struct FileAnnotateArgs {
     )]
     path: String,
     /// an optional revision to start at
-    #[arg(long, short, add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     revision: Option<RevisionArg>,
 }
 

cli/src/commands/file/chmod.rs

@@ -49,6 +49,7 @@ pub(crate) struct FileChmodArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::mutable_revisions),
     )]
     revision: RevisionArg,

cli/src/commands/file/list.rs

@@ -30,6 +30,7 @@ pub(crate) struct FileListArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     revision: RevisionArg,

cli/src/commands/file/show.rs

@@ -48,6 +48,7 @@ pub(crate) struct FileShowArgs {
     #[arg(
         long, short,
         default_value = "@",
+        value_name = "REVSET",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     revision: RevisionArg,

cli/src/commands/fix.rs

@@ -126,7 +126,12 @@ pub(crate) struct FixArgs {
     /// Fix files in the specified revision(s) and their descendants. If no
     /// revisions are specified, this defaults to the `revsets.fix` setting, or
     /// `reachable(@, mutable())` if it is not set.
-    #[arg(long, short, add = ArgValueCandidates::new(complete::mutable_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::mutable_revisions)
+    )]
     source: Vec<RevisionArg>,
     /// Fix only these paths
     #[arg(value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath)]

cli/src/commands/git/push.rs

@@ -127,15 +127,15 @@ pub struct GitPushArgs {
     #[arg(long)]
     allow_private: bool,
     /// Push bookmarks pointing to these commits (can be repeated)
-    #[arg(long, short)]
+    #[arg(long, short, value_name = "REVSETS")]
     revisions: Vec<RevisionArg>,
     /// Push this commit by creating a bookmark based on its change ID (can be
     /// repeated)
     ///
     /// The created bookmark will be tracked automatically. Use the
     /// `git.push-bookmark-prefix` setting to change the prefix for generated
     /// names.
-    #[arg(long, short)]
+    #[arg(long, short, value_name = "REVSETS")]
     change: Vec<RevisionArg>,
     /// Only display what will change on the remote
     #[arg(long)]

cli/src/commands/git/submodule.rs

@@ -52,7 +52,7 @@ pub fn cmd_git_submodule(
 #[command(hide = true)]
 pub struct PrintArgs {
     /// Read .gitmodules from the given revision.
-    #[arg(long, short = 'r', default_value = "@")]
+    #[arg(long, short = 'r', default_value = "@", value_name = "REVSET")]
     revisions: RevisionArg,
 }
 

cli/src/commands/interdiff.rs

@@ -37,10 +37,20 @@ use crate::ui::Ui;
 #[command(mut_arg("ignore_space_change", |a| a.short('b')))]
 pub(crate) struct InterdiffArgs {
     /// Show changes from this revision
-    #[arg(long, short, add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     from: Option<RevisionArg>,
     /// Show changes to this revision
-    #[arg(long, short, add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSET",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     to: Option<RevisionArg>,
     /// Restrict the diff to these paths
     #[arg(

cli/src/commands/log.rs

@@ -63,7 +63,12 @@ pub(crate) struct LogArgs {
     ///
     /// If no paths nor revisions are specified, this defaults to the
     /// `revsets.log` setting.
-    #[arg(long, short, add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        long,
+        short,
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     revisions: Vec<RevisionArg>,
     /// Show revisions modifying the given paths
     #[arg(

cli/src/commands/new.rs

@@ -52,7 +52,11 @@ use crate::ui::Ui;
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct NewArgs {
     /// Parent(s) of the new change
-    #[arg(default_value = "@", add = ArgValueCandidates::new(complete::all_revisions))]
+    #[arg(
+        default_value = "@",
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::all_revisions)
+    )]
     pub(crate) revisions: Vec<RevisionArg>,
     /// Ignored (but lets you pass `-d`/`-r` for consistency with other
     /// commands)
@@ -73,6 +77,7 @@ pub(crate) struct NewArgs {
         short = 'A',
         visible_alias = "after",
         conflicts_with = "revisions",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::all_revisions),
     )]
     insert_after: Vec<RevisionArg>,
@@ -82,6 +87,7 @@ pub(crate) struct NewArgs {
         short = 'B',
         visible_alias = "before",
         conflicts_with = "revisions",
+        value_name = "REVSETS",
         add = ArgValueCandidates::new(complete::mutable_revisions),
     )]
     insert_before: Vec<RevisionArg>,

cli/src/commands/parallelize.rs

@@ -57,7 +57,10 @@ use crate::ui::Ui;
 #[command(verbatim_doc_comment)]
 pub(crate) struct ParallelizeArgs {
     /// Revisions to parallelize
-    #[arg(add = ArgValueCandidates::new(complete::mutable_revisions))]
+    #[arg(
+        value_name = "REVSETS",
+        add = ArgValueCandidates::new(complete::mutable_revisions)
+    )]
     revisions: Vec<RevisionArg>,
 }