ok/jj
1
0
Fork 0
forked from mirrors/jj
Code Pull requests Activity

Improve the documentation of jj prev

Browse source 
This will hopefully make it clear that `jj prev` does not
move by [OFFSET] relative to `@`, which is a misconception
that I had and I think others may also have.

I am suggesting this change as a result of the vigorous discussion in
these two issues:

- https://github.com/martinvonz/jj/issues/3426
- https://github.com/martinvonz/jj/pull/3445

We should make similar changes to `jj next` as well since
it follows similar rules.
This commit is contained in:
Evan Mesterhazy 2024-04-04 13:04:49 -04:00 committed by Evan Mesterhazy
parent 73508730aa
commit c1920d765f
2 changed files with 43 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
cli/src/commands/prev.rs
View file

@ -20,35 +20,36 @@ use crate::cli_util::{short_commit_hash, CommandHelper};
use crate::command_error::{user_error, CommandError};
use crate::commands::next::choose_commit;
use crate::ui::Ui;
/// Move the working-copy commit to the parent revision
/// Change the working copy revision relative to the parent revision
///
/// The command creates a new empty working copy revision that is the child of
/// an ancestor `offset` revisions behind the parent of the current working
/// copy.
///
/// The command moves you to the parent in a linear fashion.
/// For example, when the offset is 1:
///
/// ```text
/// D @ D
/// |/ |
/// A => A @
/// | |/
/// B B
/// D @ D
/// |/ |
/// A => A @
/// | |/
/// B B
/// ```
///
/// If `--edit` is passed, it will move the working copy commit
/// directly to the parent.
/// If `--edit` is passed, the working copy revision is changed to the parent of
/// the current working copy revision.
///
/// ```text
/// D @ D
/// |/ |
/// C => @
/// | |
/// B B
/// | |
/// A A
///
/// If your working-copy commit already has visible children, then `--edit` is
/// D @ D
/// |/ |
/// C => @
/// | |
/// B B
/// | |
/// A A
/// ```
/// If the working copy revision already has visible children, then `--edit` is
/// implied.
/// ```
// TODO(#2126): Handle multiple parents, e.g merges.
#[derive(clap::Args, Clone, Debug)]
#[command(verbatim_doc_comment)]

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

@ -128,7 +128,7 @@ To get started, see the tutorial at https://github.com/martinvonz/jj/blob/main/d
* `obslog` — Show how a change has evolved
* `operation` — Commands for working with the operation log
* `parallelize` — Parallelize revisions by making them siblings
* `prev` — Move the working-copy commit to the parent revision
* `prev` — Change the working copy revision relative to the parent revision
* `rebase` — Move revisions to different parent(s)
* `resolve` — Resolve a conflicted file with an external merge tool
* `restore` — Restore paths from another revision
@ -1385,34 +1385,36 @@ several conditions, otherwise the command will fail.
## `jj prev`
Move the working-copy commit to the parent revision
Change the working copy revision relative to the parent revision
The command creates a new empty working copy revision that is the child of
an ancestor `offset` revisions behind the parent of the current working
copy.
The command moves you to the parent in a linear fashion.
For example, when the offset is 1:
```text
D @ D
|/ |
A => A @
| |/
B B
D @ D
|/ |
A => A @
| |/
B B
```
If `--edit` is passed, it will move the working copy commit
directly to the parent.
If `--edit` is passed, the working copy revision is changed to the parent of
the current working copy revision.
```text
D @ D
|/ |
C => @
| |
B B
| |
A A
If your working-copy commit already has visible children, then `--edit` is
D @ D
|/ |
C => @
| |
B B
| |
A A
```
If the working copy revision already has visible children, then `--edit` is
implied.
```
**Usage:** `jj prev [OPTIONS] [OFFSET]`