diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1187472047..43720007f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,17 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   that describes them better, and they also behave similar to Mercurial's
   bookmarks.
 
+* `jj unsquash` has been deprecated in favor of `jj squash` and
+  `jj diffedit --restore-descendants`.
+
+  **Rationale:** `jj squash` can be used in interactive mode to pull
+  changes from one commit to another, including from a parent commit
+  to a child commit. For fine-grained dependent diffs, such as when
+  the parent and the child commits must successively modify the same
+  location in a file, `jj diffedit --restore-descendants` can be used
+  to set the parent commit to the desired content without altering the
+  content of the child commit.
+
 * The `git.push-branch-prefix` config has been deprecated in favor of
   `git.push-bookmark-prefix`.
 
diff --git a/cli/src/commands/diffedit.rs b/cli/src/commands/diffedit.rs
index 3ab5c901fb..08211bce90 100644
--- a/cli/src/commands/diffedit.rs
+++ b/cli/src/commands/diffedit.rs
@@ -42,8 +42,7 @@ use crate::ui::Ui;
 /// rebased on top as usual, which may result in conflicts.
 ///
 /// See `jj restore` if you want to move entire files from one revision to
-/// another. See `jj squash -i` or `jj unsquash -i` if you instead want to move
-/// changes into or out of the parent revision.
+/// another. For moving changes between revisions, see `jj squash -i`.
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct DiffeditArgs {
     /// The revision to touch up
diff --git a/cli/src/commands/mod.rs b/cli/src/commands/mod.rs
index 52c03c1743..97011dce12 100644
--- a/cli/src/commands/mod.rs
+++ b/cli/src/commands/mod.rs
@@ -156,6 +156,8 @@ enum Command {
     Util(util::UtilCommand),
     /// Undo an operation (shortcut for `jj op undo`)
     Undo(operation::undo::OperationUndoArgs),
+    // TODO: Delete `unsquash` in jj 0.28+
+    #[command(hide = true)]
     Unsquash(unsquash::UnsquashArgs),
     // TODO: Delete `untrack` in jj 0.27+
     #[command(hide = true)]
diff --git a/cli/src/commands/unsquash.rs b/cli/src/commands/unsquash.rs
index 8368b2087e..220e4f7211 100644
--- a/cli/src/commands/unsquash.rs
+++ b/cli/src/commands/unsquash.rs
@@ -56,6 +56,15 @@ pub(crate) fn cmd_unsquash(
     command: &CommandHelper,
     args: &UnsquashArgs,
 ) -> Result<(), CommandError> {
+    writeln!(
+        ui.warning_default(),
+        "`jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` \
+         instead"
+    )?;
+    writeln!(
+        ui.warning_default(),
+        "`jj unsquash` will be removed in a future version, and this will be a hard error"
+    )?;
     let mut workspace_command = command.workspace_helper(ui)?;
     let commit = workspace_command.resolve_single_rev(ui, &args.revision)?;
     workspace_command.check_rewritable([commit.id()])?;
diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap
index 395c88c739..dd6947d78f 100644
--- a/cli/tests/cli-reference@.md.snap
+++ b/cli/tests/cli-reference@.md.snap
@@ -92,7 +92,6 @@ This document contains the help content for the `jj` command-line program.
 * [`jj util markdown-help`↴](#jj-util-markdown-help)
 * [`jj util config-schema`↴](#jj-util-config-schema)
 * [`jj undo`↴](#jj-undo)
-* [`jj unsquash`↴](#jj-unsquash)
 * [`jj version`↴](#jj-version)
 * [`jj workspace`↴](#jj-workspace)
 * [`jj workspace add`↴](#jj-workspace-add)
@@ -146,7 +145,6 @@ To get started, see the tutorial at https://martinvonz.github.io/jj/latest/tutor
 * `tag` — Manage tags
 * `util` — Infrequently used commands such as for generating shell completions
 * `undo` — Undo an operation (shortcut for `jj op undo`)
-* `unsquash` — Move changes from a revision's parent into the revision
 * `version` — Display version information
 * `workspace` — Commands for working with workspaces
 
@@ -657,7 +655,7 @@ With the `--from` and/or `--to` options, starts a [diff editor] comparing the "f
 
 Edit the right side of the diff until it looks the way you want. Once you close the editor, the revision specified with `-r` or `--to` will be updated. Unless `--restore-descendants` is used, descendants will be rebased on top as usual, which may result in conflicts.
 
-See `jj restore` if you want to move entire files from one revision to another. See `jj squash -i` or `jj unsquash -i` if you instead want to move changes into or out of the parent revision.
+See `jj restore` if you want to move entire files from one revision to another. For moving changes between revisions, see `jj squash -i`.
 
 **Usage:** `jj diffedit [OPTIONS]`
 
@@ -2113,28 +2111,6 @@ Undo an operation (shortcut for `jj op undo`)
 
 
 
-## `jj unsquash`
-
-Move changes from a revision's parent into the revision
-
-After moving the changes out of the parent, the child revision will have the same content state as before. If moving the change out of the parent change made it empty compared to its parent, it will be abandoned. Without `--interactive`, the parent change will always become empty.
-
-If the source became empty and both the source and destination had a non-empty description, you will be asked for the combined description. If either was empty, then the other one will be used.
-
-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 unsquash [OPTIONS]`
-
-###### **Options:**
-
-* `-r`, `--revision <REVISION>`
-
-  Default value: `@`
-* `-i`, `--interactive` — Interactively choose which parts to unsquash
-* `--tool <NAME>` — Specify diff editor to be used (implies --interactive)
-
-
-
 ## `jj version`
 
 Display version information
diff --git a/cli/tests/test_immutable_commits.rs b/cli/tests/test_immutable_commits.rs
index f29a7d37a4..c5d9d3f30b 100644
--- a/cli/tests/test_immutable_commits.rs
+++ b/cli/tests/test_immutable_commits.rs
@@ -326,8 +326,10 @@ fn test_rewrite_immutable_commands() {
     "###);
     // unsquash
     let stderr = test_env.jj_cmd_failure(&repo_path, &["unsquash", "-r=main"]);
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Error: Commit 1d5af877b8bb is immutable
     Hint: Pass `--ignore-immutable` or configure the set of immutable commits via `revset-aliases.immutable_heads()`.
-    "###);
+    "#);
 }
diff --git a/cli/tests/test_unsquash_command.rs b/cli/tests/test_unsquash_command.rs
index f306cea7f2..6dd6ec51b9 100644
--- a/cli/tests/test_unsquash_command.rs
+++ b/cli/tests/test_unsquash_command.rs
@@ -42,10 +42,12 @@ fn test_unsquash() {
     // Unsquashes into the working copy from its parent by default
     let (stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["unsquash"]);
     insta::assert_snapshot!(stdout, @"");
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Working copy now at: mzvwutvl 9177132c c | (no description set)
     Parent commit      : qpvuntsm 184ddbcc a b | (no description set)
-    "###);
+    "#);
     insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
     @  9177132cfbb9 c
     ○  184ddbcce5a9 a b
@@ -60,11 +62,13 @@ fn test_unsquash() {
     test_env.jj_cmd_ok(&repo_path, &["undo"]);
     let (stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["unsquash", "-r", "b"]);
     insta::assert_snapshot!(stdout, @"");
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Rebased 1 descendant commits
     Working copy now at: mzvwutvl b353b29c c | (no description set)
     Parent commit      : kkmpptxz 27772b15 b | (no description set)
-    "###);
+    "#);
     insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
     @  b353b29c423d c
     ○  27772b156771 b
@@ -99,20 +103,24 @@ fn test_unsquash() {
     ◆  000000000000
     "###);
     let stderr = test_env.jj_cmd_failure(&repo_path, &["unsquash"]);
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Error: Cannot unsquash merge commits
-    "###);
+    "#);
 
     // Can unsquash from a merge commit
     test_env.jj_cmd_ok(&repo_path, &["new", "e"]);
     std::fs::write(repo_path.join("file1"), "e\n").unwrap();
     let (stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["unsquash"]);
     insta::assert_snapshot!(stdout, @"");
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Working copy now at: pzsxstzt bd05eb69 merge
     Parent commit      : mzvwutvl 382c9bad c e?? | (no description set)
     Parent commit      : xznxytkn f86e2b3a d e?? | (no description set)
-    "###);
+    "#);
     insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
     @    bd05eb698d1e
     ├─╮
@@ -160,11 +168,13 @@ fn test_unsquash_partial() {
     std::fs::write(&edit_script, "dump JJ-INSTRUCTIONS instrs").unwrap();
     let (stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["unsquash", "-r", "b", "-i"]);
     insta::assert_snapshot!(stdout, @"");
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Rebased 1 descendant commits
     Working copy now at: mzvwutvl 8802263d c | (no description set)
     Parent commit      : kkmpptxz 5bd83140 b | (no description set)
-    "###);
+    "#);
 
     insta::assert_snapshot!(
         std::fs::read_to_string(test_env.env_root().join("instrs")).unwrap(), @r###"
@@ -195,10 +205,12 @@ fn test_unsquash_partial() {
     std::fs::write(edit_script, "reset file1").unwrap();
     let (stdout, stderr) = test_env.jj_cmd_ok(&repo_path, &["unsquash", "-i"]);
     insta::assert_snapshot!(stdout, @"");
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Working copy now at: mzvwutvl a896ffde c | (no description set)
     Parent commit      : kkmpptxz 904111b4 b | (no description set)
-    "###);
+    "#);
     insta::assert_snapshot!(get_log_output(&test_env, &repo_path), @r###"
     @  a896ffdebb85 c
     ○  904111b4d3c4 b
@@ -233,10 +245,12 @@ fn test_unsquash_partial() {
         ],
     );
     insta::assert_snapshot!(stdout, @"");
-    insta::assert_snapshot!(stderr, @r###"
+    insta::assert_snapshot!(stderr, @r#"
+    Warning: `jj unsquash` is deprecated; use `jj diffedit --restore-descendants` or `jj squash` instead
+    Warning: `jj unsquash` will be removed in a future version, and this will be a hard error
     Working copy now at: mzvwutvl aaca9268 c | (no description set)
     Parent commit      : kkmpptxz fe8eb117 b | (no description set)
-    "###);
+    "#);
     let stdout = test_env.jj_cmd_success(&repo_path, &["file", "show", "file1", "-r", "b"]);
     insta::assert_snapshot!(stdout, @r###"
     a
diff --git a/docs/tutorial.md b/docs/tutorial.md
index 76f8fc2a77..d7688da53c 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -507,7 +507,6 @@ line. Unlike `jj squash -i`, which left the content state of the commit
 unchanged, `jj diffedit` (typically) results in a different state, which means
 that descendant commits may have conflicts.
 
-Other commands for rewriting contents of existing commits are `jj split`, `jj
-unsquash -i`. Now that you've seen how `jj squash -i` and `jj diffedit` work,
-you can hopefully figure out how those work (with the help of the instructions
-in the diff).
+Another command for rewriting contents of existing commits is `jj split`. Now that
+you've seen how `jj squash -i` and `jj diffedit` work, you can hopefully figure out
+how it works (with the help of the instructions in the diff).