### Install Documentation Dependencies and Run Dev Server

Source: https://github.com/idursun/jjui/blob/main/CONTRIBUTING.md

Install dependencies and start the local development server for the documentation site, which is built with Starlight.

```shell
pnpm install
pnpm run dev
```

--------------------------------

### Plugin Setup in config.lua

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Load external Lua modules as plugins using `require` in `config.lua`. This example shows how a plugin can register its own action.

```lua
-- ~/.config/jjui/plugins/my_plugin.lua:
local M = {}

function M.setup(config)
  config.action("my-action", function()
    flash("hello from plugin")
  end, {
    key = "H",
    scope = "revisions",
    desc = "my action",
  })
end

return M
```

```lua
-- ~/.config/jjui/config.lua:
local my_plugin = require("plugins.my_plugin")

function setup(config)
  my_plugin.setup(config)
end
```

--------------------------------

### Install jjui with Scoop

Source: https://github.com/idursun/jjui/blob/main/README.md

Use Scoop to install jjui on Windows. Ensure the 'extras' bucket is added first.

```shell
scoop bucket add extras
scoop install jjui
```

--------------------------------

### Install jjui from AUR (Source)

Source: https://github.com/idursun/jjui/blob/main/README.md

Build and install jjui from source using the AUR with paru or yay.

```shell
paru -S jjui
# OR
yay -S jjui
```

--------------------------------

### Install jjui from AUR (Binary)

Source: https://github.com/idursun/jjui/blob/main/README.md

Install the pre-built jjui binary from the Arch User Repository (AUR) using paru or yay.

```shell
paru -S jjui-bin
# OR
yay -S jjui-bin
```

--------------------------------

### Load plugin module in config.lua

Source: https://context7.com/idursun/jjui/llms.txt

Example of loading a plugin module named 'workflow' and calling its setup function within the main `config.lua`.

```lua
-- ~/.config/jjui/config.lua
local workflow = require("plugins.workflow")

function setup(config)
  workflow.setup(config)
end
```

--------------------------------

### Build and Development Commands for jjui

Source: https://github.com/idursun/jjui/blob/main/AGENTS.md

Common commands for building, installing, testing, and generating code for the jjui project. Ensure you have the correct Go version and jj installed.

```bash
# Build the application
go build ./cmd/jjui
```

```bash
# Install locally
go install ./...
```

```bash
# Run all tests
go test ./...
```

```bash
# Run a specific test
go test -run TestName ./path/to/package
```

```bash
# Run tests with verbose output
go test -v ./...
```

```bash
# Regenerate action catalog after changing intent annotations
go run ./cmd/genactions
```

--------------------------------

### Install jjui with WinGet

Source: https://github.com/idursun/jjui/blob/main/README.md

Use WinGet to install the latest release of jjui on Windows.

```shell
winget install IbrahimDursun.jjui
```

--------------------------------

### Install jjui via Package Managers

Source: https://context7.com/idursun/jjui/llms.txt

Install jjui using various package managers for macOS, Linux, and Windows. Ensure the respective package manager is set up.

```shell
# macOS / Linux (Homebrew)
brew install jjui
```

```shell
# Windows (WinGet)
winget install IbrahimDursun.jjui
```

```shell
# Windows (Scoop)
scoop bucket add extras && scoop install jjui
```

```shell
# Arch Linux (AUR)
paru -S jjui-bin
```

```shell
# Nix (nixpkgs)
nix run nixpkgs#jjui
```

```shell
# Nix (flake, always latest main)
nix run github:idursun/jjui
```

--------------------------------

### Install jjui with Homebrew

Source: https://github.com/idursun/jjui/blob/main/README.md

Install the latest release of jjui from Homebrew core on macOS or Linux.

```shell
brew install jjui
```

--------------------------------

### Key and sequence binding examples

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Demonstrates how to specify a single key or an array of keys for a binding. Both 'r' and the sequence ['up', 'k'] trigger the same action.

```toml
key = "r"
key = ["up", "k"]   # both keys trigger the same action
```

--------------------------------

### Install JJUI Latest Release

Source: https://github.com/idursun/jjui/blob/main/README.md

