Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add FAQ for why to use new-then-amend over edit
Browse files Browse the repository at this point in the history
khionu committed Mar 7, 2024
1 parent e20d3d2 commit ab6751b
Showing 3 changed files with 15 additions and 0 deletions.
2 changes: 2 additions & 0 deletions cli/src/commands/edit.rs
Original file line number Diff line number Diff line change
@@ -26,6 +26,8 @@ use crate::ui::Ui;
/// Note, it is generally recommended to instead to use `jj new` and `jj amend`.
/// 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
2 changes: 2 additions & 0 deletions cli/tests/cli-reference@.md.snap
Original file line number Diff line number Diff line change
@@ -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 amend`. 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 <REVISION>`
###### **Arguments:**
11 changes: 11 additions & 0 deletions docs/FAQ.md
Original file line number Diff line number Diff line change
@@ -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 amend`,
and `jj edit`. The first is generally recommended over the second for a few reasons,
which come down to how intentional you are with your changes. If the revision you
want to resume working on has a conflict, `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. If you amend a new
revision onto a revision that contains a conflict, the conflict will be updated to
correctly reflect your new changes.

### How do I deal with divergent changes ('??' after the [change ID])?

A [divergent change][glossary_divergent_change] represents a change that has two

0 comments on commit ab6751b

Please sign in to comment.