# Rat Commander — User Manual

Rat Commander (`rc`) is a two-panel terminal file manager in the tradition of
Norton Commander and Midnight Commander, with a batch of modern built-in tools:
a file viewer and editor with syntax highlighting, archive browsing, remote
(SFTP / FTP / SCP) clients, a disk-usage explorer, a process explorer, and (on
Linux) a disk manager. It needs no external programs for its core features.

Press **F1** inside the program to read this manual at any time.


## The screen

The window is divided into four areas, top to bottom:

- **Menu bar** (top row) — `Left  File  Command  Options  Right`. Open it with
  **F9** (or `Alt` + its first letter).
- **Two panels** — the heart of the program. Each shows the contents of one
  directory. The **active panel** has a highlighted (brighter) border; it is the
  one your keystrokes act on. The other panel is usually the destination for
  copy/move operations.
- **Command line** (second from bottom) — type a shell command here and press
  Enter to run it in the active panel's directory. Recently run commands are
  remembered across sessions: cycle them with `Alt-P` / `Alt-N`, or press `Alt-Shift-H`
  to pick one from the **Shell History** window. `Alt-Enter` drops the name under
  the cursor onto the command line. `Ctrl-F5` hides it and gives the row to the
  panels, which also makes plain typing start a quick search — see *Working
  without the command prompt*.
- **Function-key bar** (bottom row) — shows what F1–F10 do in the current
  context. The labels also work as buttons: click one to run it.

Each panel's bottom border shows the volume's **free / total** disk space, and a
mini status line under the listing shows the full name of the highlighted file.

### The console (behind the panels)

Commands you run from the command line go to a **single persistent shell** —
the very same session `Ctrl-O` drops into — whose screen sits *behind* the
panels, exactly like Norton Commander. Because it's one lasting session, state
carries across commands and between the command line and `Ctrl-O`: a variable
you set, a directory you `cd` into, your shell history and aliases are all
shared. Commands run in the active panel's directory (the shell follows the
panel automatically).