Installs the latest released version of JJUI using go install. Ensure your Go environment is set up correctly.

```shell
go install github.com/idursun/jjui/cmd/jjui@latest
```

--------------------------------

### Start Squash Operation

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Initiates a squash operation on specified files.

```lua
revisions.start_squash({files = {"main.go"}})
```

--------------------------------

### Example Theme Style Definitions

Source: https://github.com/idursun/jjui/wiki/Themes

Illustrates how to define styles for UI elements using selectors and style properties in a TOML theme file.

```toml
"selected" = { fg = "#FF8C00", bg = "#2B2B2B", bold = true }
"border" = { fg = "bright black" }
```

--------------------------------

### Install Lua type definitions for jjui

Source: https://context7.com/idursun/jjui/llms.txt

Install Lua type definition files for jjui. This enables better autocompletion and type checking when using Lua for custom actions and bindings.

```shell
jjui --install-lua-types
```

--------------------------------

### Install JJUI Latest Commit from Main

Source: https://github.com/idursun/jjui/blob/main/README.md

Installs the most recent commit from the main branch of JJUI. This is useful for testing the latest development changes.

```shell
go install github.com/idursun/jjui/cmd/jjui@HEAD
```

--------------------------------

### Multi-key sequence binding

Source: https://context7.com/idursun/jjui/llms.txt

Example of creating a multi-key sequence binding ('g' then 'r') to open the revset editor.

```toml
[[bindings]]
action = "ui.open_revset"
seq    = ["g", "r"]
scope  = "revisions"
desc   = "revset via sequence"
```

--------------------------------

### Custom Command Configuration

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Example of how to define a custom Lua command in the jjui configuration file.

```APIDOC
## Custom Command Configuration

### Description
Define a custom command with a keybinding and a Lua script.

### Configuration File
`~/.config/jjui/config.toml`

### Example
```toml
[custom_commands.hello]
key = ["ctrl+h"]
lua = '''
flash("Hello from Lua!")
'''
```

### Usage
Press `Ctrl+h` in jjui to execute the `flash("Hello from Lua!")` command.
```

--------------------------------

### Start Rebase Operation

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Initiates a rebase operation, specifying the source and target for the rebase.

```lua
revisions.start_rebase({source = "branch", target = "after"})
```

--------------------------------

### Start Inline Describe

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Opens an inline editor to change the revision description. Returns true if applied.

```lua
local applied = revisions.start_inline_describe()
```

--------------------------------

### Add a binding for an existing action

Source: https://context7.com/idursun/jjui/llms.txt

Example of using `config.bind` to add a key binding ('F1') for the 'ui.open_help' action within the 'ui' scope.

```lua
config.bind({
  action = "ui.open_help",
  key    = "F1",
  scope  = "ui",
  desc   = "help",
})
```

--------------------------------

### Execute jj command interactively

Source: https://context7.com/idursun/jjui/llms.txt

Example of launching an interactive 'jj split' command, which typically opens a full terminal interface for user input.

```lua
-- Interactive: opens a full terminal for user input (split, diffedit, etc.)
jj_interactive("split")
```

--------------------------------

### Copy selected file or change ID to clipboard

Source: https://context7.com/idursun/jjui/llms.txt

An example demonstrating how to copy either the selected file path or the change ID to the clipboard, prioritizing the file path if available.

```lua
-- Example: copy selected file or change ID
local target = file or cid
if target then
  copy_to_clipboard(target)
  flash("Copied: " .. target)
end
```

--------------------------------

### Launch jjui with custom revset

Source: https://context7.com/idursun/jjui/llms.txt

Start jjui with a custom revset filter applied to the revisions shown. This overrides the default `jj` configuration.

```shell
# Set a custom revset on startup (overrides jj config)
jjui --revset "mine() & trunk().."
jjui -r "trunk().. ~ empty()"
```

--------------------------------

### Remap 'open revset editor' binding

Source: https://context7.com/idursun/jjui/llms.txt

Example of rebinding the 'revset.edit' action from Shift+L to Ctrl+L for the 'revisions' scope.

