cli: branch: add "move" command that can update branches by revset or…

… name

This basically supersedes the current "branch set" command. The plan is to turn
"branch set" into an "upsert" command, and deprecate "branch create". (martinvonz#3584)
Maybe we can also add "branch set --new" flag to only allow creation of new
branches. One reason behind this proposed change is that "set" usually allows
both "creation" and "update". However, we also need a typo-safe version of
"set" to not create new branches by accident.

"jj branch move" is useful when advancing ancestor branches. Let's say you've
added a couple of commits on top of an existing PR branch, you can advance the
branch by "jj branch move --from 'heads(::@- & branches())' --to @-". If this
pattern is super common, maybe we can add --advance flag for short.

One drawback of this change is that "git branch --move" is equivalent to
"jj branch rename". I personally don't find this is confusing, but it's true
that "move" sometimes means "rename".

CHANGELOG.md

@@ -52,6 +52,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * `jj file` now groups commands for working with files.
 
+* New command `jj branch move` let you update branches by name pattern or source
+  revision.
+
 ### Fixed bugs
 
 ## [0.18.0] - 2024-06-05

cli/src/commands/branch.rs

@@ -46,6 +46,8 @@ pub enum BranchCommand {
     Forget(BranchForgetArgs),
     #[command(visible_alias("l"))]
     List(BranchListArgs),
+    #[command(visible_alias("m"))]
+    Move(BranchMoveArgs),
     #[command(visible_alias("r"))]
     Rename(BranchRenameArgs),
     #[command(visible_alias("s"))]
@@ -183,6 +185,41 @@ pub struct BranchSetArgs {
     pub names: Vec<String>,
 }
 
+/// Move existing branches to target revision
+///
+/// If branch names are given, the specified branches will be updated to point
+/// to the target revision.
+///
+/// If `--from` options are given, branches currently pointing to the specified
+/// revisions will be updated. The branches can also be filtered by names.
+///
+/// Example: pull up the nearest branches to the working-copy parent
+///
+/// $ jj branch move --from 'heads(::@- & branches())' --to @-
+#[derive(clap::Args, Clone, Debug)]
+#[command(group(clap::ArgGroup::new("source").multiple(true).required(true)))]
+pub struct BranchMoveArgs {
+    /// Move branches from the given revisions
+    #[arg(long, group = "source", value_name = "REVISIONS")]
+    from: Vec<RevisionArg>,
+
+    /// Move branches to this revision
+    #[arg(long, default_value = "@", value_name = "REVISION")]
+    to: RevisionArg,
+
+    /// Allow moving branches backwards or sideways
+    #[arg(long, short = 'B')]
+    allow_backwards: bool,
+
+    /// Move branches matching the given name patterns
+    ///
+    /// By default, the specified name matches exactly. Use `glob:` prefix to
+    /// select branches by wildcard pattern. For details, see
+    /// https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
+    #[arg(group = "source", value_parser = StringPattern::parse)]
+    names: Vec<StringPattern>,
+}
+
 /// Start tracking given remote branches
 ///
 /// A tracking remote branch will be imported as a local branch of the same
@@ -234,6 +271,7 @@ pub fn cmd_branch(
         BranchCommand::Create(sub_args) => cmd_branch_create(ui, command, sub_args),
         BranchCommand::Rename(sub_args) => cmd_branch_rename(ui, command, sub_args),
         BranchCommand::Set(sub_args) => cmd_branch_set(ui, command, sub_args),
+        BranchCommand::Move(sub_args) => cmd_branch_move(ui, command, sub_args),
         BranchCommand::Delete(sub_args) => cmd_branch_delete(ui, command, sub_args),
         BranchCommand::Forget(sub_args) => cmd_branch_forget(ui, command, sub_args),
         BranchCommand::Track(sub_args) => cmd_branch_track(ui, command, sub_args),
@@ -391,6 +429,83 @@ fn cmd_branch_set(
     Ok(())
 }
 
+fn cmd_branch_move(
+    ui: &mut Ui,
+    command: &CommandHelper,
+    args: &BranchMoveArgs,
+) -> Result<(), CommandError> {
+    let mut workspace_command = command.workspace_helper(ui)?;
+    let repo = workspace_command.repo().as_ref();
+    let view = repo.view();
+
+    let branch_names = {
+        let is_source_commit = if !args.from.is_empty() {
+            workspace_command
+                .parse_union_revsets(&args.from)?
+                .evaluate()?
+                .containing_fn()
+        } else {
+            Box::new(|_: &CommitId| true)
+        };
+        if !args.names.is_empty() {
+            find_branches_with(&args.names, |pattern| {
+                view.local_branches_matching(pattern)
+                    .filter(|(_, target)| target.added_ids().any(&is_source_commit))
+                    .map(|(name, _)| name.to_owned())
+            })?
+        } else {
+            view.local_branches()
+                .filter(|(_, target)| target.added_ids().any(&is_source_commit))
+                .map(|(name, _)| name.to_owned())
+                .collect()
+        }
+    };
+    let target_commit = workspace_command.resolve_single_rev(&args.to)?;
+
+    if branch_names.is_empty() {
+        writeln!(ui.status(), "No branches to update.")?;
+        return Ok(());
+    }
+    if branch_names.len() > 1 {
+        writeln!(
+            ui.warning_default(),
+            "Updating multiple branches: {}",
+            branch_names.join(", "),
+        )?;
+        if args.names.is_empty() {
+            writeln!(ui.hint_default(), "Specify branch by name to update one.")?;
+        }
+    }
+
+    if !args.allow_backwards {
+        if let Some(name) = branch_names
+            .iter()
+            .find(|name| !is_fast_forward(repo, view.get_local_branch(name), target_commit.id()))
+        {
+            return Err(user_error_with_hint(
+                format!("Refusing to move branch backwards or sideways: {name}"),
+                "Use --allow-backwards to allow it.",
+            ));
+        }
+    }
+
+    let mut tx = workspace_command.start_transaction();
+    for name in &branch_names {
+        tx.mut_repo()
+            .set_local_branch_target(name, RefTarget::normal(target_commit.id().clone()));
+    }
+    tx.finish(
+        ui,
+        format!(
+            "point {} to commit {}",
+            make_branch_term(&branch_names),
+            target_commit.id().hex()
+        ),
+    )?;
+
+    Ok(())
+}
+
 fn find_local_branches(
     view: &View,
     name_patterns: &[StringPattern],

cli/tests/cli-reference@.md.snap

@@ -18,6 +18,7 @@ This document contains the help content for the `jj` command-line program.
 * [`jj branch delete`↴](#jj-branch-delete)
 * [`jj branch forget`↴](#jj-branch-forget)
 * [`jj branch list`↴](#jj-branch-list)
+* [`jj branch move`↴](#jj-branch-move)
 * [`jj branch rename`↴](#jj-branch-rename)
 * [`jj branch set`↴](#jj-branch-set)
 * [`jj branch track`↴](#jj-branch-track)
@@ -236,6 +237,7 @@ For information about branches, see https://github.com/martinvonz/jj/blob/main/d
 * `delete` — Delete an existing branch and propagate the deletion to remotes on the next push
 * `forget` — Forget everything about a branch, including its local and remote targets
 * `list` — List branches and their targets
+* `move` — Move existing branches to target revision
 * `rename` — Rename `old` branch name to `new` branch name
 * `set` — Update an existing branch to point to a certain commit
 * `track` — Start tracking given remote branches
@@ -321,6 +323,36 @@ For information about branches, see https://github.com/martinvonz/jj/blob/main/d
 
 
 
+## `jj branch move`
+
+Move existing branches to target revision
+
+If branch names are given, the specified branches will be updated to point to the target revision.
+
+If `--from` options are given, branches currently pointing to the specified revisions will be updated. The branches can also be filtered by names.
+
+Example: pull up the nearest branches to the working-copy parent
+
+$ jj branch move --from 'heads(::@- & branches())' --to @-
+
+**Usage:** `jj branch move [OPTIONS] <--from <REVISIONS>|NAMES>`
+
+###### **Arguments:**
+
+* `<NAMES>` — Move branches matching the given name patterns
+
+   By default, the specified name matches exactly. Use `glob:` prefix to select branches by wildcard pattern. For details, see https://github.com/martinvonz/jj/blob/main/docs/revsets.md#string-patterns.
+
+###### **Options:**
+
+* `--from <REVISIONS>` — Move branches from the given revisions
+* `--to <REVISION>` — Move branches to this revision
+
+  Default value: `@`
+* `-B`, `--allow-backwards` — Allow moving branches backwards or sideways
+
+
+
 ## `jj branch rename`
 
 Rename `old` branch name to `new` branch name.

cli/tests/test_branch_command.rs

@@ -101,6 +101,10 @@ fn test_branch_move() {
     Error: No such branch: foo
     Hint: Use `jj branch create` to create it.
     "###);
+    let stderr = test_env.jj_cmd_failure(&repo_path, &["branch", "move", "foo"]);
+    insta::assert_snapshot!(stderr, @r###"
+    Error: No such branch: foo
+    "###);
 
     let (_stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["branch", "create", "foo"]);
     insta::assert_snapshot!(stderr, @"");
@@ -126,6 +130,124 @@ fn test_branch_move() {
         &["branch", "set", "-r@-", "--allow-backwards", "foo"],
     );
     insta::assert_snapshot!(stderr, @"");
+
+    let (_stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["branch", "move", "foo"]);
+    insta::assert_snapshot!(stderr, @"");
+
+    let stderr = test_env.jj_cmd_failure(&repo_path, &["branch", "move", "--to=@-", "foo"]);
+    insta::assert_snapshot!(stderr, @r###"
+    Error: Refusing to move branch backwards or sideways: foo
+    Hint: Use --allow-backwards to allow it.
+    "###);
+
+    let (_stdout, stderr) = test_env.jj_cmd_ok(
+        &repo_path,
+        &["branch", "move", "--to=@-", "--allow-backwards", "foo"],
+    );
+    insta::assert_snapshot!(stderr, @"");
+}
+
+#[test]
+fn test_branch_move_matching() {
+    let test_env = TestEnvironment::default();
+    test_env.jj_cmd_ok(test_env.env_root(), &["git", "init", "repo"]);
+    let repo_path = test_env.env_root().join("repo");
+
+    test_env.jj_cmd_ok(&repo_path, &["branch", "create", "a1", "a2"]);
+    test_env.jj_cmd_ok(&repo_path, &["new", "-mhead1"]);
+    test_env.jj_cmd_ok(&repo_path, &["new", "root()"]);
+    test_env.jj_cmd_ok(&repo_path, &["branch", "create", "b1"]);
+    test_env.jj_cmd_ok(&repo_path, &["new"]);
+    test_env.jj_cmd_ok(&repo_path, &["branch", "create", "c1"]);
+    test_env.jj_cmd_ok(&repo_path, &["new", "-mhead2"]);
+    insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
+    @   a2781dd9ee37
+    ◉  c1 f4f38657a3dd
+    ◉  b1 f652c32197cf
+    │ ◉   6b5e840ea72b
+    │ ◉  a1 a2 230dd059e1b0
+    ├─╯
+    ◉   000000000000
+    "###);
+
+    // The default could be considered "--from=all() glob:*", but is disabled
+    let stderr = test_env.jj_cmd_cli_error(&repo_path, &["branch", "move"]);
+    insta::assert_snapshot!(stderr, @r###"
+    error: the following required arguments were not provided:
+      <--from <REVISIONS>|NAMES>
+
+    Usage: jj branch move <--from <REVISIONS>|NAMES>
+
+    For more information, try '--help'.
+    "###);
+
+    // No branches pointing to the source revisions
+    let (_stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["branch", "move", "--from=none()"]);
+    insta::assert_snapshot!(stderr, @r###"
+    No branches to update.
+    "###);
+
+    // No matching branches within the source revisions
+    let stderr = test_env.jj_cmd_failure(&repo_path, &["branch", "move", "--from=::@", "glob:a?"]);
+    insta::assert_snapshot!(stderr, @r###"
+    Error: No matching branches for patterns: a?
+    "###);
+
+    // Noop move
+    let (_stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["branch", "move", "--to=a1", "a2"]);
+    insta::assert_snapshot!(stderr, @r###"
+    Nothing changed.
+    "###);
+
+    // Move from multiple revisions
+    let (_stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["branch", "move", "--from=::@"]);
+    insta::assert_snapshot!(stderr, @r###"
+    Warning: Updating multiple branches: b1, c1
+    Hint: Specify branch by name to update one.
+    "###);
+    insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
+    @  b1 c1 a2781dd9ee37
+    ◉   f4f38657a3dd
+    ◉   f652c32197cf
+    │ ◉   6b5e840ea72b
+    │ ◉  a1 a2 230dd059e1b0
+    ├─╯
+    ◉   000000000000
+    "###);
+    test_env.jj_cmd_ok(&repo_path, &["undo"]);
+
+    // Try to move multiple branches, but one of them isn't fast-forward
+    let stderr = test_env.jj_cmd_failure(&repo_path, &["branch", "move", "glob:?1"]);
+    insta::assert_snapshot!(stderr, @r###"
+    Warning: Updating multiple branches: a1, b1, c1
+    Error: Refusing to move branch backwards or sideways: a1
+    Hint: Use --allow-backwards to allow it.
+    "###);
+    insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
+    @   a2781dd9ee37
+    ◉  c1 f4f38657a3dd
+    ◉  b1 f652c32197cf
+    │ ◉   6b5e840ea72b
+    │ ◉  a1 a2 230dd059e1b0
+    ├─╯
+    ◉   000000000000
+    "###);
+
+    // Select by revision and name
+    let (_stdout, stderr) = test_env.jj_cmd_ok(
+        &repo_path,
+        &["branch", "move", "--from=::a1+", "--to=a1+", "glob:?1"],
+    );
+    insta::assert_snapshot!(stderr, @"");
+    insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
+    @   a2781dd9ee37
+    ◉  c1 f4f38657a3dd
+    ◉  b1 f652c32197cf
+    │ ◉  a1 6b5e840ea72b
+    │ ◉  a2 230dd059e1b0
+    ├─╯
+    ◉   000000000000
+    "###);
 }
 
 #[test]