Running a command does **not** interrupt the file manager — there's no "press a
key to continue". The output lands on the console behind the panels; to watch
it, hide a panel with `Ctrl-F1` / `Ctrl-F2`, shrink both with `Ctrl-F4`
(half-height), or press `Ctrl-O` to step into the shell full-screen (and again
to step back). Colours and cursor motion render faithfully, so it reads like the
real terminal it is. (Interactive programs and Ctrl-C act on the shell while
you're in it via `Ctrl-O`.)

**On a remote panel.** When the active panel is on an **SFTP or SCP** connection,
the command line and `Ctrl-O` run a shell on the **remote host** instead — over
the *same* SSH connection the file transfers use (no second login). It is its own
persistent session (one per open server, keyed to that connection), with its own
backdrop; the backdrop follows whichever shell you last used, local or remote.
Commands `cd` into the panel's remote directory first, so they run where you are
browsing. (FTP has no shell, so an FTP panel keeps using the local shell.)

> **Windows note.** The persistent behind-the-panels console is a Unix feature.
> On Windows the command line and `Ctrl-O` instead run **the classic way**: the
> panels are suspended while `cmd.exe` runs (a command line runs once and waits
> for a key; `Ctrl-O` opens an interactive shell until you type `exit`), then the
> panels return. There is no live console backdrop, and shell state is not carried
> between separate runs — each command runs in the active panel's directory.


## Getting started — two-panel basics

- **Switch the active panel** with **Tab**. Everything you do (open, copy,
  select…) happens in the active panel.
- **Move the cursor** with the arrow keys, **PgUp** / **PgDn**, **Home** /
  **End**.
- **Enter a directory** by moving the cursor onto it and pressing **Enter** (or
  double-clicking it). The `..` entry at the top goes up to the parent.
- **Open a file** with **Enter** to hand it to the system default application
  (`xdg-open` on Linux). Use **F3** to view it or **F4** to edit it in the
  built-in tools instead.
- **Copy** the highlighted file (or the selected files) to the *other* panel
  with **F5**; **move/rename** with **F6**; **delete** with **F8**. Because the
  other panel is the default destination, the usual workflow is: point one panel
  at the source, the other at the destination, then press F5/F6.
- **Make a directory** with **F7**.

The active panel always provides the *source* for operations, and the inactive
panel the *destination* — so two panels make copying and moving between two
places fast and obvious.

### The mouse

The mouse works throughout:

- **Left-click** a file to move the cursor to it (and activate that panel);
  **double-click** to open it (like Enter).
- **Right-click** a file to invert its mark (tag/untag it).
- **Drag** with the left button to carry the cursor; **right-drag** flips the
  mark of every file it sweeps over (each file once).
- Click the **`◀`** arrow (a panel's top-left corner) or the **`▶`** arrow (its
  top-right corner) to step that panel **back / forward** through its directory
  history.
- Click a **menu-bar title** to open it and an entry to run it.
- Click the bottom **F-key bar** to run that function.
- Click **OK / Cancel** (or **Yes / No**) buttons in dialogs, and the
  **Abort** button on a scan/search progress dialog.
- In any dialog with input fields — **Copy/Move**, **Make directory**,
  **Chmod**, **Chown**, **Checksum**, **Select/Unselect group**, the
  **FTP/SFTP/SCP connection** form, **Settings**, **Confirmations**, **Find
  file**, editor **Search/Replace**, and more — click a **text field** to focus
  it and place the caret, click a **checkbox** or **radio** to toggle it, click a
  **dropdown** to open and pick from it, and click **OK/Cancel** to finish.
- Click an entry in the **user menu** (F2) or the **shell-history** window to run
  / recall it.
- In the **disk explorer**, click a box to select it and **double-click** to
  enter that subdirectory.


## Keyboard shortcuts

On terminals where the function keys are awkward, every `Fn` shortcut also has a
Midnight-Commander-style alias: press **Esc** then a digit — `Esc 1` … `Esc 9`
for `F1`…`F9`, and `Esc 0` for `F10` (works in the panels, viewer and editor).
A quick **Alt** + digit does the same.

### Panels

- `F1` — Help (this manual)
- `F2` — User menu (configurable)
- `F3` — View file
- `F4` — Edit file
- `F5` — Copy
- `F6` — Rename / move
- `Shift-F6` / `Ctrl-F6` — Multi rename (the selected files)
- `F7` — Make directory
- `F8` — Delete
- `F9` — Pulldown menu (Left/Right follows the active panel)
- `F10` — Quit (with confirmation)
- `Ctrl-Q` — Quit immediately
- `Tab` — Switch the active panel
- `↑ ↓` / `PgUp PgDn` / `Home End` — Move the cursor
- `Enter` — Open dir / enter archive / open file / run the command line
- `cd <dir>` + `Enter` — Change the active panel's directory
- `Insert` / `Ctrl-T` — Tag the file and advance
- `+` / `-` / `*` — Select / unselect a group (by wildcard) / invert the selection
- `← →` — Move within the command line
- `Alt-Enter` — Copy the name under the cursor onto the command line (appended,
  and shell-quoted when it contains spaces or special characters)
- `Alt-P` / `Alt-N` — Recall the previous / next command from history into the
  command line, replacing its contents (press again to keep cycling)
- `Alt-Shift-H` — Open the **Shell History** window just above the command line: move
  with `↑`/`↓` (or `Alt-P`/`Alt-N`) and press `Enter` to copy the chosen command
  into the command line **without running it**; `Esc` closes it
- `Alt-S` / `Ctrl-S` — **Quick search** the active panel: opens an empty search
  box; each letter you type filters, jumping the cursor to the first file whose
  name starts with it (case-insensitive; `Shift` for uppercase works). The box
  stays open even when empty — `Backspace` trims it, and only `Esc` or an arrow
  key dismisses it. `Enter` opens the match. With the command prompt hidden
  (`Ctrl-F5`), simply typing a character starts it
- `Ctrl-O` — Step into the persistent shell full-screen and back (press again to
  return). It is the **same session** the command line runs in — see *The
  console* above
- `Ctrl-P` — Open the **Command palette** (fuzzy search over every action,
  setting, bookmark and open connection — see *The command palette* below)
- `Alt-←` / `Alt-→` (or Midnight-Commander's `Alt-y` / `Alt-u`) — Go **back** /
  **forward** through the directories the active panel has visited. The clickable
  `◀` (top-left) and `▶` (top-right) arrows on each panel's border do the same
  (and are dimmed when there is nowhere to go that way) — see *Directory history*
  below
- `Alt-H` — Open the **Directory History** window: the same history the arrows
  step through, as a pickable list — see *Directory history* below
- `Alt-I` — Point the **other panel** at this panel's directory, so both show the
  same place
- `Alt-O` — Show the directory under the cursor **on the other panel** and step
  down one entry (with the cursor on a file, the other panel gets *this*
  directory instead) — so holding `Alt-O` walks a listing while the other panel
  keeps pace
- `Alt-T` — Cycle the active panel's **view format** (full → brief → details →
  tree)
- `Ctrl-\` — Open the **directory hotlist** (your bookmarked directories): jump
  to one, add the current directory, or remove one — see *The directory hotlist*
  below
- `Alt-Shift-I` — Set or clear the active panel's **persistent listing filter** (a
  shell glob like `*.rs`, or plain text; a blank entry clears it) — distinct from
  the quick-search cursor jump; see *The listing filter* below
- `Alt-G` — Open the **Git menu** (status, log, commit, fetch/pull/push, checkout,
  reset, init, clone …) — see *The Git menu* below
- `Ctrl-G` — **Stage / unstage** the file(s) under the cursor (git) — see
  *Git-aware panels* below
- `Alt-D` — Open a side-by-side **diff of the file against its committed (`HEAD`)
  version** (git) — see *Git-aware panels* below
- `Ctrl-R` — Re-read (refresh) the active panel
- `Ctrl-E` — Toggle reverse sort order (choose the sort key from the panel menu)
- `Alt-T` — Cycle the view format (full → brief → details → tree)
- `Ctrl-X` — Toggle vertical / horizontal split
- `Ctrl-U` — Swap the two panels
- `Ctrl-F1` / `Ctrl-F2` — Hide (and show again) the left / right panel,
  Norton-Commander style. Each panel keeps its own half; hiding one exposes the
  **console** underneath (see below), and both may be hidden at once. The menu
  bar and F-key bar always stay on screen
- `Ctrl-F4` — Toggle **half-height** panels: both panels shrink to the top half
  of the screen, exposing the console beneath them
- `Ctrl-F5` — Show / hide the **command prompt** below the panels. With it hidden
  the panels take over its row, and typing any printable character starts a quick
  search instead of entering text — see *Working without the command prompt* below
- `Alt-F1` / `Alt-F2` — Drive / connection picker for the left / right panel
- `Alt` + a menu letter (`F`/`O`/`C`/`L`/`R`) — Open that top menu (Midnight-
  Commander style); `F9` opens the menu bar too

### Editing text input lines

The command line and every dialog input field (copy/move destination, make
directory, find, rename, connection details, …) share the same Emacs/readline
key bindings:

- `Ctrl-A` / `Ctrl-E` — Move to the beginning / end of the line
- `Ctrl-B` / `Ctrl-F` — Move one character left / right
- `Alt-B` / `Alt-F` — Move one word backward / forward
- `Ctrl-H` / `Backspace` — Delete the previous character
- `Ctrl-D` / `Delete` — Delete the character under the cursor
- `Alt-Backspace` / `Alt-Ctrl-H` — Delete the previous word
- `Ctrl-@` (or `Ctrl-Space`) — Set the mark for cutting
- `Ctrl-W` — Cut the text between the mark and the cursor into the kill buffer
- `Alt-W` — Copy that text into the kill buffer (without removing it)
- `Ctrl-K` — Kill (cut) from the cursor to the end of the line
- `Ctrl-Y` — Yank (paste) the kill buffer at the cursor

The kill buffer is shared, so text cut in one field can be yanked into another.
On the **command line only**, `Ctrl-E` and `Alt-F` keep their panel meaning
(reverse sort / File menu) while the line is empty, and switch to editing as soon
as it has text. `Ctrl-W` is always the editing key — the listing-type toggle it
used to share now lives on `Alt-T`.

### Viewer (F3)

- `F1` — Help (opens this manual)
- `F2` — Toggle line wrap
- `F4` — Toggle hex / text mode
- `F5` — Goto (line / percent / byte offset)
- `F6` — (Markdown files) show the document outline — a tree of the headings.
  Use `↑ ↓` / `PgUp PgDn` / `Home End` or the mouse to pick a heading, `Enter`
  (or a click) to jump to it, `Esc` / `F6` to dismiss. Opening this manual with
  `F1` lands on its outline.
- `F7` — Search
- `F8` — (Markdown files) toggle Raw / Render; (image files) toggle Image / Raw
- `n` — Repeat the last search
- `↑ ↓` / `PgUp PgDn` / `Home End` — Scroll
- `F3` / `Esc` / `F10` / `q` — Close (F3 toggles the viewer, as in the panels)

### Editor (F4)

- `F1` — Editor shortcut help (any key closes it)
- `F2` — Save
- `Shift-F2` / `Ctrl-F2` — Save as… (browse + name)
- `F3` — Start / end a block mark
- `F4` — Search & replace
- `F5` — Copy the block to the cursor
- `F6` — Move the block to the cursor
- `F8` — Delete the block
- `F7` — Search
- `Ctrl-C` / `Ctrl-V` — Copy the block to the clipboard / paste
- `Ctrl-Z` / `Ctrl-Y` — Undo / redo
- `Shift+arrows` (or `Shift+Ctrl-arrows`) — Mark text while moving
- `Ctrl-Home` / `Ctrl-End` — Start / end of the document
- `Ctrl-← / →` — Move by word
- `F9` — Toggle the in-place hex editor
- `Shift-F9` / `Ctrl-F9` — Toggle word wrap
- `Esc` / `F10` — Quit (prompts if modified)

While **Shift** or **Ctrl** is held, the F-key bar relabels **F2 → Save as**
and **F9 → Wrap** to show those alternates.

The editor remembers where you left the cursor in each of the last **50** local
files (in `editor-positions.toml`); re-opening a file restores the cursor and
scrolls so it sits in the vertical center of the view.

### Hex editor (F9 in the editor)

- `0`–`9`, `a`–`f` — Overwrite the current byte's nibble (hex column)
- typed character — Overwrite the current byte (ASCII column)
- `Tab` — Switch between the hex and ASCII columns
- `← ↑ ↓ →` / `PgUp PgDn` — Move; `Home` / `End` — start / end of row
- `Ctrl-Home` / `Ctrl-End` — Start / end of file
- `F7` — Search (hex bytes like `48 65` or text)
- `F4` — Replace all (same length, overwrite-only)
- `F2` — Save the changed bytes in place
- `F9` — Back to text mode
- `Esc` / `F10` — Quit (prompts if modified)

### Process explorer

- `↑ ↓` / `PgUp PgDn` / `Home End` — Move the selection
- `Tab` — Switch between the flat list and the process tree
- `→` / `←` / `Enter` / `Space` (tree mode) — Expand / collapse the selected process (`←` on a collapsed row jumps to its parent)
- `*` (tree mode) — Collapse every subtree, or expand them all again
- `c` / `m` / `t` / `n` / `u` / `p` — Sort by CPU / memory / threads / program / user / PID (again to reverse)
- `r` — Reverse the sort order
- `+` / `-` — Adjust the refresh interval
- `k` / `F8` / `F9` / `Del` — Kill the selected process (SIGTERM, with confirm)
- `K` — Force-kill (SIGKILL, with confirm)
- `Esc` / `F10` / `q` — Close

### Disk explorer

- `← ↑ ↓ →` — Move the selection between boxes
- `Enter` — Dive into the selected subdirectory
- `Backspace` — Go up to the parent
- `g` / `Ctrl-Enter` — Exit and open the selected directory in the active panel
- `Esc` / `F10` / `q` — Close

### Dialogs

`Tab` / arrows move between fields, `Space` toggles checkboxes and cycles
choices, `Enter` confirms, `Esc` cancels. Progress dialogs can be aborted with
`Esc`. You can also click the buttons with the mouse.

### Theme editor

Opened from **Options → Edit themes…**. `Tab` / `Shift-Tab` cycle the four panes
(theme picker, color list, color picker, buttons).

- **Theme picker** — `↑ ↓` / `← →` choose the theme to edit; `Home` / `End` jump
  to the first / last. Switching with unsaved edits prompts to save, discard, or
  cancel.
- **Color list** — `↑ ↓` / `PgUp PgDn` / `Home End` select the element to
  recolor; `Enter` / `→` jump to the color picker.
- **Color picker** (truecolor) — `↑ ↓` pick the R / G / B channel; `← →` adjust
  it by 1, `Shift-←` / `Shift-→` by 20, `PgUp` / `PgDn` by 16, `Home` / `End`
  set it to 0 / 255; `Enter` returns to the list. On a 16-color terminal the
  picker is a swatch grid moved through with the arrows.
- **Type a hex code** — from either the color list or the picker, type a
  six-digit hex code (e.g. `1a2b3c`) to set the selected color directly;
  `Backspace` edits it and `Esc` cancels the entry.
- **Buttons** — `← →` move between **Save**, **Save as…** and **Cancel**;
  `Enter` / `Space` activates.
- `F2` / `Ctrl-S` — Save and close. `Esc` / `F10` — Close (prompts to save,
  discard, or cancel if there are unsaved changes).
- **Mouse** — click a row in the color list to select it and the wheel scrolls
  it; click a channel bar to set its value; click a swatch; click **Save** /
  **Save as…** / **Cancel** or the confirmation-dialog buttons.

The right-hand **preview** updates live, showing whichever surface the selected
element affects: the file panels, a demo dialog, or a small editor.


## Selecting (tagging) files

Most operations act on the **selection** — the set of *tagged* files — or, when
nothing is tagged, on the file under the cursor.

- **Tag the current file and advance** with **Insert** (so you can tag a run of
  files quickly).
- **Right-click** a file (or right-drag across several) to toggle tags with the
  mouse.
- **Select a group** with **`+`**: a dialog asks for a pattern. By default it is
  a shell wildcard (`*.txt`, `img_??.png`); untick *Using shell patterns* to use
  a regular expression. *Files only* limits it to files, and *Case sensitive*
  controls matching.
- **Unselect a group** with **`-`** (same dialog).
- **Invert the whole selection** with **`*`**.

Tagged files are shown in the selection color. The mini status line reports how
many are tagged and their combined size.


## View formats and sorting

Each panel can show its listing three ways; cycle them with **Ctrl-W** or pick
one from the **Left** / **Right** menu:

- **Full** — one file per row with name, size and modification time.
- **Brief** — names only, in multiple columns (more files at a glance).
- **Details** — the panel shows no listing of its own; instead it displays
  **information about whatever the *other* panel points at**:
  - on a **file**, a full overview — name, path, type, size (and exact byte
    count), permissions, owner/group, timestamps and inode;
  - on a **directory**, the **total recursive size** of everything beneath it,
    computed in the background and updated live as it scans (so even large or
    remote trees stay responsive);
  - on a **multi-file selection**, a tally of the combined size and the number
    of files and directories included.

  Beneath the metadata, a **preview** of the item is shown (loaded in the
  background so large or remote items stay responsive):
  - a **text file** → a syntax-highlighted view of its first lines;
  - an **image** → a thumbnail — a true-pixel image where the terminal supports
    graphics (Kitty / Sixel / iTerm2), or half-block cell art otherwise —
    **centred** in the panel. An embedded EXIF thumbnail is used when present (so
    a full-resolution photo isn't decoded just to shrink it), and a short **EXIF
    summary** (camera, lens, date, exposure) is shown above it when the image
    carries one;
  - an **archive** (`.zip`, `.tar.*`, `.7z`, …) → its top-level file list;
  - a **directory** → a shallow tree of its contents.

  This is useful for inspecting a file's metadata, glancing at its contents, or
  measuring how much space a folder or a set of tagged items uses, while you
  browse with the other panel.
- **Tree** — the directory structure is visualized as a tree, arrow keys navigate,
  pressing enter changes the opposite panel's directory and opens up the directory
  structure underneath.

**Sorting** is configurable from the **Left** / **Right** menu; **Ctrl-E** toggles
reverse order. The keys are: Unsorted, Name, Extension, Size,
Modify / Access / Change time, or Inode — with reverse, case-sensitive and
executables-first toggles.

Filenames carry an `ls -F`-style **type marker** so kinds read by symbol, not
just color: `/` directory, `*` executable, `@` symlink, `!` broken symlink, and
a leading space for plain files (keeps names aligned). File **names are colored**
by type as well: archives, documents, images and audio/video each get a hue.

**Nerd Font symbols.** Turning on *Options → Settings → Nerd Font symbols*
replaces those markers with a per-type icon — a folder, a chain link (broken for
a dangling one), and a glyph picked from the file itself: its language for source
files (Rust, Python, Go, …), the category for documents, images, audio, video,
archives, fonts, keys, databases and binaries, and a few whole names that carry
no extension (`Makefile`, `Dockerfile`, `LICENSE`, `.gitignore`, `Cargo.toml`, …).
Anything unrecognized gets a blank page, or a gear if it is executable. The glyph
is followed by a space, so names line up exactly as they do without it. This
needs a [Nerd Font](https://www.nerdfonts.com/) selected in your terminal —
preferably a **Mono** variant, whose icons are one cell wide — which is why it is
off by default; without one the listing shows replacement boxes.


## File operations

### Copy, move, delete

**F5** copies, **F6** moves/renames, **F8** deletes the selection (or the file
under the cursor). Copy and move open a dialog with the destination prefilled to
the other panel's directory — edit it to copy somewhere else, then confirm.

Long operations show a **progress window** with a per-file gauge, an overall
gauge, and a live **transfer-speed chart**. Press **Esc** to abort; a partly
written destination file is cleaned up.

**Overwrite handling.** When a destination already exists, a prompt offers
**Yes** / **No** for that file, **Append**, or a rule applied to all remaining
files — **All**, **Older** (only if the source is newer), **None**,
**Smaller**, or **Size differs** — with an optional guard that refuses to
overwrite a file with a zero-length one.

These operations work **transparently between local, remote and archive
panels**, so copying a file onto an SFTP server or out of a `.zip` is the same
F5 you already use.

### Background file transfers

A **To Background** button is available on most progress dialogs and sends the
currently running operation into the background. Multiple copy or file transfer
operations can run in parallel. A total progress bar will be shown on the top 
menu bar, and a list of all running background operations can be shown via 
**File → Background operations**

### Make directory, rename

**F7** makes a directory. **F6** on a single file renames it (or moves it if you
give a path). For renaming many files at once, use Multi rename (below).

### Permissions, ownership, symlinks

From the **File** menu:

- **Chmod** — set the permission bits of the selected files with checkboxes (the
  resulting octal mode is shown). A **Recurse into directories** checkbox applies
  the change through any directories in the selection.
- **Chown** — set the owner and group of the selected files (by name or numeric
  id), with the same recursion option.
- **Symlink** — create a symbolic link in the *other* panel pointing at the file
  under the cursor (both fields are prefilled and editable).


## Multi rename

*File menu → Multi rename…*, or **Shift-F6** / **Ctrl-F6**.

Batch-renames the **tagged** files using a naming mask, with a
live two-column preview — original names on the left, projected names on the
right — that scroll together so you can check each result before committing.

**Useful for** numbering a set of photos, normalizing extensions or case,
stripping or inserting text across many files at once.

**Usage:** Tag the files, open Multi rename, type a mask, watch the
right column update, then press **Execute**.

**The mask** is plain text plus placeholders that pull pieces from each original
name:

- `[N]` — the name without extension; `[N1-3]` a slice of it (characters 1–3),
  `[N3-]` from character 3 to the end, `[N2]` a single character
- `[E]` — the extension; `[E1-2]` a slice of it
- `[C]` — a running counter
- `[YMD]` — the date (`YYYYMMDD`)
- `[hms]` — the time (`HHMMSS`)

**Options.**

- **Case** — leave the case unchanged, force lowercase, or force UPPERCASE.
- **Counter** — set the start value, the step, and the number of digits
  (zero-padded) for `[C]`.
- **Search & replace** — replace a substring in the generated names, with a
  case-sensitivity toggle.

Renames run in two phases through temporary names, so swaps and renumberings
can't clobber a file that hasn't been renamed yet, and an existing file outside
the batch is never overwritten.


## Find file

*Command menu → Find file…*

Searches a directory tree for files matching a name pattern
(and optionally containing some text), then *panelizes* the results into the
active panel.

**Useful for** locating a file when you only remember part of its name, or
finding every file that mentions a string.

**Usage:** Open the dialog, set the start directory, the file-name
pattern, and (optionally) content to look for, then run it. A live progress
dialog counts matches; press **Esc / Enter** to stop early — the results found
so far are kept. The matches replace the panel listing with a flat list; a `..`
entry at the top returns to normal browsing.

**Options** include recursive search, case sensitivity, skip-hidden, and shell-
wildcard vs. regular-expression name matching. On a **remote** panel the search
matches **file names only** (content search is local).


## Compare directories

*Command menu → Compare directories…*

Compares the two panels' directories and **tags the files that
differ**, so you can act on just those.

**Useful for** spotting what changed between two copies of a tree, or what is
missing on one side.

**Modes.**

- **Quick (name)** — tag files present in one panel but not the other.
- **Size only** — also tag the larger of two files that share a name but differ
  in size.
- **Content** — tag both files whenever their bytes differ.

The comparison only *looks* at the top level of each directory and only tags
what it finds. To act on the differences — including inside subdirectories —
press **Synchronize…** in the same dialog (see below).


## Synchronize directories (mirror)

*Command menu → Synchronize directories…*, or the **Synchronize…** button in the
Compare-directories dialog.

Makes one directory tree match another, **recursively**. The active panel is
always the **source** and the other panel the **destination** — the same
direction as F5/F6 — and both dialogs spell the two paths out so there is no
doubt which way round it runs.

**Useful for** keeping a backup, a USB stick, or a server copy up to date:
*"mirror this folder to my SFTP server"* is this dialog.

**Remote and archive panels.** The sync runs over the same filesystem layer as
copy/move, so either side can be a remote connection — but what a backend can
report and store differs, and that changes what sync can do:

| Panel | Sync support |
| --- | --- |
| **Local** | Full — compares size + time, and stamps copies with the source's time. |
| **SFTP** | Full, exactly as local (SFTP reports *and* can set file times). |
| **FTP / SCP** | These report no file times, so files are compared **by size only** and each run re-copies nothing it doesn't have to. A same-size edit is not noticed. **Two-way is refused** — "newer wins" can't be decided without times. |
| **Archive** | May be the **source**, never the destination: an archive is rebuilt as a whole rather than written file by file, so syncing *into* one is refused up front. |

**Modes.**

- **One-way: copy new and changed files** — anything missing from or different on
  the destination is copied over. Nothing is ever removed. The safe default.
- **One-way mirror: also delete extraneous files** — as above, plus **anything
  the source doesn't have is deleted from the destination**, so it ends up an
  exact copy. This throws data away; the preview is flagged in red and opens on
  Cancel.
- **Two-way: newer file wins** — a file on only one side is copied to the other;
  a file on both sides is replaced by whichever copy is newer. Nothing is ever
  deleted. If the two have the same time but different contents, the **source**
  (active panel) wins rather than the choice being arbitrary.

**How files are compared.** By **size and modification time** — a file counts as
changed when either differs. Times within **two seconds** are treated as equal,
since filesystems disagree about resolution (FAT rounds to 2 s, some remotes
report whole seconds) and without that slack an untouched file would be copied on
every run. A backend that reports no timestamp at all falls back to size alone.

**The preview.** Nothing is touched until you approve it. Comparing the trees runs
in the background (it can take a moment over a slow link), then the plan is shown
in full:

- Each line is one step: `→ file` copies to the destination, `← file` copies back
  (two-way only), `✗ delete file` removes one, and `mkdir dir/` creates a
  directory. Deletions are red.
- A summary gives the totals — how many files to copy, how many bytes, how many
  to delete.
- Scroll with `↑`/`↓`/`PgUp`/`PgDn`/`Home`/`End` or the wheel; `Tab` moves between
  **Execute** and **Cancel**; `Esc` cancels. If the trees already match, it says
  so and offers only Cancel.

**Execution.** Execute hands the plan to the ordinary file-transfer engine, so a
sync behaves like any copy: a progress window with a speed chart, **Abort**, and
**To background** — which is what makes the "mirror to my server while I carry on
working" case practical. It shows up in *Background operations* like any other
transfer.

**Notes.**

- A copied file is stamped with its **source's** modification time, so a second
  run has nothing to do rather than re-copying the tree. (Local and SFTP
  destinations can do this; see the table above for the rest.)
- The order is deliberate: directories are created first, copies next, and
  extraneous deletions **last** — so a failed transfer never costs you data that
  was only about to be replaced.
- An extraneous *directory* is removed in one recursive step rather than listed
  file by file.
- If one side has a file where the other has a directory, only the deleting
  mirror mode resolves it (by removing and replacing). The other modes leave that
  path alone rather than guess.
- Search-result (panelized) listings can't be synchronized — they aren't
  directories.


## Find duplicates

*Command menu → Find duplicates…*

Tags the files that are **identical between the two panel
directories**, by criteria you choose.

**Useful for** finding copies of the same file in two places before deleting the
redundant ones.

**Usage:** Point the two panels at the directories to compare, open
the dialog, choose what "identical" means, and run it. A cancellable progress
dialog runs the comparison — important for content comparison and remote
filesystems, where it can take a while.

**Options.** File names are always compared; tick any of **size**, **date/time**
and **content** to require those to match too (with none ticked, only names are
compared). A **Case-sensitive** name-match toggle is on by default.


## Compare files (side-by-side diff)

*Command menu → Compare files…*

Opens a full-screen, side-by-side **diff** of the two files
under the cursor in each panel, with changed and added blocks highlighted and
connected by gutter guides.

**Useful for** reviewing differences between two versions of a file and merging
selected changes between them.

**Operation.**

- `↑ ↓` moves through the document and selects the active change.
- `Ctrl-↑ / ↓` jumps to the previous / next change.
- `Ctrl-←` applies the active change from the right file to the left (or deletes
  a left-only block); `Ctrl-→` applies it the other way.
- Edits happen in memory; **F2** asks to save and writes the changed file(s)
  back to disk. **Esc** closes (prompting save / discard / cancel when there are
  unsaved changes).


## Checksum a file

*File menu → Checksum…*

Computes a checksum of the file under the cursor and, if you
paste a reference checksum, tells you whether they match — handy for verifying a
download against the digest published alongside it.

**Operation.**

- Pick the algorithm (**CRC32**, **MD5**, **SHA-1**, **SHA-256**, **SHA-512**),
  optionally paste a checksum into *Compare to* to check against, and press
  **OK**.
- A progress bar tracks the calculation while the file is read (**Esc** aborts).
- The result dialog shows the computed digest. When you supplied a comparison
  value it also shows a green **✓ MATCH** or red **✗ MISMATCH** verdict (the
  comparison ignores case and whitespace). Press **OK** to close it.

Works on local files, files inside archives, and files on a remote panel.


## Send a file over the LAN

*File menu → Send over LAN…* (also in the command palette).

Shares the highlighted file with another device on the same network — a phone,
a tablet, or a laptop — without any cloud service, account, or cable. Rat
Commander starts a small one-shot HTTP server and shows the download URL as a
**QR code**; scan it with the other device's camera and the file downloads.

**Operation.**

- Put the cursor on a file (or **tag** several files / a directory) and choose
  **Send over LAN**.
- A single file is served as-is. A **multi-file or directory** selection is
  **zipped** first, with a progress bar; the zip is named after the directory.
- The dialog shows the **QR code** — a true-pixel image on terminals with a
  graphics protocol (Kitty / Sixel / iTerm2), or **half-block cell art**
  otherwise — plus the URL, the file name and size, and a live count of
  completed downloads. The QR is always drawn black-on-white so a phone camera
  reads it regardless of your colour theme.
- Scan the code (or type the URL) on a device on the **same network**. The URL
  uses a **LAN IP address** (a private one is preferred when the machine has
  several) and a **free port** chosen automatically.
- Press **Esc**, **Enter**, or click to **close** the dialog. Closing stops the
  server immediately and deletes any temporary zip — the link stops working, so
  keep the dialog open until the transfer finishes.

**Notes.**

- The server binds all interfaces on the LAN so any device on the subnet can
  reach it; it only ever serves this one file and forgets everything when closed.
- Only **local** files can be sent (a remote or in-archive panel has nothing on
  local disk to serve). Firewalls that block inbound connections on the chosen
  port will stop the download.


## The viewer (F3)

A read-only file viewer with text and hex modes, search,
syntax highlighting, a Markdown render mode, and a fullscreen image view.

**Useful for** quickly reading a file — including very large ones — without
loading it into an editor.

**Operation and options.**

- **Image view** — opening a supported image (`.png`, `.jpg`/`.jpeg`, `.gif`,
  `.bmp`, `.webp`) shows it **fullscreen**, centred: a true-pixel image on
  terminals with a graphics protocol (Kitty / Sixel / iTerm2), or **half-block
  cell art** otherwise. The header shows the original pixel dimensions. Press
  **F8** to toggle between the image and the **raw** bytes (as text/hex), and
  **F4** switches that raw view between text and hex. If a file can't be decoded
  as an image, the viewer just opens it as raw text/hex as usual.
- **Text / Hex** — **F4** toggles. Hex mode shows an offset / hex / ASCII dump.
- **Line wrap** — **F2** toggles soft wrapping.
- **Search** — **F7** opens the **same search dialog the editor uses** (see
  *Search and replace* under the editor): Normal / Regular expression / Hex /
  Wildcard modes, with *Case sensitive*, *Backwards* and *Whole words*, plus the
  **Find all** button, which tints every line holding the term. **`n`** repeats
  the last search, and so does re-running the same one from the dialog — each
  repeat moves to the **next** occurrence and wraps at the end. Changing the term
  or any option starts again from the top. Search streams the file in windows, so
  it works on huge files without loading them.
- **Goto** — **F5** jumps to a line number, a percentage through the file, or a
  decimal/hex byte offset (in hex mode the line number is a 16-byte row).
- **Syntax highlighting** colors recognized source files, using a bundled theme
  matched to the active light/dark UI. It covers syntect's default languages
  plus bundled extras (TOML, INI, Dockerfile, HCL/Terraform, GraphQL, Protobuf,
  CMake, TypeScript/TSX, Kotlin, Swift, SCSS/Sass, Elixir, Zig, Nix and more).
- **Markdown view** — `.md` files open *rendered*: the markup (`#`, `**`, `` ` ``,
  links, …) is hidden, headings are colored by level, emphasis and inline code
  are styled, and list bullets and rules are drawn. Press **F8** (*Raw*) to see
  the raw source (still syntax-highlighted) and **F8** again (*Render*) to go
  back.