```toml
[[bindings]]
action = "revset.edit"
key    = "ctrl+l"
scope  = "revisions"
desc   = "edit revset"
```

--------------------------------

### Add a Lua Custom Command

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Add a Lua custom command to your jjui configuration file. This example defines a command named 'hello' triggered by Ctrl+h.

```toml
[custom_commands.hello]
key = ["ctrl+h"]
lua = '''
flash("Hello from Lua!")
'''

```

--------------------------------

### Define a custom action with Lua script

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Custom actions are defined in `[[actions]]` blocks, requiring a `name` and a `lua` script. This example copies the diff to the clipboard.

```toml
[[actions]]
name = "copy-diff"
lua = '''
local diff = jj("diff", "-r", context.change_id(), "--git")
copy_to_clipboard(diff)
'''
```

--------------------------------

### Migrate Revset Command from TOML to Actions/Bindings

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Revset commands in TOML's `[custom_commands]` are migrated to `[[actions]]` using `revset.set` and `[[bindings]]`. This example demonstrates the migration for a 'show descendants' command.

```toml
[custom_commands."show descendants"]
key = ["M"]
revset = "::$change_id"
```

```toml
[[actions]]
name = "show-descendants"
lua = '''
revset.set("::" .. context.change_id())
'''

[[bindings]]
action = "show-descendants"
key = "M"
scope = "revisions"
desc = "show descendants"
```

--------------------------------

### Migrate Interactive Command from TOML to Actions/Bindings

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Interactive commands defined in TOML's `[custom_commands]` are migrated to `[[actions]]` with `jj_interactive` and `[[bindings]]` in TOML. This example shows the transformation for a 'resolve vscode' command.

```toml
[custom_commands."resolve vscode"]
key = ["R"]
args = ["resolve", "--tool", "vscode"]
show = "interactive"
```

```toml
[[actions]]
name = "resolve-vscode"
lua = '''
jj_interactive("resolve", "--tool", "vscode")
'''

[[bindings]]
action = "resolve-vscode"
key = "R"
scope = "revisions"
desc = "resolve in vscode"
```

--------------------------------

### Example 'Fire' Theme Configuration

Source: https://github.com/idursun/jjui/wiki/Themes

This TOML configuration defines the 'Fire' theme for jjui, specifying colors and styles for various UI elements. It includes settings for text, selection, borders, titles, and specific component states.

```toml
"text" = { fg = "#F0E6D2", bg = "#1C1C1C" }
"dimmed" = { fg = "#888888" }
"selected" = { bg = "#4B2401", fg = "#FFD700" }
"border" = { fg = "#3A3A3A" }
"title" = { fg = "#FF8C00", bold = true }
"shortcut" = { fg = "#FFA500" }
"matched" = { fg = "#FFD700", underline = true }
"source_marker" = { bg = "#6B2A00", fg = "#FFFFFF" }
"target_marker" = { bg = "#800000", fg = "#FFFFFF" }
"revisions rebase source_marker" = { bold = true }
"revisions rebase target_marker" = { bold = true }
"status" = { bg = "#1A1A1A" }
"status title" = { fg = "#000000", bg = "#FF4500", bold = true }
"status shortcut" = { fg = "#FFA500" }
"status dimmed" = { fg = "#888888" }
"revset text" = { bold = true }
"revset completion selected" = { bg = "#4B2401", fg = "#FFD700" }
"revset completion matched" = { bold = true }
"revset completion dimmed" = { fg = "#505050" }
"revisions selected" = { bold = true }
"oplog selected" = { bold = true }
"evolog selected" = { bg = "#403010", fg = "#FFD700", bold = true }
"help" = { bg = "#2B2B2B" }
"help title" = { fg = "#FF8C00", bold = true, underline = true }
"help border" = { fg = "#3A3A3A" }
"menu" = { bg = "#2B2B2B" }
"menu title" = { fg = "#FF8C00", bold = true }
"menu shortcut" = { fg = "#FFA500" }
"menu dimmed" = { fg = "#888888" }
"menu border" = { fg = "#3A3A3A" }
"menu selected" = { bg = "#4B2401", fg = "#FFD700" }
"confirmation" = { bg = "#2B2B2B" }
"confirmation text" = { fg = "#F0E6D2" }
"confirmation selected" = { bg = "#4B2401", fg = "#FFD700" }
"confirmation dimmed" = { fg = "#888888" }
"confirmation border" = { fg = "#FF4500" }
"undo" = { bg = "#2B2B2B" }
"undo confirmation dimmed" = { fg = "#888888" }
"undo confirmation selected" = { bg = "#4B2401", fg = "#FFD700" }
"preview" = { fg = "#F0E6D2" }
```

