From fd10017b20f456250ef91911bce10ab636984f4e Mon Sep 17 00:00:00 2001 From: Martin von Zweigbergk Date: Tue, 17 Dec 2024 22:16:00 -0800 Subject: [PATCH 1/2] cli: refer to fileset argument using `FILESETS` in synopsis This should help clarify that the arguments are not just simple paths (assuming `ui.allow-filesets` is not disabled). --- cli/src/commands/absorb.rs | 2 +- cli/src/commands/commit.rs | 1 + cli/src/commands/debug/tree.rs | 1 + cli/src/commands/diff.rs | 1 + cli/src/commands/file/chmod.rs | 1 + cli/src/commands/file/list.rs | 2 +- cli/src/commands/file/show.rs | 1 + cli/src/commands/file/track.rs | 2 +- cli/src/commands/file/untrack.rs | 1 + cli/src/commands/fix.rs | 2 +- cli/src/commands/interdiff.rs | 1 + cli/src/commands/log.rs | 1 + cli/src/commands/resolve.rs | 1 + cli/src/commands/restore.rs | 1 + cli/src/commands/split.rs | 7 ++- cli/src/commands/squash.rs | 1 + cli/src/commands/status.rs | 2 +- cli/tests/cli-reference@.md.snap | 60 +++++++++---------- cli/tests/test_alias.rs | 2 +- cli/tests/test_diff_command.rs | 4 +- cli/tests/test_file_track_untrack_commands.rs | 4 +- cli/tests/test_global_opts.rs | 2 +- cli/tests/test_log_command.rs | 2 +- cli/tests/test_squash_command.rs | 2 +- 24 files changed, 58 insertions(+), 46 deletions(-) diff --git a/cli/src/commands/absorb.rs b/cli/src/commands/absorb.rs index 6aa5c7357d..05046f41fe 100644 --- a/cli/src/commands/absorb.rs +++ b/cli/src/commands/absorb.rs @@ -52,7 +52,7 @@ pub(crate) struct AbsorbArgs { )] into: Vec, /// Move only changes to these paths (instead of all paths) - #[arg(value_hint = clap::ValueHint::AnyPath)] + #[arg(value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath)] paths: Vec, } diff --git a/cli/src/commands/commit.rs b/cli/src/commands/commit.rs index e1caf405aa..80ee6a1c2c 100644 --- a/cli/src/commands/commit.rs +++ b/cli/src/commands/commit.rs @@ -42,6 +42,7 @@ pub(crate) struct CommitArgs { message_paragraphs: Vec, /// Put these paths in the first commit #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::modified_files), )] diff --git a/cli/src/commands/debug/tree.rs b/cli/src/commands/debug/tree.rs index 479276e4ff..3255082029 100644 --- a/cli/src/commands/debug/tree.rs +++ b/cli/src/commands/debug/tree.rs @@ -35,6 +35,7 @@ pub struct DebugTreeArgs { id: Option, #[arg(long, requires = "id")] dir: Option, + #[arg(value_name = "FILESETS")] paths: Vec, // TODO: Add an option to include trees that are ancestors of the matched paths } diff --git a/cli/src/commands/diff.rs b/cli/src/commands/diff.rs index b3a1c28409..1ccc9659ec 100644 --- a/cli/src/commands/diff.rs +++ b/cli/src/commands/diff.rs @@ -59,6 +59,7 @@ pub(crate) struct DiffArgs { to: Option, /// Restrict the diff to these paths #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::modified_revision_or_range_files), )] diff --git a/cli/src/commands/file/chmod.rs b/cli/src/commands/file/chmod.rs index 866a89cf2c..886202b4b0 100644 --- a/cli/src/commands/file/chmod.rs +++ b/cli/src/commands/file/chmod.rs @@ -55,6 +55,7 @@ pub(crate) struct FileChmodArgs { /// Paths to change the executable bit for #[arg( required = true, + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::all_revision_files), )] diff --git a/cli/src/commands/file/list.rs b/cli/src/commands/file/list.rs index 202fda788c..d3315c8500 100644 --- a/cli/src/commands/file/list.rs +++ b/cli/src/commands/file/list.rs @@ -34,7 +34,7 @@ pub(crate) struct FileListArgs { )] revision: RevisionArg, /// Only list files matching these prefixes (instead of all files) - #[arg(value_hint = clap::ValueHint::AnyPath)] + #[arg(value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath)] paths: Vec, } diff --git a/cli/src/commands/file/show.rs b/cli/src/commands/file/show.rs index 29057efde8..2f07ae9092 100644 --- a/cli/src/commands/file/show.rs +++ b/cli/src/commands/file/show.rs @@ -54,6 +54,7 @@ pub(crate) struct FileShowArgs { /// Paths to print #[arg( required = true, + value_name = "FILESETS", value_hint = clap::ValueHint::FilePath, add = ArgValueCompleter::new(complete::all_revision_files), )] diff --git a/cli/src/commands/file/track.rs b/cli/src/commands/file/track.rs index 68d1a8435e..352292c3d7 100644 --- a/cli/src/commands/file/track.rs +++ b/cli/src/commands/file/track.rs @@ -34,7 +34,7 @@ use crate::ui::Ui; #[derive(clap::Args, Clone, Debug)] pub(crate) struct FileTrackArgs { /// Paths to track - #[arg(required = true, value_hint = clap::ValueHint::AnyPath)] + #[arg(required = true, value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath)] paths: Vec, } diff --git a/cli/src/commands/file/untrack.rs b/cli/src/commands/file/untrack.rs index be0314735e..6271546da3 100644 --- a/cli/src/commands/file/untrack.rs +++ b/cli/src/commands/file/untrack.rs @@ -38,6 +38,7 @@ pub(crate) struct FileUntrackArgs { /// colocated repos). #[arg( required = true, + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::all_revision_files), )] diff --git a/cli/src/commands/fix.rs b/cli/src/commands/fix.rs index cbbdedfa81..ff9211edfe 100644 --- a/cli/src/commands/fix.rs +++ b/cli/src/commands/fix.rs @@ -129,7 +129,7 @@ pub(crate) struct FixArgs { #[arg(long, short, add = ArgValueCandidates::new(complete::mutable_revisions))] source: Vec, /// Fix only these paths - #[arg(value_hint = clap::ValueHint::AnyPath)] + #[arg(value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath)] paths: Vec, /// Fix unchanged files in addition to changed ones. If no paths are /// specified, all files in the repo will be fixed. diff --git a/cli/src/commands/interdiff.rs b/cli/src/commands/interdiff.rs index d577e22bdf..a0b3e4afd0 100644 --- a/cli/src/commands/interdiff.rs +++ b/cli/src/commands/interdiff.rs @@ -44,6 +44,7 @@ pub(crate) struct InterdiffArgs { to: Option, /// Restrict the diff to these paths #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::interdiff_files), )] diff --git a/cli/src/commands/log.rs b/cli/src/commands/log.rs index 03ef5735b6..8f47117b7a 100644 --- a/cli/src/commands/log.rs +++ b/cli/src/commands/log.rs @@ -67,6 +67,7 @@ pub(crate) struct LogArgs { revisions: Vec, /// Show revisions modifying the given paths #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::log_files), )] diff --git a/cli/src/commands/resolve.rs b/cli/src/commands/resolve.rs index bd29479ab1..f12ead62bc 100644 --- a/cli/src/commands/resolve.rs +++ b/cli/src/commands/resolve.rs @@ -64,6 +64,7 @@ pub(crate) struct ResolveArgs { /// the `--list` argument to find paths to use here. // TODO: Find the conflict we can resolve even if it's not the first one. #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::revision_conflicted_files), )] diff --git a/cli/src/commands/restore.rs b/cli/src/commands/restore.rs index 5262dd6e3d..60efffd0e4 100644 --- a/cli/src/commands/restore.rs +++ b/cli/src/commands/restore.rs @@ -47,6 +47,7 @@ use crate::ui::Ui; pub(crate) struct RestoreArgs { /// Restore only these paths (instead of all paths) #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::modified_range_files), )] diff --git a/cli/src/commands/split.rs b/cli/src/commands/split.rs index a33f01f384..1b7c984313 100644 --- a/cli/src/commands/split.rs +++ b/cli/src/commands/split.rs @@ -69,10 +69,11 @@ pub(crate) struct SplitArgs { parallel: bool, /// Files matching any of these filesets are put in the first commit #[arg( + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::modified_revision_files), )] - filesets: Vec, + paths: Vec, } #[instrument(skip_all)] @@ -92,12 +93,12 @@ pub(crate) fn cmd_split( workspace_command.check_rewritable([commit.id()])?; let matcher = workspace_command - .parse_file_patterns(ui, &args.filesets)? + .parse_file_patterns(ui, &args.paths)? .to_matcher(); let diff_selector = workspace_command.diff_selector( ui, args.tool.as_deref(), - args.interactive || args.filesets.is_empty(), + args.interactive || args.paths.is_empty(), )?; let mut tx = workspace_command.start_transaction(); let end_tree = commit.tree()?; diff --git a/cli/src/commands/squash.rs b/cli/src/commands/squash.rs index 462fec1e8c..81ca33e5cf 100644 --- a/cli/src/commands/squash.rs +++ b/cli/src/commands/squash.rs @@ -93,6 +93,7 @@ pub(crate) struct SquashArgs { /// Move only changes to these paths (instead of all paths) #[arg( conflicts_with_all = ["interactive", "tool"], + value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath, add = ArgValueCompleter::new(complete::squash_revision_files), )] diff --git a/cli/src/commands/status.rs b/cli/src/commands/status.rs index baaca96c46..bf91c26abf 100644 --- a/cli/src/commands/status.rs +++ b/cli/src/commands/status.rs @@ -37,7 +37,7 @@ use crate::ui::Ui; #[command(visible_alias = "st")] pub(crate) struct StatusArgs { /// Restrict the status display to these paths - #[arg(value_hint = clap::ValueHint::AnyPath)] + #[arg(value_name = "FILESETS", value_hint = clap::ValueHint::AnyPath)] paths: Vec, } diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap index acb1e46dde..f32e26a945 100644 --- a/cli/tests/cli-reference@.md.snap +++ b/cli/tests/cli-reference@.md.snap @@ -232,11 +232,11 @@ This command splits changes in the source revision and moves each change to the The modification made by `jj absorb` can be reviewed by `jj op show -p`. -**Usage:** `jj absorb [OPTIONS] [PATHS]...` +**Usage:** `jj absorb [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Move only changes to these paths (instead of all paths) +* `` — Move only changes to these paths (instead of all paths) ###### **Options:** @@ -475,11 +475,11 @@ A non-tracking remote bookmark is just a pointer to the last-fetched remote book Update the description and create a new change on top -**Usage:** `jj commit [OPTIONS] [PATHS]...` +**Usage:** `jj commit [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Put these paths in the first commit +* `` — Put these paths in the first commit ###### **Options:** @@ -683,11 +683,11 @@ With the `-r` option, which is the default, shows the changes compared to the pa With the `--from` and/or `--to` options, shows the difference from/to the given revisions. If either is left out, it defaults to the working-copy commit. For example, `jj diff --from main` shows the changes from "main" (perhaps a bookmark name) to the working-copy commit. -**Usage:** `jj diff [OPTIONS] [PATHS]...` +**Usage:** `jj diff [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Restrict the diff to these paths +* `` — Restrict the diff to these paths ###### **Options:** @@ -864,7 +864,7 @@ Sets or removes the executable bit for paths in the repo Unlike the POSIX `chmod`, `jj file chmod` also works on Windows, on conflicted files, and on arbitrary revisions. -**Usage:** `jj file chmod [OPTIONS] ...` +**Usage:** `jj file chmod [OPTIONS] ...` ###### **Arguments:** @@ -876,7 +876,7 @@ Unlike the POSIX `chmod`, `jj file chmod` also works on Windows, on conflicted f - `x`: Make a path executable (alias: executable) -* `` — Paths to change the executable bit for +* `` — Paths to change the executable bit for ###### **Options:** @@ -890,11 +890,11 @@ Unlike the POSIX `chmod`, `jj file chmod` also works on Windows, on conflicted f List files in a revision -**Usage:** `jj file list [OPTIONS] [PATHS]...` +**Usage:** `jj file list [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Only list files matching these prefixes (instead of all files) +* `` — Only list files matching these prefixes (instead of all files) ###### **Options:** @@ -910,11 +910,11 @@ Print contents of files in a revision If the given path is a directory, files in the directory will be visited recursively. -**Usage:** `jj file show [OPTIONS] ...` +**Usage:** `jj file show [OPTIONS] ...` ###### **Arguments:** -* `` — Paths to print +* `` — Paths to print ###### **Options:** @@ -932,11 +932,11 @@ Without arguments, all paths that are not ignored will be tracked. New files in the working copy can be automatically tracked. You can configure which paths to automatically track by setting `snapshot.auto-track` (e.g. to `"none()"` or `"glob:**/*.rs"`). Files that don't match the pattern can be manually tracked using this command. The default pattern is `all()` and this command has no effect. -**Usage:** `jj file track ...` +**Usage:** `jj file track ...` ###### **Arguments:** -* `` — Paths to track +* `` — Paths to track @@ -944,11 +944,11 @@ New files in the working copy can be automatically tracked. You can configure wh Stop tracking specified paths in the working copy -**Usage:** `jj file untrack ...` +**Usage:** `jj file untrack ...` ###### **Arguments:** -* `` — Paths to untrack. They must already be ignored. +* `` — Paths to untrack. They must already be ignored. The paths could be ignored via a .gitignore or .git/info/exclude (in colocated repos). @@ -1022,11 +1022,11 @@ The tool defined by `tool-command` acts as if it was the first entry in `fix.tools`, and uses `pattern = "all()"``. Support for `tool-command` will be removed in a future version. -**Usage:** `jj fix [OPTIONS] [PATHS]...` +**Usage:** `jj fix [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Fix only these paths +* `` — Fix only these paths ###### **Options:** @@ -1321,11 +1321,11 @@ Compare the changes of two commits This excludes changes from other commits by temporarily rebasing `--from` onto `--to`'s parents. If you wish to compare the same change across versions, consider `jj evolog -p` instead. -**Usage:** `jj interdiff [OPTIONS] <--from |--to > [PATHS]...` +**Usage:** `jj interdiff [OPTIONS] <--from |--to > [FILESETS]...` ###### **Arguments:** -* `` — Restrict the diff to these paths +* `` — Restrict the diff to these paths ###### **Options:** @@ -1358,11 +1358,11 @@ Spans of revisions that are not included in the graph per `--revisions` are rend The working-copy commit is indicated by a `@` symbol in the graph. Immutable revisions (https://jj-vcs.github.io/jj/latest/config/#set-of-immutable-commits) have a `◆` symbol. Other commits have a `○` symbol. To customize these symbols, see https://jj-vcs.github.io/jj/latest/config/#node-style. -**Usage:** `jj log [OPTIONS] [PATHS]...` +**Usage:** `jj log [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Show revisions modifying the given paths +* `` — Show revisions modifying the given paths ###### **Options:** @@ -1890,11 +1890,11 @@ Only conflicts that can be resolved with a 3-way merge are supported. See docs f Note that conflicts can also be resolved without using this command. You may edit the conflict markers in the conflicted file directly with a text editor. -**Usage:** `jj resolve [OPTIONS] [PATHS]...` +**Usage:** `jj resolve [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Restrict to these paths when searching for a conflict to resolve. We will attempt to resolve the first conflict we can find. You can use the `--list` argument to find paths to use here +* `` — Restrict to these paths when searching for a conflict to resolve. We will attempt to resolve the first conflict we can find. You can use the `--list` argument to find paths to use here ###### **Options:** @@ -1918,11 +1918,11 @@ When neither `--from` nor `--to` is specified, the command restores into the wor See `jj diffedit` if you'd like to restore portions of files rather than entire files. -**Usage:** `jj restore [OPTIONS] [PATHS]...` +**Usage:** `jj restore [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Restore only these paths (instead of all paths) +* `` — Restore only these paths (instead of all paths) ###### **Options:** @@ -2100,11 +2100,11 @@ If the source was abandoned and both the source and destination had a non-empty If a working-copy commit gets abandoned, it will be given a new, empty commit. This is true in general; it is not specific to this command. -**Usage:** `jj squash [OPTIONS] [PATHS]...` +**Usage:** `jj squash [OPTIONS] [FILESETS]...` ###### **Arguments:** -* `` — Move only changes to these paths (instead of all paths) +* `` — Move only changes to these paths (instead of all paths) ###### **Options:** @@ -2127,11 +2127,11 @@ This includes: * The working copy commit and its (first) parent, and a summary of the changes between them * Conflicted bookmarks (see https://jj-vcs.github.io/jj/latest/bookmarks/) -**Usage:** `jj status [PATHS]...` +**Usage:** `jj status [FILESETS]...` ###### **Arguments:** -* `` — Restrict the status display to these paths +* `` — Restrict the status display to these paths diff --git a/cli/tests/test_alias.rs b/cli/tests/test_alias.rs index 533e734655..1d926491c5 100644 --- a/cli/tests/test_alias.rs +++ b/cli/tests/test_alias.rs @@ -110,7 +110,7 @@ fn test_alias_calls_command_with_invalid_option() { tip: to pass '--nonexistent' as a value, use '-- --nonexistent' - Usage: jj log [OPTIONS] [PATHS]... + Usage: jj log [OPTIONS] [FILESETS]... For more information, try '--help'. "###); diff --git a/cli/tests/test_diff_command.rs b/cli/tests/test_diff_command.rs index 2632812467..5e5ad4cec9 100644 --- a/cli/tests/test_diff_command.rs +++ b/cli/tests/test_diff_command.rs @@ -497,7 +497,7 @@ fn test_diff_bad_args() { insta::assert_snapshot!(stderr, @r###" error: the argument '--summary' cannot be used with '--types' - Usage: jj diff --summary [PATHS]... + Usage: jj diff --summary [FILESETS]... For more information, try '--help'. "###); @@ -506,7 +506,7 @@ fn test_diff_bad_args() { insta::assert_snapshot!(stderr, @r###" error: the argument '--color-words' cannot be used with '--git' - Usage: jj diff --color-words [PATHS]... + Usage: jj diff --color-words [FILESETS]... For more information, try '--help'. "###); diff --git a/cli/tests/test_file_track_untrack_commands.rs b/cli/tests/test_file_track_untrack_commands.rs index a9df82a5a7..2d6d2bef0f 100644 --- a/cli/tests/test_file_track_untrack_commands.rs +++ b/cli/tests/test_file_track_untrack_commands.rs @@ -48,9 +48,9 @@ fn test_track_untrack() { let stderr = test_env.jj_cmd_cli_error(&repo_path, &["file", "untrack"]); insta::assert_snapshot!(stderr, @r###" error: the following required arguments were not provided: - ... + ... - Usage: jj file untrack ... + Usage: jj file untrack ... For more information, try '--help'. "###); diff --git a/cli/tests/test_global_opts.rs b/cli/tests/test_global_opts.rs index cc6ffa3ae4..8c148020e7 100644 --- a/cli/tests/test_global_opts.rs +++ b/cli/tests/test_global_opts.rs @@ -578,7 +578,7 @@ fn test_early_args() { let stdout = test_env.jj_cmd_success(test_env.env_root(), &["log", "--help", "--color=always"]); insta::assert_snapshot!( stdout.lines().find(|l| l.contains("Usage:")).unwrap(), - @"Usage: jj log [OPTIONS] [PATHS]..."); + @"Usage: jj log [OPTIONS] [FILESETS]..."); // Early args are parsed with clap's ignore_errors(), but there is a known // bug that causes defaults to be unpopulated. Test that the early args are diff --git a/cli/tests/test_log_command.rs b/cli/tests/test_log_command.rs index d8453b2fd7..c2ea461061 100644 --- a/cli/tests/test_log_command.rs +++ b/cli/tests/test_log_command.rs @@ -210,7 +210,7 @@ fn test_log_with_or_without_diff() { insta::assert_snapshot!(stderr, @r###" error: the argument '--git' cannot be used with '--color-words' - Usage: jj log --template