- **Hex-color swatches** — any `#rgb` / `#rrggbb` / `#rrggbbaa` token in the
  text has its `#` painted in the color it names, so colors in code and configs
  are visible at a glance.

The viewer is **paged from disk** — local files are read on demand, so even
multi-gigabyte files open instantly. Viewing a large file over a remote
connection streams it to a temporary copy first, behind a progress dialog you
can abort.


## The editor (F4)

An `mcedit`-style text editor with block operations, search
and replace, undo/redo, syntax highlighting, and an in-place hex editor.

**Useful for** quick edits without leaving the file manager.

**Launching straight into the editor.** Open a file in the editor without going
through the panels by starting the program as **`rc /edit <file>`** (a missing
file opens an empty buffer so you can create it). Omit the filename entirely —
**`rc /edit`** — to start on a blank, untitled buffer; the first save then acts
as **Save as**, prompting you for a name. The packages and installers also set
up an **`rcedit`** shortcut — a symlink to `rc` on Linux/macOS, a small
`rcedit.cmd` on Windows — so **`rcedit <file>`** (or bare **`rcedit`**) does the
same thing. In this mode, closing the editor exits the program (it does not drop
to the panels).

**Marking a block.** Mark text either with **Shift+arrows** (and
**Shift+Ctrl-arrows**) while moving, or with **F3** to start/end a mark. A
marked block **stays selected as you move the cursor** and **stays anchored to
its text across edits** — inserting or deleting before, after or inside it never
clears the selection (F3 again toggles a block off).