--------------------------------

### Show Help Information

Source: https://github.com/idursun/jjui/wiki/Command-Line-Options

Prints the help message for jjui, detailing all available command line options. Use the `--help` flag.

```bash
jjui --help
```

--------------------------------

### Build Jujutsu UI Project

Source: https://github.com/idursun/jjui/blob/main/CONTRIBUTING.md

Build the Jujutsu UI project using the Go toolchain.

```shell
go build ./cmd/jjui
```

--------------------------------

### Define Basic Custom Commands

Source: https://github.com/idursun/jjui/wiki/Custom-Commands

Configure custom commands with keys, arguments, and display modes. Use placeholders like $change_id for dynamic arguments. The 'show' argument controls how command output is displayed.

```toml
[custom_commands]
"show diff" = { key = ["U"], args = ["diff", "-r", "$change_id", "--color", "always"], show = "diff" }
"show oplog diff" = { key = ["ctrl+o"], args = ["op", "show",  "$operation_id", "--color", "always"], show = "diff" }
"resolve vscode" = { key = ["R"], args = ["resolve", "--tool", "vscode"], show = "interactive" }
"new main" = { args = ["new", "main"] }
"tug" = { key = ["ctrl+t"], args = ["bookmark", "move", "--from", "closest_bookmark($change_id)", "--to", "closest_pushable($change_id)"] }
```

--------------------------------

### Create Bookmark on Current Change

Source: https://github.com/idursun/jjui/wiki/Leader-Key

Defines a leader key `bn` to create a new bookmark for the current change, using `gum` to prompt for the bookmark name.

```toml
[leader.bn]
help = "Set new bookmark"
send = [ "$", "jj bookmark set -r \"$change_id\" $(gum input --placeholder \"Name of the new bookmark\")", "enter" ]
```

--------------------------------

### Install JJUI Latest Commit Bypassing Cache

Source: https://github.com/idursun/jjui/blob/main/README.md

Installs the latest commit from the main branch without using the Go module cache. Use this if you suspect cache issues or need the absolute latest code.

```shell
GOPROXY=direct go install github.com/idursun/jjui/cmd/jjui@HEAD
```

--------------------------------

### Show Version Information

Source: https://github.com/idursun/jjui/wiki/Command-Line-Options

Displays the version of jjui. Use the `--version` flag.

```bash
jjui --version
```

--------------------------------

### Preview Pane Configuration

Source: https://github.com/idursun/jjui/wiki/Revisions

Configure commands for displaying revision, oplog, and file details in the preview pane. These commands are executed when the preview pane is opened.

```toml
[preview]
revision_command = ["show", "--color", "always", "-r", "$change_id"]
oplog_command = ["op", "show", "$operation_id", "--color", "always"]
file_command = ["diff", "--color", "always", "-r", "$change_id", "$file"]
```

--------------------------------

### Full jjui Configuration with Preview Settings (TOML)

Source: https://github.com/idursun/jjui/wiki/Preview

This TOML snippet shows a comprehensive configuration for jjui, including keybindings for the preview mode and various preview window settings like position and size.

```toml
[keys.preview]
  mode = ["p"]
  toggle_bottom = ["P"]
  scroll_up = ["ctrl+p"]
  scroll_down = ["ctrl+n"]
  half_page_down = ["ctrl+d"]
  half_page_up = ["ctrl+u"]
  expand = ["ctrl+h"]
  shrink = ["ctrl+l"]
[preview]
  position = "auto" # auto, bottom, or right
  show_at_start = false
  width_percentage = 50.0
  width_increment_percentage = 5.0
  revision_command = ["show", "--color", "always", "-r", "$change_id"]
  oplog_command = ["op", "show", "$operation_id", "--color", "always"]
  file_command = ["diff", "--color", "always", "-r", "$change_id", "$file"]
```

