mirrors/jj
1
0
Fork 1
mirror of https://github.com/martinvonz/jj.git synced 2024-11-28 17:41:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

docs: add FAQ for why to use new-then-amend over edit

Browse source
This commit is contained in:
Khionu Sybiern 2024-03-07 13:16:16 -08:00
parent 289b9bc71f
commit 3bbc3e5715
3 changed files with 18 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
cli/src/commands/edit.rs
View file

@ -25,6 +25,8 @@ use crate::ui::Ui;
/// ///
/// Note: it is generally recommended to instead use `jj new` and `jj /// Note: it is generally recommended to instead use `jj new` and `jj
/// squash`. /// 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)] #[derive(clap::Args, Clone, Debug)]
pub(crate) struct EditArgs { pub(crate) struct EditArgs {
/// The commit to edit /// The commit to edit

2
cli/tests/cli-reference@.md.snap
View file

@ -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`. 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 <REVISION>` **Usage:** `jj edit <REVISION>`
###### **Arguments:** ###### **Arguments:**

14
docs/FAQ.md
View file

@ -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 to the old state, and `jj restore --from X` to restore the new working-copy
commit to the new state. 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 <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])? ### How do I deal with divergent changes ('??' after the [change ID])?
A [divergent change][glossary_divergent_change] represents a change that has two A [divergent change][glossary_divergent_change] represents a change that has two