lazyjj

repository·main·Indexed 22 days ago

https://github.com/cretezy/lazyjj

A Terminal User Interface (TUI) for the Jujutsu (jj) version control system built with Ratatui. lazyjj provides interactive navigation for logs, change management, bookmark handling, and diff viewing. It includes a configurable keybinding system via TOML and a structured application state for managing views such as Log, Files, Bookmarks, and CommandLog.

Tokens
10.9K
Snippets
54
Records
58
Agent score
77%

What's inside lazyjj

  1. Use the Command Box to run jj commands

    main
    You can execute any jj command directly within the lazyjj TUI by pressing : to open the command box. You do not need to include the jj prefix; for example, typing new main is equivalent to running jj new main.
    :
  2. Configure keybindings in lazyjj

    main

    Keybindings are configured using TOML syntax. You can assign a single key combination, an array of multiple key combinations for the same action, or disable an action entirely by setting it to false.

    # change keybinding
    save = "ctrl+s"
    
    # set multiple keybindings
    save = ["ctrl+s", "ctrl+shift+g"]
    
    # disable keybinding
    save = false
  3. Navigate between tabs and panels

    main

    Tab Navigation

    • Switch tabs using 1/2/3 or h/l.
    • View all key mappings for the current tab by pressing ?.

    Scrolling

    Main Panel

    • One line: j/k or arrow keys.
    • Half page: J/K or arrow keys.

    Details Panel

    • One line: Ctrl+e/Ctrl+y.
    • Half page: Ctrl+d/Ctrl+u.
    • Full page: Ctrl+f/Ctrl+b.
  4. Install lazyjj

    main

    You can install lazyjj using several methods depending on your preferred package manager or environment. Ensure you have jj installed before proceeding.

    Using cargo binstall

    cargo binstall lazyjj

    Using cargo install

    cargo install lazyjj --locked

    Using Arch Linux

    pacman -S lazyjj

    Pre-built binaries

    Download them from the releases page.

    cargo install lazyjj --locked
  5. Manage changes in the Log tab

    main

    The Log tab allows you to navigate the jj log and perform change management operations.

    TaskKeyCommand Mapping
    Select current change@N/A
    View change files in Files tabEnterN/A
    Display different revsetrjj log -r
    Toggle diff format (color-words/git)wN/A
    Toggle details panel wrappingWN/A
    Create new changenjj new
    Create new change + describeNjj new -m
    Edit highlighted changeejj edit
    Edit ignoring immutabilityEjj edit --ignore-immutable
    Abandon a changeajj abandon
    Describe highlighted changedjj describe
    Set bookmark to selected changebjj bookmark set
    Squash current to selectedsjj squash
    Squash ignoring immutabilitySjj squash --ignore-immutable
    Git fetchfjj git fetch
    Fetch all remotesFjj git fetch --all-remotes
    Git pushpjj git push
    Push all bookmarksPjj git push --all
    Push including new bookmarksCtrl+p / Ctrl+Pjj git push --allow-new
    n
  6. Manage bookmarks in the Bookmarks tab

    main

    The Bookmarks tab provides a dedicated interface for managing bookmarks across remotes.

    TaskKeyCommand Mapping
    Show all bookmarks (inc. remotes)ajj bookmark list --all
    Create a bookmarkcjj bookmark create
    Rename a bookmarkrjj bookmark rename
    Delete a bookmarkdjj bookmark delete
    Forget a bookmarkfjj bookmark forget
    Track a bookmarktjj bookmark track
    Untrack a bookmarkTjj bookmark untrack
    Create new change after bookmarknjj new
    Create new change + describeNjj new -m
    Edit bookmark's changeejj edit
    Edit ignoring immutabilityEjj edit --ignore-immutable
  7. Run lazyjj

    main

    To start lazyjj in the current directory:

    lazyjj

    To target a specific repository path:

    lazyjj --path ~/path/to/repo

    To start with a specific default revset:

    lazyjj -r '::@'
    lazyjj --path ~/path/to/repo
  8. Use the Commander struct to interact with the jj CLI

    main

    The Commander struct is the primary interface for executing jj commands from within lazyjj. It manages command execution, handles output, and maintains a history of executed commands.

    Key capabilities include:

    • Executing jj commands with specific color and quiet settings.
    • Recording command history in command_history for logging or auditing.
    • Setting environment variables for specific commands using set_env.
    • Managing terminal width for secondary programs (like diff tools) via limit_width.
    • Verifying that the installed jj version is compatible (minimum version 0.33.0).
    use crate::commander::Commander;
    use crate::env::Env;
    
    // Assuming env is already initialized
    let mut commander = Commander::new(&env);
    
    // Set an environment variable for the next command
    commander.set_env("MY_VAR", "my_value");
    
    // Execute a jj command and get the stdout as a String
    let output = commander.execute_jj_command(vec!["status"], true, true)?;
    
    // Execute a command where you don't need the output
    commander.execute_void_jj_command(vec!["git", "init", "--colocate"])?;
  9. Understand the LogPanel component

    main

    The LogPanel is a UI component used in the Log tab to display the output of the jj log command. It is typically rendered on the left side of the Log tab and serves as a selection mechanism: selecting a change in the LogPanel allows that change to be expanded and viewed on the right side of the tab.

    Key behaviors:

    • Dual Indexing: The panel manages two types of indices:
      • Line index: Used for scrolling at the display level (raw text lines).
      • Head index: Used for user-level scrolling and selecting specific changes (commits/heads).
    • Selection: Users can select a change (a Head) via keyboard or mouse clicks. The panel highlights the currently selected change using the configured highlight_color from the application settings.
  10. Configure lazyjj via jj config

    main

    lazyjj can be configured using your existing jj configuration file (user or repo config). The following options are available:

    KeyDescriptionDefault
    lazyjj.highlight-colorChanges the highlight color (supports named colors).#323264
    lazyjj.diff-formatDefault diff format: color-words or git.color_words
    lazyjj.diff-toolSpecifies the default diff tool.Uses ui.diff.tool if not set
    lazyjj.bookmark-prefixPrefix for generated bookmark names.push-
    lazyjj.layoutMain and details panel layout: horizontal or vertical.horizontal
    lazyjj.layout-percentSplit percentage between main and details (0-100).50

    Note on fallbacks:

    • If lazyjj.diff-format is unset, it uses ui.diff.format.
    • If lazyjj.diff-tool is unset, it uses ui.diff.tool.
    • If lazyjj.bookmark-prefix is unset, it uses git.push-bookmark-prefix.
    jj config set --user lazyjj.diff-format "color-words"
  11. Use the Rebase Popup to configure rebase operations

    main

    The RebasePopup is a transient UI component used to select a rebase configuration before executing the command. It allows you to specify how the source revision is selected (the 'cut' part) and how the target revision is handled (the 'paste' part).

    Rebase Configuration Options

    Source Mode (Cut Options):

    • -s: Include this change and all its descendants.
    • -b: Include the whole branch.
    • -r: Only move this single revision.

    Target Mode (Paste Options):

    • -d: Rebase onto the target as a new branch.
    • -A: Rebase after the target.
    • -B: Rebase before the target.

    Keyboard Shortcuts

    • Selection: s, b, r for source modes; d, Shift+A, Shift+B for target modes.
    • Actions: Enter to execute the rebase, Esc or q to cancel the operation.
    // Visual representation of the popup:
    // ~~~
    //    Source   (zsztoxlv)
    //    ( ) -s this and descendants
    //    ( ) -b whole branch
    //    (*) -r only one change moves
    //    Target @ (umrpslui)
    //    (*) -d rebase onto @ as new branch
    //    ( ) -A rebase after @
    //    ( ) -B rebase before @
    //
    // Esc: Cancel    Enter: Rebase
    // ~~~
  12. Debug lazyjj with Logging and Tracing

    main

    If you encounter issues, you can enable debugging tools by setting environment variables before running lazyjj.

    Logging

    Set LAZYJJ_LOG=1 to generate a lazyjj.log file.

    Tracing

    Set LAZYJJ_TRACE=1 to generate Chrome trace files (trace-*.json), which can be viewed in chrome://tracing or ui.perfetto.dev.

    LAZYJJ_LOG=1 lazyjj