--------------------------------

### Get checked commit IDs

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves a table of checked commit IDs using `context.checked_commit_ids()`.

```lua
local commits = context.checked_commit_ids()   -- table of checked commit IDs
```

--------------------------------

### Get checked change IDs

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves a table of checked change IDs using `context.checked_change_ids()`.

```lua
local changes = context.checked_change_ids()   -- table of checked change IDs
```

--------------------------------

### Get checked file paths

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves a table of checked file paths using `context.checked_files()`.

```lua
local files   = context.checked_files()        -- table of checked file paths
```

--------------------------------

### Execute jj command asynchronously

Source: https://context7.com/idursun/jjui/llms.txt

Shows how to execute a 'jj bookmark create' command asynchronously for fire-and-forget operations. Refreshes revisions after execution.

```lua
-- Asynchronous: fire-and-forget (state-changing commands)
jj_async("bookmark", "create", "feature-" .. context.change_id())
revisions.refresh()
```

--------------------------------

### Get selected operation ID

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves the ID of the selected operation in the oplog using `context.operation_id()`.

```lua
local opid = context.operation_id()   -- selected operation ID in oplog (or nil)
```

--------------------------------

### Open Configuration File

Source: https://github.com/idursun/jjui/wiki/Configuration

Use the --config argument to open the current configuration file in your default editor.

```bash
jjui --config
```

--------------------------------

### Get current commit ID

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves the commit ID of the currently selected revision using `context.commit_id()`.

```lua
local cmid = context.commit_id()      -- commit ID
```

--------------------------------

### Show Selection Menu

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Use `choose(...)` to display a selection menu and wait for user choice. It accepts varargs, a table, or an options object with `options` and `title`.

```lua
local choice = choose("Yes", "No")
```

```lua
choose({options = {"a", "b"}, title = "Pick"})
```

--------------------------------

### Get current change ID

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves the change ID of the currently selected revision or file using `context.change_id()`.

```lua
local cid  = context.change_id()      -- change ID of selected revision/file
```

--------------------------------

### Show Input Prompt

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Use `input(...)` to display an input prompt. Options include `title` and `prompt`.

```lua
local text = input({title = "Name", prompt = "Enter: "})
```

--------------------------------

### Show Selection Menu

Source: https://context7.com/idursun/jjui/llms.txt

Display a selection menu with options, optionally including a title. Returns the chosen string or nil.

```lua
-- Show a selection menu; returns the chosen string or nil
local choice = choose("mine()", "trunk()..", "all()", revset.default())
-- With a title and table
local pick = choose({ options = { "yes", "no" }, title = "Confirm?" })
if pick == "yes" then jj_async("abandon", context.change_id()) end
```

--------------------------------

### Get selected file path

Source: https://context7.com/idursun/jjui/llms.txt

Retrieves the path of the selected file in the details view, or nil if no file is selected, using `context.file()`.

```lua
local file = context.file()           -- selected file path in details view (or nil)
```

--------------------------------

### Open jjui in a Specific Directory

Source: https://github.com/idursun/jjui/wiki/Command-Line-Options

Launches jjui and targets a specific repository path. Provide the absolute or relative path to the desired jj repository.

```bash
jjui /path/to/repo
```

--------------------------------

### Run jjui with Nix Flake

Source: https://github.com/idursun/jjui/blob/main/README.md

Run jjui using a flake from the GitHub repository.

```shell
nix run github:idursun/jjui
```

--------------------------------

### Trigger UI Operations Programmatically

Source: https://context7.com/idursun/jjui/llms.txt

Programmatically trigger UI operations such as opening details, starting inline descriptions, squashing files, or rebasing.

```lua
-- Trigger UI operations programmatically
revisions.open_details()
revisions.start_inline_describe()   -- yields until description is confirmed; returns bool
revisions.start_squash({ files = { "README.md", "src/main.go" } })
revisions.start_rebase({ source = "branch", target = "after" })
```