**Block operations.**

- **F5** — copy the block to the cursor position.
- **F6** — move the block to the cursor position.
- **F8** — delete the block.
- **Ctrl-C** / **Ctrl-V** — copy the block to the clipboard / paste it.

**Search and replace.** **F7** searches; **F4** opens search & replace. Both use
the same dialog, and the viewer (F3) uses it too:

- **Mode** — **Normal** (literal text), **Regular expression**, **Hex** (byte
  strings like `48 65 6c`), or **Wildcard** (`*` and `?`). In regex mode `^` and
  `$` anchor to **each line**, so `^fn ` finds every line starting with `fn `;
  `.` does not cross a line break.
- **Options** — *Case sensitive*, *Backwards*, *Whole words*, and, when
  replacing, *In selection*.
- **Buttons** — **OK** finds the next match (pressing Enter from any field does
  the same), **Cancel** closes, and **Find all** — between them — highlights
  **every line holding the term** at once.

**Find all** is for reading rather than jumping: the matching lines stay tinted
(in the theme's inactive-cursor shade) while you scroll, edit and search onward,
so you can see where the hits are without stepping through them. The highlight
survives ordinary searches and is replaced only by the **next Find all** — or
dropped when the editor closes. It honours the mode and options, so you can
highlight, say, every whole-word `foo` case-sensitively. The status line reports
how many lines were marked, and the cursor lands on the first of them.

**Saving.** **F2** writes the file in place. **Save as** (**Shift-F2** or
**Ctrl-F2**) opens a browser — navigate directories and type a file name,
prefilled with the current one — to write the buffer somewhere else; the editor
then continues editing the new file. If a normal save fails (a read-only
location, a permission error, …), the Save-as browser opens automatically with
the reason shown, so you can redirect the write without losing your work.

**Word wrap.** **Shift-F9** (or **Ctrl-F9**) toggles virtual word wrap: long
lines are shown across several screen rows without changing the file, and each
*continued* row ends in a **`>`** marker so soft wraps are distinguishable from
real line breaks. Cursor movement, scrolling and the mouse all follow the
visible (wrapped) rows; `WRAP` shows on the status line while it is on.

**Help.** **F1** brings up a list of the editor's keyboard shortcuts and what
they do; any key closes it. While **Shift** or **Ctrl** is held, the F-key bar
relabels **F2 → Save as** and **F9 → Wrap** to advertise those alternates (on
terminals that report held modifier keys via the enhanced keyboard protocol).

**Other.** **Ctrl-Z** / **Ctrl-Y** undo and redo. The status bar shows the byte
under the cursor, the line and column, and the totals. Syntax highlighting
updates incrementally as you type.

**Hex editor (F9).** Toggles an in-place offset / hex / ASCII editor. Only the
visible window is read and only changed bytes are written back, so arbitrarily
large files can be hex-edited (and a file too big to load as text opens straight
into hex mode). Editing is overwrite-only (length-preserving). **Tab** switches
between the hex and ASCII columns; **F7** searches for hex bytes (`48 65 6c`) or
text, **F4** replaces all (same length), **F2** saves the changed bytes.


## Archives — browsed like directories

Lets you walk into `.zip`, `.tar`, `.tar.gz`, `.tar.bz2`,
`.tar.xz`, `.7z` and `.rar` archives as if they were folders.

**Useful for** inspecting, extracting from, or adding to an archive without
unpacking it first.

**Operation.** Press **Enter** on an archive file to browse it. Copy files
**out** (F5 to a normal panel) or **in** (F5 from a normal panel into the archive
panel); **F8** deletes from the archive. To build a new archive, tag a selection
and use *File menu → Compress…*, choosing the format by the name you type
(`.zip`, `.7z`, `.tar.gz`, `.tar.bz2`, `.tar.xz`).

RAR archives are **read-only** — you can browse and extract them, but no tool can
create RAR archives. (RAR support is an optional build feature, on by default.)


## File associations and extfs (rc.ext)

Beyond the built-in archive formats above, Rat Commander can open a file type
with a command of your choosing — or browse it **as a directory** using a
Midnight-Commander **extfs** script. Both are configured in the **`rc.ext`**
file (Midnight Commander's `mc.ext` format), created with a few examples on first
run.

**Useful for** stepping into formats the built-in browser doesn't cover
(`.iso`, `.rpm`, `.deb`, `.lha`, …), and for wiring **Enter** / **F3** / **F4**
on a file type to your own commands.

**extfs — browse via scripts.** An `Open` rule of the form
`Open=%cd %p/<prefix>://` mounts the file with the extfs script named `<prefix>`
and shows its contents like a folder. Rat Commander runs the **same scripts as
Midnight Commander**, looked up in `~/.local/share/mc/extfs.d`,
`/usr/lib/mc/extfs.d` (and the other MC directories) plus your own
`~/.config/rat-commander/extfs.d`. So with MC installed, `.iso` (`iso9660`),
`.rpm` (`rpm`), `.deb` (`deb`) and the rest work out of the box. Inside a mount
you browse, copy **out** with **F5** (extract) or **in** with **F5** (add),
**F8** to delete and **F7** to make a directory — whatever that script supports;
an unsupported action reports a clear error. **..** at the top steps back out to
the file. (extfs scripts are shell/Perl/Python programs, so this is a Unix
feature.)

**Open / View / Edit commands.** A rule can also just run a command: `Open` on
**Enter**, `View` on **F3**, `Edit` on **F4**. A `View` beginning with
`%view{ascii}` (or `%view{hex}`) pipes the command's **output** into the built-in
viewer — e.g. `View=%view{ascii} unzip -v %f` shows the archive's contents
listing; a plain `Open` / `View` / `Edit` command runs in the foreground. When a
rule matches a file, its `View` / `Edit` takes precedence over the built-in
viewer / editor for that type.

Native archive browsing (the formats above) takes precedence over an extfs
`Open` rule, so `.zip` still opens with the fast built-in handler while `rc.ext`
covers everything else. The file format is detailed under
*Configuration → The rc.ext file format*.


## Remote filesystems (SFTP / FTP / SCP)

Mounts a remote server into a panel, so you browse and transfer
files over **SFTP** or **SCP** (SSH) or **FTP / FTPS** exactly like local files.

**Useful for** managing files on a server without a separate client — copy/move/
delete works transparently between local, remote and archive panels.

**Remote shell.** On an **SFTP/SCP** panel, the command line and **Ctrl-O** run on
the **remote host** over the same SSH connection — see *The console → On a remote
panel* above.

**Connecting.** Open the **Drive / connection picker** with **Alt-F1** (left
panel) or **Alt-F2** (right panel), or pick a protocol from the panel's
**Left** / **Right** menu. Enter host, port, user, password and an optional
remote path. Previously used servers are remembered (passwords are **not**
stored): open the **history dropdown** with the **▼** on the Host field, or by
pressing **↓** while the Host field is focused, to refill the form.

**FTP** connections have a **Passive mode (PASV)** checkbox (on by default): in
passive mode the client opens the data connection, which is what works behind
most NAT/firewalls; untick it for **active** mode, where the server connects
back. The choice is remembered per server. (SFTP and SCP tunnel their data over
the single SSH connection, so they have no such option.)

SSH host keys are checked against `~/.ssh/known_hosts` (trust-on-first-use; a
changed key is rejected).

**Connections behave like drives.** Every open connection stays alive as a
button in the picker, so you can switch a panel between **Local** and any server
at will — like drive letters. The **Local** button returns a panel to the local
filesystem *without* closing the connection (it even restores the local
directory you were last in); the connection is only closed by its own **✕
Disconnect** button, which asks for confirmation first. Several servers can be
open at once, and each remembers the directory you were last browsing on it. The
open connections (and a disconnect entry for each) also appear in the **Left** /
**Right** panel menus.

To keep things simple, **one panel is always local**: while one panel is on a
remote connection, the other panel's picker offers only Local and drive letters.
Return the remote panel to Local first to open a connection on the other side.
This avoids server-to-server transfers.

**Pulling a file down.** When the destination panel is remote, the copy/move
dialog prefills a `scheme://path` target (e.g. `scp-0:///home/user`). **Delete
the `scheme://` prefix** to redirect the copy to a **local** path instead — handy
for grabbing a file to disk while the remote connection stays open.


## The command line and subshell

The line at the bottom runs shell commands in the active panel's directory:
type a command and press **Enter**. The one special case is **`cd <dir>`**, which
changes the *active panel* (so the change sticks, unlike `cd` in a subshell);
`~`, `..`, and absolute or relative paths are supported.

For interactive work, **Ctrl-O** drops to a **full-screen persistent subshell**
in the current directory; press **Ctrl-O** again to return to the panels with
your shell session still alive. When the active panel is on an **SFTP/SCP**
server, that shell runs on the **remote host** over the same SSH connection (see
*The console → On a remote panel*).

On **Windows** this works differently (see the *Windows note* under *The
console* above): `Ctrl-O` opens a fresh interactive `cmd.exe` that you leave by
typing `exit`, and command-line commands run one at a time with the panels
suspended — there is no persistent behind-the-panels session.

### Working without the command prompt

**Ctrl-F5** hides the command line altogether (the same switch as **Command
prompt** in *Options → Settings…*, and a toggle in the command palette). The
panels take over its row, and the choice is remembered across sessions.

With it hidden, typing a printable character no longer enters text — it starts a
**quick search** on the active panel, seeded with that character, exactly as if
you had pressed `Alt-S` first. `Backspace` trims the query, `Esc` cancels, `Enter`
opens the match, and any other key leaves the search and does its usual job. The
selection keys keep their meaning: `+` and `-` still open the select / unselect
dialogs and `*` still inverts the selection.

The command-line-only keys (`Alt-Enter`, `Alt-P` / `Alt-N`, `Alt-Shift-H`) do
nothing while it is hidden. Everything that doesn't need the prompt still works:
**Ctrl-O** drops to the subshell, **F2** user-menu entries run their commands, and
`Enter` on a directory descends into it.


## The user menu (F2)

**F2** opens a configurable **user menu** of shell commands. It is created with
sensible defaults on first run and uses the Midnight Commander `menu` file
format (see *Configuration* below). Each entry runs commands against the current
file, the current directory, the other panel or the tagged files via macros, and
can be shown or defaulted **conditionally** — only when files are tagged, for a
matching file type or name, and so on. Useful for one-key access to your own
scripts and recurring tasks.


## The command palette (Ctrl-P)

*Command menu → Command palette…*, or **Ctrl-P**.

A single fuzzy-search box over everything the program can do, so you can reach a
command by name instead of hunting through menus.

**Useful for** running any action, changing a setting, or jumping somewhere in a
couple of keystrokes — without remembering which menu it lives in.

**Operation.** Type to filter; the list narrows as you go, ranking the tightest
matches first and highlighting the letters that matched. `↑`/`↓` (or the mouse
wheel) move the selection, `PgUp`/`PgDn` jump a page, **Enter** (or a click) runs
the highlighted entry, and **Esc** (or **Ctrl-P** again) closes it. The query is
a *fuzzy* match — `cf` finds *Compare files*, `dspl` finds *Disk explorer* — and
typing a family name (`bookmark`, `connection`, …) narrows to that family.

**What it lists**, shown with a colour-coded tag on the right:

- **Command** — every menu action (view, copy, compare, the explorers, the
  connection forms, the panel view/sort options for the active panel, …), run
  exactly as if picked from the menu.
- **Setting** (tagged *Options*) — switch the **theme**, **language** or
  **graphics** mode directly, or flip a toggle (truecolor, animations, the status
  widget, RTL reshaping, the internal viewer/editor, and each confirmation) in
  place. A `✓` marks the active theme/language/mode; toggles show `✓`/`✗`. The
  change is applied and saved immediately.
- **Bookmark** — jump the active panel to a saved directory, or **add / remove**
  the current directory. Bookmarks are local directories, persisted in
  `config.toml` (the `bookmarks` list); the **directory hotlist** (Ctrl-\, below)
  manages the same list.
- **Connection** — switch the active panel to any **open** remote session, or
  **reconnect** to a **saved** server (opens the connection form prefilled from
  history, ready for the password).


## Git-aware panels

When a panel is showing a directory inside a **Git working tree**, Rat Commander
reads its VCS status in the background (so even a large repository stays
responsive) and surfaces it in the listing and on the border.

**Per-file status.** Each entry's leading marker is replaced by a coloured status
glyph when git has something to say about it:

- **`>`** — **modified** in the working tree (unstaged changes).
- **`+`** — **staged** in the index (ready to commit).
- **`?`** — **untracked** (not yet added to git).
- **`!`** — **conflict** (an unmerged path).

A subdirectory that *contains* changes is flagged with the strongest state found
beneath it, so you can see where changes live without descending. The file name
is tinted the same colour as its glyph.

**Branch on the border.** The bottom-left of the panel border shows the current
branch, e.g. `⎇ main ↑2 ↓1` — the `↑`/`↓` counts are how many commits the branch
is **ahead** / **behind** its upstream (shown only when non-zero).

**One-key actions** (they act on the active panel's cursor file, or the tagged
files if any):

- **`Ctrl-G`** — **stage / unstage**. A staged file is unstaged; anything else is
  staged (`git add` / `git restore --staged`). The glyphs refresh immediately.
- **`Alt-D`** — open a **side-by-side diff against `HEAD`** — the committed
  version on the left, your working copy on the right — in the same
  [Compare files](#compare-files-side-by-side-diff) view. Use `Ctrl-←` to bring a
  hunk over from `HEAD` (discarding a change) and **F2** to write the working file
  back. An untracked file diffs against an empty left side. (The `HEAD` side is
  read-only, so it can't be written back over anything.)

Everything else lives in the [Git menu](#the-git-menu) below.

Git integration shells out to the `git` command; if `git` isn't installed, or the
directory isn't a repository, panels simply show no VCS info. Remote and archive
panels never show git status.


## The Git menu

**`Alt-G`**, or *File menu → Git* (it opens as a submenu; `→`/`Enter` opens it,
`←`/`Esc` steps back out). Every entry is also in the command palette — type
`git` to see them all.

The point is to cover the everyday git round trip without dropping to a shell,
and to *guide* rather than assume you remember the flags. Long-running commands
(fetch/pull/push/clone) run in the background, so the UI never freezes.

**Seeing what's going on.**

- **Status** (`S`) — `git status`, shown in a scrollable output box.
- **Log** (`L`) — the last 200 commits as a decorated graph, one line each.
- **Diff vs HEAD** (`D`, or **`Alt-D`**) — the side-by-side diff described above.

**Staging and committing** (these act on the tagged files, or the cursor file):

- **Add (stage)** (`A`) — `git add`.
- **Stage/unstage** (`G`, or **`Ctrl-G`**) — the toggle.
- **Unstage** (`U`) — `git restore --staged`.
- **Remove…** (`M`) — `git rm`: drops the files from the index **and deletes them
  on disk**, so it asks first.
- **Restore (discard)…** (`T`) — `git restore`: throws away uncommitted edits.
  Git cannot undo this, so it asks first.
- **Commit…** (`C`) — a message field plus *stage all tracked changes* (`-a`) and
  *amend the last commit*. An empty message cancels rather than letting git
  reject it.

**Exchanging with the remote.**

- **Fetch…** (`F`) — with *all remotes* and *prune* options (*all* is pre-ticked
  when the repo has more than one remote).
- **Pull…** (`P`) — with a *rebase instead of merge* option.
- **Push…** (`H`) — pick the **remote** from a dropdown, and optionally *set
  upstream*, *force with lease*, or *force*. **Force with lease** is the safer of
  the two (it refuses to clobber work that reached the remote after your last
  fetch) and wins if you tick both.
- **Sync** (`Y`) — pull then push in one step. A failed pull skips the push.

**Moving around and undoing.**

- **Checkout…** (`K`) — the **branch dropdown** lists your local branches (the
  current one first) followed by the remote-tracking ones; picking `origin/x`
  checks out `x` as a tracking branch rather than detaching HEAD. Type a name in
  the second field instead to **create** that branch.
- **Reset…** (`R`) — pick the **mode** (*soft* keeps the index and working tree,
  *mixed* keeps the working tree, *hard* discards everything) and the target
  commit (default `HEAD`).

**Starting a repository.**

- **Init repository…** (`I`) — `git init` in the panel's directory (confirmed).
  Offered only when the directory isn't already in a work tree.
- **Clone…** (`N`) — a URL, and optionally the directory name to clone into
  (blank lets git derive it from the URL). Clones into the panel's directory.

**Output.** Anything git prints — a push summary, a merge conflict, an error —
appears verbatim in a large scrollable box: `↑`/`↓`/`PgUp`/`PgDn`/`Home`/`End`
and the mouse wheel scroll, `←`/`→` pan sideways (long `log --graph` lines are
not wrapped), and **Close** / `Esc` / `Enter` dismiss it. A command that
succeeds silently (like `add`) shows no box at all; a failure is titled as such
and coloured. Afterwards the panels and the status glyphs are re-read
automatically.

All of these need the active panel to be on a **local** directory — a remote or
in-archive panel has no work tree to act on.


## Directory history (back / forward)

Each panel remembers the directories it has visited, like a web browser's history.

- **Go back** with `Alt-←` (or Midnight-Commander's `Alt-y`) to return to the
  directory you were in before the current one; **go forward** with `Alt-→` (or
  `Alt-u`) to retrace a step you went back from.
- Two small arrows sit on each panel's top border: **`◀`** (back) at the
  **top-left** corner and **`▶`** (forward) at the **top-right** corner.
  **Click** them with the mouse to navigate. Each is drawn brightly when there is
  somewhere to go that way and **dimmed** when there is not.
- Any move that changes a panel's directory — pressing Enter on a folder, `..`,
  `cd`, a bookmark jump, a tree selection, switching drives or servers — is
  recorded. Making a new move after going back discards the forward trail (again,
  like a browser). Each panel keeps its own independent history.

**The history window (`Alt-H`)**, also on *Command menu → Directory history…*,
shows the whole trail as a list rather than making you step through it:

- Entries are in visit order — everything you can go **back** to, then the
  current directory (marked **`▶`** and highlighted), then anything you can go
  **forward** to.
- Move with `↑`/`↓`/`PgUp`/`PgDn`/`Home`/`End` or the wheel, **Enter** (or a
  click) to jump straight there, `Esc` to close. Picking the directory you are
  already in just closes the window.
- Jumping is an ordinary move, so it is recorded on the history itself.

(The **shell** history window — recent *commands* — is `Alt-Shift-H`; the two
share the letter.)


## Sending a directory to the other panel

Two shortcuts move the *other* panel without leaving this one:

- **`Alt-I`** — point the other panel at **this panel's directory**, so both show
  the same place. Handy right before a copy, a compare, or a sync.
- **`Alt-O`** — show the directory **under the cursor** on the other panel, and
  step the cursor down one entry. Holding `Alt-O` therefore walks down a list of
  folders while the other panel previews each in turn. With the cursor on a
  **file** (or in an empty listing) the other panel gets *this* directory
  instead, which is the useful reading of "show me where I am".

Both are also on the *Command menu*, and both record the move on the other
panel's history like any navigation.


## The directory hotlist (Ctrl-\)

*Command menu → Directory hotlist…*, or **Ctrl-\**.

A list of **bookmarked directories** you can jump to instantly — the same
bookmarks the command palette shows and stores in `config.toml`.

- **Enter** (or a click) jumps the active panel to the highlighted directory.
- **`a`** or **Insert** adds the active panel's current directory to the list.
- **`d`** or **Delete** removes the highlighted entry.
- `↑`/`↓`, `PgUp`/`PgDn`, `Home`/`End` move the selection; **Esc** closes.

Edits (adds/removes) are saved to `config.toml` when the hotlist closes. Only
local directories can be bookmarked.


## The listing filter (Alt-I)

*Command menu → Panel filter…*, or **Alt-I**.

A **persistent** filter that hides files whose names don't match, until you clear
it — distinct from *quick search* (Alt-S / Ctrl-S), which only jumps the cursor
and never hides anything.

- Type a **shell glob** (`*.rs`, `img_??.png`) or **plain text** (matched
  anywhere in the name, case-insensitively — e.g. `report` shows every name
  containing "report"). Matching is case-insensitive.
- The active filter is shown in the panel's **title** as `[pattern]`, so it is
  obvious when entries are hidden. `..` is always kept so you can still navigate.
- The prompt is pre-filled with the current filter; submit an **empty** value to
  clear it. The filter is per panel and stays in effect as you browse and refresh
  (it is re-applied on each directory load). Marks on files the filter hides are
  preserved and reappear when the filter is cleared.


## Disk explorer

*Command menu → Disk explorer…*

Draws a full-screen **treemap** of the current directory: each
box's area is proportional to a subdirectory's total on-disk size, labeled with
the name and a human-readable size.

**Useful for** finding what is using your disk space.

**Operation.** Boxes that are large enough also show their **biggest files**
inside, each with its size, so you can spot space hogs without diving in. On a
terminal with graphics support (see *Terminal graphics*), the **whole treemap is
drawn as pixel "pillow" boxes**: each directory is a softly cushion-shaded box
**in its own hue**, subdivided into recessed, semi-transparent **sub-boxes** for
its largest files (sized by their share, with names labeled where they fit), so
every box reads as a little map of its own contents and much finer detail is
visible than with characters. It falls back to character-cell boxes on a plain terminal. The top
bar always shows the selected box's name, size and share of the total. **Arrow
keys** move the selection, **Enter** dives into a subdirectory, **Backspace**
goes up, **`g`** (or **Ctrl-Enter**) exits and points the active panel at the
selected directory, **Esc** closes. With the **mouse**, click a box to select it
and **double-click** to dive into it. Symlinks are never followed or counted.


## Process explorer

*Command menu → Process explorer…*

A full-screen, btop-style system monitor with a process table
and live graphs. It works on **Linux, Windows and macOS**.

**Useful for** seeing what's running and what's using the CPU, memory, disk and
network — and killing a runaway process.

**Operation.** The table has two layouts, toggled with **`Tab`**. **Flat** (the
default) is a single sortable list with **Pid**, **Program**, **Command**,
**Threads**, **User** and **MemB** columns. **Tree** shows the parent/child
process hierarchy, **fully unfolded** by default, with branch lines and a fold
box on each parent: **`[-]`** when open, **`[+]`** when folded; press **`→`**
(or **`Enter`**/**`Space`**) to unfold a subtree and **`←`** to fold it (or, on an
already-folded row, to jump to the parent), and **`*`** to fold/unfold the whole
tree at once. Individual threads are collapsed into their process's **Threads**
count rather than listed separately. Each row also shows CPU%, memory and a
per-process CPU sparkline; sort by **program, CPU, memory, threads, user or PID**
— in the tree, the sort orders each set of siblings while children stay grouped
under their parent. The layout adds a CPU-load line
graph and per-core meters, a memory sparkline, and two **centre-line graphs**
that split a metric into its two directions around a drawn **horizontal axis
line**: the **Disk** panel grows **writes upward (▲)** and **reads downward
(▼)**, and the **Net** panel grows **uploads upward (▲)** and **downloads
downward (▼)**, each direction scaled to their shared peak. **`+`/`-`** adjust the refresh interval.
**`k`** kills the selected process, **`K`** force-kills it; both ask to confirm.

A couple of details are platform-specific: on **Unix**, `k`/`K` send SIGTERM
/SIGKILL (graceful vs. forced), while on **Windows** both terminate the process
outright; the **battery** readout and per-process **thread counts** are shown on
Linux and read as unavailable on other platforms.


## Disk manager (Linux)

*Command menu → Disk manager…*

A two-pane manager of block devices and mounts: a
**disk → partition tree** on the left (each partition shows its filesystem type
and volume label) and the **current mounts** on the right. **Tab** switches panes.

**Useful for** mounting, unmounting, formatting and syncing drives without
leaving the file manager.

**Operation.** **Enter** (or double-click) a device for an action menu —
**Mount** / **Format** / **Flash image** / **Create image** when it's free, or
**Unmount** / **Flash image** / **Create image** when mounted. **Enter** on a
mount offers **Unmount** / **Sync**. Mounting prompts for a path (offering to
create it if missing); unmounting asks to confirm, and unmounting an **essential
system mount point** (`/`, `/boot`, …) raises a warning.

**Format** writes a fresh **FAT32, FAT16, VFAT, NTFS, EXT4/3/2 or BTRFS**
filesystem, with a volume label and filesystem-specific options (quick format,
bytes-per-inode), behind a destructive-action confirmation.

Privileged operations need root: when not run as root they use **`sudo`** —
non-interactively where possible, otherwise prompting for a password. Passwords
are never stored.


## Network connections (Linux)

*Command menu → Network connections…*

A full-screen view of the machine's sockets, split into two lists: **Listening
ports** (every open port with its owning program and **service name**) on top,
and active **Connections** below — each with its **type**
(`tcp`/`tcp6`/`udp`/`udp6`), state, local and peer address (with the peer's
service), program, the **incoming/outgoing traffic** it has carried (cumulative
bytes), the **live in/out rate** (bytes/sec), and a **per-connection rate
sparkline** of its recent throughput. The header shows totals and the current
overall down/up rate.

**Useful for** seeing what is listening on the machine, what it's talking to,
which programs are moving the most data, and spotting a busy or unexpected
connection at a glance.

**Operation.** On opening it asks for a **root password**. Enter one to see
*every* socket's owning program (full visibility); leave it **blank** to run in
**user mode**, where the connection lists are still complete but a program name
is shown only for your own sockets.

- **Tab** cycles the three views: **Listening ports → Connections → Overview
  diagram**. In the two lists, **←→** switch the focused list and **↑↓ /
  PgUp/PgDn / Home/End** (and the mouse wheel) scroll it.
- **`/`** starts a live **filter** — type to narrow the lists by program,
  address, port, state or service; **Enter** keeps it, **Esc** clears it. The
  filter also reshapes the overview diagram.
- **`s`** cycles the focused list's **sort** column, **`S`** reverses it.
- **`p`** cycles the protocol filter (all → tcp → udp), **`e`** toggles
  established-only, **`h`** toggles hiding loopback sockets.
- **Enter** opens a **details** popup for the selected socket (full command line,
  user, cumulative + live traffic, a rate graph, and the raw `ss` counters);
  any key closes it.
- **`k`** terminates the selected socket's owning process (SIGTERM), **`K`**
  force-kills it (SIGKILL) — both ask to confirm.
- **`r`** refreshes now, **`+`/`-`** change the auto-refresh interval, **Esc**
  closes the view.

**Overview diagram.** The third view (reach it with **Tab**) arranges the active
connections into a **responsive grid of service cards** — one card per service,
titled by its `proto :port name`. Each card lists the IP addresses talking to
that service, with a **◀** for **inbound** peers (someone connected to a port you
listen on) and a **▶** for **outbound** ones (you connected out). Colour encodes
the protocol: **cyan = TCP**, **green = UDP**, **yellow = both**. The diagram is
drawn with true terminal graphics when available, and with box-drawing characters
otherwise.

- **↑↓←→** move the cursor between IP addresses (nearest in that direction);
  **Home/End** jump to the first/last; **PgUp/PgDn** and the mouse wheel scroll.
- **Enter** or a **mouse click** on an address opens an **IP details** popup —
  direction, service, owning program(s), socket count, cumulative and live
  traffic, and a **reverse-DNS** hostname (resolved in the background via the
  system resolver; shows *resolving…* until it arrives, then caches the result).
- **`k` / `K`** act on the selected address's owning process, exactly as in the
  lists.

Data comes from `ss` (iproute2); the tool is offered only on Linux. The root
password, if given, is held in memory for the session so periodic refreshes can
re-run `sudo` without re-prompting, and is discarded when the view closes.


## Flash and image a disk (Linux)

**Flash an image to a disk.** Press **Enter** on a raw image file (`.iso`,
`.img`, `.raw`, `.bin`, `.dd`, …) to open a **target picker** listing every block
device and partition with its name, vendor/model, serial, label, filesystem and
size. Devices too small for the image can't be selected. Choosing a target asks
to confirm; a **non-removable** (fixed/system) disk raises an extra warning
first. The same flow is reachable from the disk manager's **Flash image** action,
which opens a small file browser to pick the image.

**Create an image of a device.** In the disk manager, the **Create image** action
on a device or partition opens a save browser to choose a directory and file
name (defaulting to `<device>.img`), then streams the device out to that file.


## Windows: drive letters

On Windows the **Drive / connection picker** (**Alt-F1** / **Alt-F2**, or the
panel menu's **Drive…** entry) shows the available **drive letters** on its first
row, with the current drive highlighted. Use the arrow keys or press a
drive-letter key to switch the panel to that drive. The **Local** button, any
open remote connections and the SFTP / FTP / SCP buttons appear below.

The command line and `Ctrl-O` shell also behave differently on Windows — see the
**Windows note** under [The console](#the-console-behind-the-panels): commands run
with the panels suspended (there is no persistent behind-the-panels console), and
`Ctrl-O` opens an interactive `cmd.exe` you leave by typing `exit`.


## Configuration

Configuration files live in your platform config directory
(`~/.config/rat-commander/` on Linux):

- **`config.toml`** — written by the Settings dialog. Holds the active theme and
  language, the truecolor / animation / status-widget / `nerd_font` toggles, the external
  editor and viewer commands, the confirmation flags, the remembered remote
  servers (without passwords), and your directory **`bookmarks`** (used by the
  command palette, Ctrl-P). It also holds `command_history_max` (default
  `100`) — the maximum number of command-line entries kept in the persistent
  history; set it to `0` to disable history. Finally it remembers the **session
  layout** — each panel's last directory, listing filter, visibility and
  half-height state, the split direction, and which side was active — and
  restores it on the next launch. The one exception is the initially-active
  panel, which opens at the current directory (where `rc` was launched) so you
  land where you were working; the other panel restores its saved directory (or
  the working directory if that directory is gone).
- **`history`** — the persistent command-line history, one command per line
  (recalled with `Alt-P` / `Alt-N` / `Alt-H`), trimmed to `command_history_max`.
- **`editor-positions.toml`** — the editor's cursor-position memory for the last
  50 files edited (see *Editor*).
- **`themes.toml`** — your editable themes (see *Themes*).
- **`lang/`** — the localization files, one TOML per language (see *Language*).
- **`menu`** — the F2 user menu (see below).
- **`rc.ext`** — file associations for Open/View/Edit actions and extfs mounts
  (see *The rc.ext file format*).

### Settings (Options → Settings…)

Choose the **theme** and **language**, toggle **truecolor**, **animations**, the
**system-status widget**, the **command prompt** (the shell line below the
panels — also `Ctrl-F5`; see *Working without the command prompt*), **Nerd Font
symbols** (per-file-type icons in the listing — see *Panels*; needs a Nerd Font
in your terminal) and **Reshape
RTL text** (see *Language*), pick the
**Graphics** mode (see *Terminal graphics* below), set an **external editor /
viewer** command (used instead of the built-in ones), and choose whether to use
the internal viewer/editor. When the external editor field is left blank, `rc`
falls back to the **`$VISUAL`** then **`$EDITOR`** environment variable; the
external viewer likewise falls back to **`$PAGER`**. Only if none of those is set
does the built-in tool run.

The **Theme**, **Language** and **Graphics** fields are dropdowns: press
**Enter** to open the scrollable list, **↑/↓** (or the mouse wheel) to move
through it, **Enter** to pick, **Esc** to close. They **preview live** as you
move the highlight — the UI re-colors / re-translates / re-draws immediately — so
**Enter** keeps the highlighted one and **Esc** (closing the dialog) reverts to
what you started with. The **Nerd Font symbols** box previews live in the same
way: the listings behind the dialog switch markers as you tick it, and go back on
**Esc**. In every dialog the **OK** and **Cancel** buttons are part
of the keyboard focus ring: **Tab** / **↑↓** move onto them and **Enter** or
**Space** activates the highlighted one (**Enter** still submits from a field and
**Esc** always cancels).

### Terminal graphics

Where the terminal supports a graphics protocol, the **progress bars**, the
**process-explorer graphs** (CPU, per-core, memory, disk and network), the
file-transfer **speed graph**, the **disk-explorer treemap** and the **dialog
buttons** (OK, Cancel, Yes/No, …) are drawn as true-pixel images with smooth
gradients instead of block characters. Buttons pick up the theme's button colors
and gain a drop shadow, with a soft glow around the focused one; their labels are
drawn with an anti-aliased font (Latin, Cyrillic and Greek). A button whose
translated label is in a script that font can't draw (e.g. Arabic or CJK) simply
falls back to a regular text button so it stays readable. It uses the
**Kitty**, **Sixel** or
**iTerm2** protocol — so Kitty, Ghostty, WezTerm, Konsole, foot, recent
xterm/VTE, iTerm2 and similar all get the richer rendering — and falls back
automatically to the classic cell rendering everywhere else, so nothing is lost
on a plain terminal.

The **Graphics** setting controls this: **Auto** (default — use pixel graphics if
the terminal supports them, else cells), **Off** (always use cells), or a forced
**Kitty** / **Sixel** / **iTerm2**. Turn it **Off** if your terminal mis-renders
the images. The setting previews live and reverts on **Esc**, exactly like the
theme. (In `config.toml` the key is `graphics = "auto"`.)

### Language

The UI language is chosen in Settings and applied immediately. Translations live
in the **`lang/`** directory of the config folder, one file per language.
**18 languages** are written there on first run — English, German, French,
Spanish, Portuguese, Dutch, Czech, Slovak, Hungarian, Serbian, Ukrainian,
Russian, Japanese, Chinese (traditional and simplified), Hindi, Persian and
Arabic. Each file starts with a `name` (what the language is called in the
chooser) and a `[strings]` table mapping the English source text to its
translation — any missing entry falls back to English, so a partial translation
still works. To **add a language**, copy an existing file (e.g. `en.toml`) to a
new name, change its `name`/`code`, translate the values, and it appears in the
Settings chooser automatically. In menu labels the `&` marks the keyboard-
accelerator letter (the non-Latin catalogs put it in a trailing `(&X)` so the
accelerators stay typeable).

**Right-to-left scripts** (Arabic, Persian) are handled with the **Reshape RTL
text** setting, on by default. When on, RTL text is Arabic-shaped (letters are
mapped to their joined presentation forms) and bidi-reordered into visual order
just before it is drawn, so it reads correctly on a terminal that has no bidi
support of its own — most terminals. The accelerator underline is dropped in
this mode (reshaping moves the marked letter), but the accelerator **key** still
works. If your terminal already does its own bidi (mlterm, a recent VTE-based
terminal, Konsole), turn **Reshape RTL text** off so the text isn't processed
twice. The setting has no effect for left-to-right languages.

### Confirmations (Options → Confirmations…)

Toggle which actions ask first: **delete** (on), **overwrite** (on), **execute /
open with default app** (off), **unmount** (on) and **exit** (on).

### Themes (Options → Edit themes…)

Rat Commander ships many themes — Dracula, Nord, Gruvbox, Solarized, Tokyo
Night, Catppuccin, One Dark and more — plus a classic Midnight Commander look,
Monochrome, Amber/Green CRT, and some playful ones. On a truecolor terminal the
bars and cursor render as animated gradients.

**Options → Edit themes…** opens a **visual theme editor**. It starts on the
theme in use; pick any UI element from the color list and set its color with the
RGB **color picker** (a 16-color swatch grid on non-truecolor terminals), while a
**live preview** on the right shows whichever surface that element affects — the
file panels, a demo dialog, or a small editor. **Save** writes the change
(applying it at once when you are editing the active theme), **Save as…** stores
it under a new name that then appears in the theme chooser, and **Cancel** / `Esc`
leaves — prompting to save, discard, or cancel if there are unsaved edits (as
does switching the picker to another theme). The full key list is under
[Theme editor](#theme-editor) above.

Themes are stored in **`themes.toml`**, generated with all the presets on first
run. Each `[[theme]]` holds an explicit `#rrggbb` color for **every UI element** —
`panel_bg`, `menu_bg`, `dialog_bg`, `dialog_border_fg` / `dialog_border_bg`,
`input_bg` / `input_fg`, `cursor_bg` / `cursor_fg`, `menu_selection_bg` /
`menu_selection_fg`, the per-type file colors (`dir_fg` for directories, `file_fg`
for regular files, plus `exec_fg` / `symlink_fg` / `archive_fg` / `doc_fg` /
`image_fg` / `media_fg` / `marked_fg`), the gradient endpoints, and so on. You can
also edit the file directly — open it with **F4** in a panel, and saving
live-reloads it. Delete the file to regenerate the presets. An older `themes.toml`
is upgraded in place on start: newly-added fields (such as `file_fg`) are filled
with sensible per-theme values, preserving each theme's appearance.

### The F2 user-menu format

The `menu` file uses the Midnight Commander format. A line starting in column 0
is a menu entry whose first character is its hotkey; the indented lines below it
are the shell commands to run. Lines starting with `#` are comments.

```
# a comment
= t d
3      Compress the current subdirectory (tar.gz)
        Pwd=`basename %d`
        cd .. && tar cf - "$Pwd" | gzip -f9 > "$Pwd.tar.gz"
```

**Condition lines** may precede an entry: `+ <cond>` shows the entry only when the
condition is true, `= <cond>` marks the default (highlighted) entry, and `=+` /
`+=` do both — evaluated against the panels when you press F2. Sub-conditions,
combined **left-to-right** (no precedence): `f` / `F <pat>` the current /
other-panel file matches a pattern, `d` / `D <pat>` the current / other directory,
`t` / `T <types>` the file type, `x <path>` an executable exists, `!` negates,
`&` / `|` combine. Type chars: `n` not-dir, `r` regular, `d` dir, `l` link,
`c` / `b` char / block device, `f` fifo, `s` socket, `x` executable, `t` tagged.
A first line `shell_patterns=0` switches `f` / `d` patterns from shell globs to
regular expressions. For example, `+ ! t t` shows an entry only when nothing is
tagged; `+ t t` only when something is.

**Macros** expand before the command runs: `%f` / `%p` the current file, `%d` the
current directory, `%s` the tagged-or-current files, `%t` the tagged files; the
uppercase `%F` / `%P` / `%D` / `%S` / `%T` are the same for the *other* panel;
`%u` is the tagged files (untagged afterwards); `%x` the extension; `%%` a literal
percent. Value macros are **shell-quoted** by default, so write them **unquoted** —
`cat %f`, not `cat "%f"`; `%0f` turns quoting off and `%1f` forces it.
`%{Prompt text}` pops up a dialog and inserts what you type; `%view{…}` is accepted
(the command then runs in the foreground shell). Menu commands run in a **suspended
foreground shell**, so their output is visible and interactive `read` prompts work.

A `menu` written for an older version that wrapped macros in quotes (`"%f"`) is
**migrated automatically** on first load — the quotes are dropped and a one-time
`menu.bak` backup of the original is kept beside it.

### The rc.ext file format

The `rc.ext` file maps file names to actions, in Midnight Commander's `mc.ext`
format. A line starting in column 0 is a **matcher**; the indented `Key=Value`
lines below it are the **actions** for files it matches:

```
# zip
regex/\.(zip|ZIP)$
    Open=%cd %p/uzip://
    View=%view{ascii} unzip -v %f

# ISO9660 CD image
shell/i/.iso
    Open=%cd %p/iso9660://
```

**Matchers** (first match wins): `regex/PATTERN` matches the file name with a
regular expression (`regex/i/…` case-insensitive); `shell/.ext` matches a name
suffix and `shell/name` an exact name (`shell/i/…` case-insensitive). Other
Midnight Commander matcher kinds (`type/…`, `directory/…`) are recognised and
skipped.

**Actions.** `Open` runs on **Enter**, `View` on **F3**, `Edit` on **F4**.
`Open=%cd <path>/<prefix>://` mounts the file with the extfs script `<prefix>`
(see *File associations and extfs*); any other `Open` / `View` / `Edit` value is
a shell command run in the file's directory. A `View` value prefixed with
`%view{ascii}` or `%view{hex}` pipes the command's output into the built-in
viewer instead. `Icon=` and unknown keys are ignored.

**Macros** are the same as the user menu — `%f` / `%p` the current file, `%d` its
directory, `%s` / `%t` the tagged files, `%%` a literal percent — plus `%x` for
the file's extension.

Delete the file to regenerate the default examples.