From 3bbc3e5715eba28e79dad7528ccd8e9bc37b505b 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 | 14 ++++++++++++++ 3 files changed, 18 insertions(+) diff --git a/cli/src/commands/edit.rs b/cli/src/commands/edit.rs index 65bd2d6bcd..3ab8495ca2 100644 --- a/cli/src/commands/edit.rs +++ b/cli/src/commands/edit.rs @@ -25,6 +25,8 @@ use crate::ui::Ui; /// /// Note: it is generally recommended to instead use `jj new` and `jj /// squash`. +/// +/// For more information, see https://martinvonz.github.io/jj/latest/FAQ#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 8fbdcecfbe..f47d16c490 100644 --- a/cli/tests/cli-reference@.md.snap +++ b/cli/tests/cli-reference@.md.snap @@ -710,6 +710,8 @@ Sets the specified revision as the working-copy revision Note: it is generally recommended to instead use `jj new` and `jj squash`. +For more information, see https://martinvonz.github.io/jj/latest/FAQ#how-do-i-resume-working-on-an-existing-change + **Usage:** `jj edit ` ###### **Arguments:** diff --git a/docs/FAQ.md b/docs/FAQ.md index cb51b381c7..b4203eb71c 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -136,6 +136,20 @@ 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, but `jj edit` can be useful. When +you use `jj edit`, the revision is directly amended with your new changes, making it +difficult to tell what exactly you change. You should avoid using `jj edit` when the +revision has a conflict, as you may accidentally break the plain-text annotations on +your state without realising. + +To start, use `jj new ` to create a change based on that earlier revision. Make +your edits, then use `jj squash` to update the earlier revision with those edits. +For when you would use git stashing, use `jj edit ` for expected behaviour. +Other workflows may prefer `jj edit` as well. + ### How do I deal with divergent changes ('??' after the [change ID])? A [divergent change][glossary_divergent_change] represents a change that has two