--------------------------------

### Run jjui with Nix

Source: https://github.com/idursun/jjui/blob/main/README.md

Run jjui directly using the Nix package manager.

```shell
nix run nixpkgs#jjui
```

--------------------------------

### Quick Revset Switcher with Lua

Source: https://github.com/idursun/jjui/wiki/Custom-Command-‐-Lua-Scripting

Presents a menu of common revsets for quick selection and application. Requires the 'choose' and 'revset' modules.

```lua
local selected = choose({
    options = {
        "mine()",
        "all()",
        "trunk()..@",
        revset.default()
    },
    title = "Quick Revset"
})

if selected then
    revset.set(selected)
    flash("Revset: " .. selected)
end

```

--------------------------------

### Build JJUI from Source

Source: https://github.com/idursun/jjui/blob/main/README.md

Clones the JJUI repository and builds all Go packages within it. This method is suitable for development or when you need to build from the source code.

```shell
git clone https://github.com/idursun/jjui.git
cd jjui
go install ./...
```

--------------------------------

### Develop jjui with Nix Flake

Source: https://github.com/idursun/jjui/blob/main/README.md

Enter the development environment for jjui using a flake from the GitHub repository.

```shell
nix develop github:idursun/jjui
```

--------------------------------

### Migrate jjui configuration

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Run this command to automatically convert [custom_commands] and [keys] sections to the new actions and bindings format. It creates a backup of the original config.

```sh
jjui --config --migrate
```

--------------------------------

### Define custom action in TOML

Source: https://context7.com/idursun/jjui/llms.txt

Example of defining a custom action using Lua within a TOML configuration file for jjui. Custom actions can be bound to keys.

```toml
# ~/.config/jjui/config.toml

[[actions]]
  name = "my-custom-action"
  description = "Does something cool"
  script = <<EOF
    -- Lua script for the custom action
    print("Hello from custom action!")
  EOF

[[bindings]]
  key = "<leader>ca"
  action = "my-custom-action"

```

--------------------------------

### Register Action with Inline Binding in config.lua

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Use `config.action` in `config.lua` to register a Lua action and optionally define an inline binding. This example registers a 'copy-diff' action.

```lua
function setup(config)
  config.action("copy-diff", function()
    local diff = jj("diff", "-r", context.change_id(), "--git")
    copy_to_clipboard(diff)
  end, {
    key = "Y",
    scope = "revisions",
    desc = "copy diff",
  })
end
```

--------------------------------

### Custom Command with Revset Modification

Source: https://github.com/idursun/jjui/wiki/Custom-Commands

Define a custom command that modifies the current revision set. This example filters the view to show only descendants of the selected change ID.

```toml
[custom_commands]
"show after revisions" = { key = ["M"], revset = "::$change_id" }
```

--------------------------------

### Basic jjui Usage

Source: https://github.com/idursun/jjui/wiki/Command-Line-Options

Opens jjui in the current directory. This is the default behavior when no location is specified.

```bash
jjui
```

--------------------------------

### Configure Light and Dark Themes

Source: https://github.com/idursun/jjui/wiki/Themes

Set different themes for light and dark modes using the `ui.theme` configuration.

```toml
[ui.theme]
light = "my-light-theme"
dark = "my-dark-theme"
```

--------------------------------

### Load Base Theme Configuration

Source: https://github.com/idursun/jjui/wiki/Themes

Configure jjui to load a base theme from a specified TOML file.

```toml
# ~/.config/jjui/config.toml
[ui]
theme = "my-theme"
```

--------------------------------

### Lua Custom Command for Revset Manipulation

Source: https://github.com/idursun/jjui/wiki/Custom-Commands

Execute embedded Lua scripts for advanced custom command logic. This example modifies the current revset to include or increment ancestors of a selected change ID.

```toml
[custom_commands.append_to_revset]
    key = ["+"]
    lua = '''
    local change_id = revisions.current()
    if not change_id then return end

    local current = revset.current()
    local bumped = false
    local updated = current:gsub("ancestors%(" .. change_id .. "%s*,%s*(%d+)%)", function(n)
        bumped = true
        return "ancestors(" .. change_id .. ", " .. (tonumber(n) + 1) .. ")"
    end, 1)

    if not bumped then
        updated = current .. " | ancestors(" .. change_id .. ", 2)"
    end

    revset.set(updated)
    '''
```

