Skip to content

Commit

Permalink
docs: add FAQ for why to use new-then-amend over edit
Browse files Browse the repository at this point in the history
  • Loading branch information
khionu committed Mar 8, 2024
1 parent c88ff38 commit 246f4e9
Show file tree
Hide file tree
Showing 3 changed files with 18 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
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions cli/tests/[email protected]
Original file line number Diff line number Diff line change
Expand Up @@ -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 <REVISION>`
###### **Arguments:**
Expand Down
14 changes: 14 additions & 0 deletions docs/FAQ.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Check failure on line 145 in docs/FAQ.md

View workflow job for this annotation

GitHub Actions / Codespell

commited ==> committed
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 <rev>` 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 <rev>` 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
Expand Down

0 comments on commit 246f4e9

Please sign in to comment.