From e056456b58d155dfd49fbef4c266c667ad1fa0f3 Mon Sep 17 00:00:00 2001 From: Khionu Sybiern Date: Thu, 7 Mar 2024 13:16:16 -0800 Subject: [PATCH] docs: add FAQ for why to use new-then-amend over edit --- cli/src/commands/edit.rs | 2 ++ cli/tests/cli-reference@.md.snap | 2 ++ docs/FAQ.md | 11 +++++++++++ 3 files changed, 15 insertions(+) diff --git a/cli/src/commands/edit.rs b/cli/src/commands/edit.rs index 48dd7022f12..c6be0f975fe 100644 --- a/cli/src/commands/edit.rs +++ b/cli/src/commands/edit.rs @@ -26,6 +26,8 @@ use crate::ui::Ui; /// Note: it is generally recommended to instead to use `jj new` and `jj /// squash`. Creating a new revision enables being more intentional with respect /// to the existing revision. +/// +/// For more information, see https://github.com/martinvonz/jj/blob/main/docs/FAQ.md#how-do-i-resume-working-on-an-existing-change #[derive(clap::Args, Clone, Debug)] pub(crate) struct EditArgs { /// The commit to edit diff --git a/cli/tests/cli-reference@.md.snap b/cli/tests/cli-reference@.md.snap index 923a0f2b730..c6e3e3f72af 100644 --- a/cli/tests/cli-reference@.md.snap +++ b/cli/tests/cli-reference@.md.snap @@ -711,6 +711,8 @@ Sets the specified revision as the working-copy revision Note: it is generally recommended to instead to use `jj new` and `jj squash`. Creating a new revision enables being more intentional with respect to the existing revision. +For more information, see https://github.com/martinvonz/jj/blob/main/docs/FAQ.md#how-do-i-resume-working-on-an-existing-change + **Usage:** `jj edit ` ###### **Arguments:** diff --git a/docs/FAQ.md b/docs/FAQ.md index 0315c701b5b..dd5ec9d53c0 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -137,6 +137,17 @@ commit, then run `jj restore --from Y --to @-` to restore the parent commit to the old state, and `jj restore --from X` to restore the new working-copy commit to the new state. +### How do I resume working on an existing change? + +There are two ways to resume working on an earlier change: `jj new` then `jj squash`, +and `jj edit`. The first is generally recommended over the second because at this +point, your earlier change could have developed a conflict. In that case`jj edit` +would restore the state with plain-text conflict annotations. Editing those +annotations incorrectly or by accident can lead to undesired output from conflict +resolution. To avoid this, you use `jj new ` to create a change based on your +earlier revision, make your edits, then use `jj squash`. Your earlier revision will +now be updated with the new edits. + ### How do I deal with divergent changes ('??' after the [change ID])? A [divergent change][glossary_divergent_change] represents a change that has two