--------------------------------

### Bind to Existing Action in config.lua

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Use `config.bind` in `config.lua` to add a key binding to an action that is defined elsewhere (e.g., in TOML or another `config.action` call). This example binds the 'R' key to the 'ui.open_revset' action.

```lua
function setup(config)
  config.bind({
    action = "ui.open_revset",
    key = "R",
    scope = "revisions",
    desc = "revset",
  })
end
```

--------------------------------

### Migrate Lua Custom Command from TOML to Actions/Bindings

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Lua scripts defined directly in TOML's `[custom_commands]` can be migrated to `[[actions]]` with a `lua` field. The same Lua API remains available. This example shows a 'set-revset' command.

```toml
[custom_commands."set-revset"]
key = ["+"]
lua = '''
revset.set("bookmarks()")
'''
```

```toml
[[actions]]
name = "set-revset"
lua = '''
revset.set("bookmarks()")
'''

[[bindings]]
action = "set-revset"
key = "+"
scope = "revisions"
desc = "set revset"
```

--------------------------------

### Add new custom actions with [[actions]] and [[bindings]]

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Define new custom actions using `[[actions]]` blocks, specifying the action name and Lua script. Then, bind these actions to keys using `[[bindings]]`.

```toml
[[actions]]
name = "my-action"
lua = 'flash("hello")'

[[bindings]]
action = "my-action"
key = "H"
scope = "revisions"
```

--------------------------------

### Execute jj command synchronously

Source: https://context7.com/idursun/jjui/llms.txt

Demonstrates executing a 'jj log' command synchronously, capturing its output and any error. The output is flashed to the user if an error occurs.

```lua
-- Synchronous: blocks until done, returns (output, err)
local log, err = jj("log", "-r", "@", "-T", "change_id")
if err then flash({ text = err, error = true }) return end
```

--------------------------------

### Replace [keys] entry with [[bindings]]

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Migrates a legacy `[keys]` entry mapping an action name to a key into a new `[[bindings]]` block, specifying the action, key, and scope.

```toml
[[bindings]]
action = "revisions.abandon"
key = "x"
scope = "revisions"
```

--------------------------------

### Configure UI Theme

Source: https://context7.com/idursun/jjui/llms.txt

Configure the UI theme in `config.toml`. Supports single themes for light/dark or separate themes for each.

```toml
# ~/.config/jjui/config.toml

# Single theme for light + dark
[ui]
theme = "my-theme"

# Separate light and dark themes
[ui.theme]
light = "my-light-theme"
dark  = "my-dark-theme"
```

--------------------------------

### Nested Leader Keymaps with Context

Source: https://github.com/idursun/jjui/wiki/Leader-Key

Illustrates nested leader keymaps for creating new changes, with a context requirement for `$change_id`. The parent key `\n` acts as a menu without a direct send action.

```toml
[leader.n]
context = ["$change_id"]
help = "New change"

[leader.na]
help = "After"
send = [ ":", "new -A \"$change_id\"", "enter" ]

[leader.nb]
help = "Before"
send = [ ":", "new -B \"$change_id\"", "enter" ]
```

--------------------------------

### Preview Window Position Configuration (TOML)

Source: https://github.com/idursun/jjui/wiki/Preview

Configure the default position and behavior of the preview window. Options include 'auto', 'bottom', and 'right'.

```toml
[preview]
position = "auto"   # one of: "auto", "bottom", "right"
show_at_start = true
```

--------------------------------

### Launch jjui for a specific repository

Source: https://context7.com/idursun/jjui/llms.txt

Open jjui and target a specific Jujutsu repository located at the provided path.

```shell
jjui /path/to/my-repo
```

--------------------------------

### Replace simple [custom_commands] with [[actions]] and [[bindings]]

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Migrates a `[custom_commands]` entry that executes a simple jj command. It's converted into a new `[[actions]]` block defining the Lua script and a `[[bindings]]` block to trigger it.

```toml
[[actions]]
name = "show-diff"
lua = '''
jj_async("diff", "-r", context.change_id(), "--git")
'''

[[bindings]]
action = "show-diff"
key = "U"
scope = "revisions"
desc = "show diff"
```

--------------------------------

### Set Alternate Bindings Profile

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Specify a TOML file to completely replace the default key bindings. This file should be located relative to the configuration directory or be an absolute path.

```toml
bindings_profile = "vim_bindings.toml"
```

--------------------------------

### Basic Leader Key Mapping

Source: https://github.com/idursun/jjui/wiki/Leader-Key

Defines a simple leader key `h` that sends `?` to the UI, typically used for help.

```toml
[leader.h]
help = "Help"
send = ["?"]
```

--------------------------------

### Launch jjui with revision limit

Source: https://context7.com/idursun/jjui/llms.txt

Launch jjui and display only a specified number of the most recent revisions. Use the `--limit` or `-n` flag.

```shell
# Show only the 20 most recent revisions
jjui --limit 20
jjui -n 20
```

--------------------------------

### Migrate Legacy Config Automatically

Source: https://context7.com/idursun/jjui/llms.txt

Use the jjui command-line tool to automatically migrate legacy TOML configurations to the newer [[actions]] and [[bindings]] format. This process creates a backup of the original config file.

```shell
jjui --config --migrate
# Creates config.old.toml backup, rewrites config.toml with [[actions]] + [[bindings]]
```

--------------------------------

### Import JJ Aliases as Custom Commands

Source: https://github.com/idursun/jjui/wiki/Custom-Commands

This script imports all existing jj aliases and configures them as custom commands in jjui. It appends the necessary TOML configuration to the jjui config file.

```bash
echo "[custom_commands]" >> $JJUI_CONFIG_DIR/config.toml
jj config list aliases -T '"\"" ++ name ++ "\" = { args = [ \"" ++ name ++ "\" ] }\n"' --no-pager |
    sed -e 's/aliases.//g' |
    tee -a $JJUI_CONFIG_DIR/config.toml
```

--------------------------------

### Run Jujutsu UI

Source: https://github.com/idursun/jjui/blob/main/CONTRIBUTING.md

Run the Jujutsu UI application. This command is also used to ensure the code builds successfully.

```shell
go run ./cmd/jjui
```

--------------------------------

### Rewrite [leader] sequences as seq bindings

Source: https://github.com/idursun/jjui/wiki/Migrating-to-v0.10

Convert legacy [leader] sequences to new `seq` bindings. The `seq` field takes an ordered array of keys for multi-key sequences.

```toml
[[bindings]]
action = "ui.open_revset"
seq = ["g", "r"]
scope = "revisions"
```

--------------------------------

### Legacy Custom Command Configuration

Source: https://context7.com/idursun/jjui/llms.txt

Configure custom commands using the legacy TOML syntax for backward compatibility. These commands can be migrated to the newer [[actions]] + [[bindings]] format. Available placeholder variables include $change_id, $commit_id, and others.

```toml
# Still functional (legacy syntax)
[custom_commands]
"show diff"           = { key = ["U"], args = ["diff", "-r", "$change_id", "--color", "always"], show = "diff" }
"resolve vscode"      = { key = ["R"], args = ["resolve", "--tool", "vscode"], show = "interactive" }
"show descendants"    = { key = ["M"], revset = "::$change_id" }
"move commit down"    = { key = ["J"], args = ["rebase", "-r", "$change_id", "--insert-before", "$change_id-"] }
"move commit up"      = { key = ["K"], args = ["rebase", "-r", "$change_id", "--insert-after",  "$change_id+"] }

# Available placeholder variables:
#   $change_id, $commit_id, $operation_id, $file, $revset
#   $checked_commit_ids, $checked_files
```

--------------------------------

### Clone Jujutsu UI Repository

Source: https://github.com/idursun/jjui/blob/main/CONTRIBUTING.md

Clone the Jujutsu UI repository locally after forking it on GitHub.

```shell
git clone https://github.com/YOUR_USERNAME/jjui.git
cd jjui
```