From 246f4e9e396339ef948a73a4316ee38f60d31f16 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..90c0a0b5e2 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://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 9ac68a2fe3..c453fadf28 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 use `jj new` and `jj squash`. +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 0315c701b5..e429682b40 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -137,6 +137,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 the recommended default, but `jj edit` can be useful. +When you use `jj edit`, you don't get the opportunity to review your draft before it +is commited to the revision. This can create oversight issues when drafting over +changes that were considered done. You should avoid using `jj edit` when the +revision has a conflict, as the state will have plain-text conflict annotations. + +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