Skip to content

Conversation

@murataslan1
Copy link

Summary

This PR addresses #3687 by adding visual ASCII diagrams to the help text of commands that work with commit graphs.

Changes

Added ASCII graphs to:

jj interdiff

Shows how commits are compared by temporarily rebasing one onto the other's parent:

    D
    |
C   C
|   |
B   A'  (A rebased onto C's parent)
|   |
A   B
 \ /
  root

jj squash

Shows how changes are moved from one commit to its parent:

D          D
|          |
C          C
|    =>    |
B          B'  (contains changes from both B and C)
|
A

jj duplicate

Shows how commits are copied:

         C'
C        |
|   =>   C
B        |
         B

Also added #[command(verbatim_doc_comment)] attribute to preserve the ASCII art formatting in the help output.

@murataslan1 murataslan1 requested a review from a team as a code owner November 28, 2025 19:00
@google-cla
Copy link

google-cla bot commented Nov 28, 2025

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

/// \ \ /
/// E A E
/// ```
/// (duplicating C onto D with `jj duplicate C --onto D`)

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The text describes multiple duplicates, but the graph shows one duplicate and a move or something else. Is this graph correct? If so, improve the text so it matches.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed! Updated the graph to show C being duplicated to C' with both sharing the same parent B, and added explanatory text.

Comment on lines 61 to 65
/// C C
/// | => |
/// B B' (contains changes from both B and C)
/// |
/// A

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A novice is left thinking that A was deleted, and C remains even though empty.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed! Updated with Before/After format showing that C is abandoned and B' contains both B's and C's changes. A remains in the graph.

@murataslan1 murataslan1 force-pushed the add-graphs-to-command-help branch from c6b8fb7 to 8a298bf Compare November 29, 2025 09:06
This addresses jj-vcs#3687 by adding visual ASCII diagrams to the help text
of commands that work with commit graphs:

- interdiff: Shows how commits are compared by rebasing
- squash: Shows how changes are moved between commits
- duplicate: Shows how commits are copied onto their parents or new destinations

Added #[command(verbatim_doc_comment)] to preserve the ASCII art formatting.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
@murataslan1 murataslan1 force-pushed the add-graphs-to-command-help branch from 8a298bf to ac4445b Compare November 29, 2025 19:42
@murataslan1
Copy link
Author

Thanks for the feedback @joyously! I've updated the graphs to address your concerns:

duplicate.rs:

  • First graph now correctly shows C being duplicated to C' (both sharing parent B), not moved
  • Second graph uses Before/After format and clearly shows original C remains unchanged

squash.rs:

  • Graph now uses Before/After format
  • Clearly shows C is abandoned and B' contains both B's and C's changes
  • Added explanatory text: "(C is abandoned after its changes are moved into B)"

Please let me know if the updated graphs are clearer now!

@joyously
Copy link

joyously commented Dec 1, 2025

Please let me know if the updated graphs are clearer now!

Much clearer, thanks. (I'm not the one to check for accuracy, though.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants