A keyboard-driven terminal interface for Perforce, inspired by gitui. It brings a familiar tab bar, two status lists, a colored diff pane, contextual commands, and keyboard navigation to Perforce workspaces.
Status: early release. The core workflows have real p4/p4d integration tests, including conflicting edits and stream integration. This is a new application, not a claim of gitui's maturity or complete feature parity. See feature mapping and remaining gaps and validation.
Requirements: Rust 1.88 or newer, the Perforce p4 client supporting tagged JSON (-ztag -Mj), and an existing workspace. Development is tested locally with P4/P4D 2026.1 on macOS ARM64. A daemon is only needed to run the server integration tests; it is not bundled or started during normal use.
cargo install --path . --locked
cd /path/to/your/perforce/workspace
p4 login # if required by your server
p4uiOr run directly:
cargo run --release -- -d /path/to/workspace
p4ui -p ssl:perforce.example.com:1666 -u alice -c alice-workspace
p4ui --check # connection/workspace diagnostics
p4ui --status # machine-readable workspace status, no TTY needed
p4ui --log # one history page as JSON; no workspace scan
p4ui --tab log # open directly in Log without loading Status
p4ui --max-p4-processes 2 # cap concurrent p4 commands; default is 4
p4ui --helpSet P4PORT to connect without a port flag:
export P4PORT=ssl:perforce.example.com:1666
p4ui -u alice -c alice-workspace
# Or just for this invocation:
P4PORT=perforce.example.com:1666 p4ui --checkAn explicit --port / -p overrides the server address. Without that flag, p4ui delegates connection settings to the native p4 client: P4CONFIG settings override environment variables such as P4PORT. For example, with P4CONFIG=.perforce, a checkout's .perforce can select a different server than the shell's exported P4PORT. The client searches the launch directory and its parents, taking each setting from the nearest config file that defines it. P4PORT still supplies the server when the config files do not set one. See Perforce configuration precedence.
Other settings such as P4USER, P4CLIENT, P4CHARSET, P4ENVIRO, trust, ignore rules, and login tickets also use normal p4 resolution. Explicit connection flags override their corresponding settings. Authentication/SSO, trust enrollment, server administration, and workspace creation remain in the p4 CLI. No passwords are accepted on p4ui's command line or stored in its configuration.
--max-p4-processes N limits concurrent P4 commands per p4ui instance. The default is 4; use 1 for serial requests or 2 to reduce concurrency. Independent read-only requests run in parallel, including Status queries and the initial history/connection lookup. Mutations remain serialized, and older history pages follow their cursor order.
Run from the workspace root to operate on the whole workspace. Status, history, Files, and bulk sync/reconcile/merge/copy use the current directory and its descendants. Submit and shelve operate on the entire changelist, including files outside that directory. Enter on a pending changelist shows its complete file list across the workspace. Selected-file actions apply to that file, even outside the current directory.
Selecting a workspace keeps the current server, user, and character set for the session. A P4CONFIG file in the selected workspace cannot redirect that connection. To connect to a different server or user, start another p4ui instance with the desired settings.
See Building on macOS and Linux for Apple Silicon/Intel Mac instructions, distro build prerequisites, and .deb, .rpm, and Arch package recipes. Branch builds upload downloadable artifacts to GitHub Actions. Pushing an ordinary stable vX.Y.Z tag automatically publishes all packages under Releases after the package and full CI checks pass. Command-managed tags prepare drafts for final verification. See Releasing for version updates and existing-tag releases. These are upstream packages; availability in official distro repositories is tracked separately.
Maintainers can prepare and publish a new stable version with one command:
./scripts/release.py 0.4.1Run from a clean, synchronized default branch after pushing source changes. The command updates version metadata and release notes, runs local and GitHub checks, verifies package checksums, and publishes only after all checks pass. See Releasing for prerequisites, --check, and --resume.
- In Status, select an offline/untracked file and press
Spaceorato reconcile it.Areconciles all files in scope after confirmation.p4 ignorerules are honored through the client's usual configuration. - For tracked files, use Files, press
eto open for edit, oroto open for edit and launch your editor. Editor selection isP4EDITOR,VISUAL,EDITOR, thenvi(notepadon Windows). Commands with quoted arguments are supported; shell pipelines/expansion are not evaluated. - In Changes, press
nto create a numbered changelist. Select it and pressSpaceto make it the target for subsequent file actions. In Status,mmoves an opened file to a chosen changelist. - Press
cto submit. The default changelist asks for a description; numbered changelists use their saved description (Eedits it). Multiline inputs use Enter for a newline and Ctrl-S to accept. All submissions require explicityconfirmation. - Use Log to inspect submitted change summaries. Enter drills into the first 200 affected files; select a file for its revision-specific diff.
Escreturns. Shelves and pending changes support the same drilldown. sin Changes shelves a numbered changelist. Shelving keeps the files open; revert separately when ready.uin Shelves unshelves into a chosen pending change. Existing shelf content is never force-overwritten.fsyncs to depot HEAD after confirmation. Resolve lists unresolved files;Rchooses safe automatic resolve, merge, yours, or theirs. Conflicts left by auto resolve require your merge tool andp4 resolve.
Nonfatal workspace scan warnings appear in the status bar; press ? to read their full messages. Usable files remain available, and warnings identify potentially incomplete results. Authentication errors and failed commands still stop the request.
The UI draws after input, resize, or background results, and formats only visible rows and diff lines. Rapid tab selections coalesce before starting a load. Status and Resolve reload workspace data on return; other tab listings and read-only depot/spec previews can reuse results for up to 10 seconds. Read caches have a 2 MiB listing budget and a 1 MiB preview budget. r / F5 bypasses the caches, and mutations, workspace changes, and editor handoffs invalidate them. Mutations check the current workspace identity again before running.
The result of a failed submit can be a newly numbered pending changelist. Refresh and inspect Changes before retrying. Timeouts and interrupted network operations also require inspection; server changes are not assumed to be rolled back.
? / F1 opens full help, including the keys for the current workflows. Arrow keys and j/k navigate; left/right or 1–9 switch tabs; Tab focuses the diff pane. PageUp/PageDown and Home/End scroll. / filters loaded rows, scrolling near the bottom loads an older page in Log/Shelves (+ also loads a page; it increases the result limit in other tabs), r / F5 refreshes, and q exits. Read-only background requests are cancelled on exit; p4ui waits for active mutations before allowing a normal exit.
On Status, press t to jump directly between Opened and Offline / untracked, selecting the first matching file in the destination pane. This works from the diff pane too and respects the active filter; an empty destination keeps the selection and shows a message. You can also use Down/j past the last Opened file or Up/k across the boundary. Tab toggles focus between the file lists and diff. End selects the last file. Returning to Status restores its selected file, filter and pane scroll positions after refreshing; workspace changes reset them.
File badges show Perforce actions: A is add/branch/move destination, M is edit/modify (and the fallback for other actions), and D is delete/move source. For unopened files, Files shows the last submitted revision's action, so these badges can describe depot history. Status shows pending workspace changes.
Press C on any tab to edit the current workspace's client specification in your configured editor (P4EDITOR, VISUAL, EDITOR, then vi/notepad). Save and exit the editor, then press y to save the specification to Perforce, or n/Esc to discard it. An unchanged form is not saved. The Client: name must stay unchanged. Editing the spec does not sync files or change p4ui's working directory. If the editor or save fails, the error shows a recovery draft path.
| Tab | Commands |
|---|---|
| Status | t jump between Opened and Offline / untracked; a / Space reconcile or reopen to target; A reconcile all; o editor; m move to changelist; u metadata revert, keep content; U discard/revert |
| Log | Enter browse files; b annotate revision; h file/integration history |
| Changes | n new; Space target; Enter files; E edit description; s shelve; c submit; D delete empty change |
| Shelves | Enter files; u unshelve; D delete shelf |
| Files | e open for edit; o editor; b annotate; h history; v inspect revision; D open for delete; M move; L lock / l unlock |
| Streams | o / Space switch; n create; D delete spec; g merge from selected; p copy from selected |
| Resolve | R resolve (-am, -as, -ay, -at) |
| Workspaces | o / Space select local workspace for this session; C edit current client spec (available on every tab) |
| Labels | Inspect label specifications and filter the list |
U, delete, sync, submit, unshelve, integration, and switching require confirmation. Enter never accepts a destructive confirmation: press y explicitly.
Stream commands require a stream workspace and follow server flow/permission rules. Creation makes a development child of the current stream, or a mainline when no current stream is set; a stream depot must already exist. Creating the specification does not populate files. Switch to it, select the parent, merge (g) to populate a development stream, resolve, inspect, and submit. Copy (p) promotes development to its parent after incoming changes have been merged. Stream deletion removes the specification, not submitted history. Stream paths cannot be renamed as though they were Git branch references.
The default path is $XDG_CONFIG_HOME/p4ui/config.toml or ~/.config/p4ui/config.toml; on Windows, %APPDATA%/p4ui/config.toml. Use --config path to override. Missing default configuration is fine; unknown fields, unsupported themes, and conflicting key bindings are errors.
refresh_seconds = 10 # 0 disables automatic refresh; Log/Shelves refresh manually
command_timeout_seconds = 120 # 1..3600, including submits and large syncs
max_output_mb = 16 # 1..256 per command/preview
page_size = 200 # non-history tabs: 10..10000; + raises it
history_page_size = 100 # 1..200 maximum batch; interactive batches use visible rows
history_max_scan_rows = 0 # inherit server limits; 1..1000000 requests a stricter cap
theme = "dark" # dark, light, mono
[keys]
quit = "Q"
# Single characters; arrow/navigation keys remain available.Configurable action names: quit, refresh, help, search, up, down, open, reconcile, submit, sync, new_change, revert, edit, shelve, unshelve, delete, move_change, annotate, filelog, resolve, rename, lock, revision, edit_change, edit_client, status_pane. Fixed keys are Space, A, g, p, l, +, digits and terminal navigation keys. Swapping two bindings requires configuring both.
Log and Shelves initially request enough actual changes to fill the visible list, up to history_page_size per request. Moving down near the bottom (arrow keys, PageDown, or mouse wheel) fetches the next page in the background. + also loads an older page. Resizing a larger terminal fills its additional rows. Pages append to the cache, preserving selection; older pages use the changelist immediately before the oldest returned change as their upper bound. Gaps in changelist numbers do not reduce the number of changes requested.
Log pages use p4 changes -L -m N -s submitted ..., with an upper revision bound for older pages. There are no file-head scans, global-counter walks, or repeated queries for already cached Log pages. Perforce ignores revision bounds on file-scoped shelf listings, so Shelves use -s shelved, refetch a bounded prefix (at most 10,000 rows), and filter with an ID cursor to handle shelf insertions/deletions. Connection information is reused within a browsing session. Switching tabs cancels an outstanding background read; active mutations continue to completion. Log and Shelves never poll while idle. r refreshes from the newest changes. Filters search the cached rows only; at most 10,000 changes are cached.
By default, p4ui inherits the server's resource limits, just like the P4 CLI. history_max_scan_rows = 0 does not override them. A positive value requests an optional stricter scan cap, clamped to reported group limits; if group metadata cannot be read completely, p4ui leaves the server limits unchanged and warns. Such overrides can be ignored by a server configured with server.commandlimits=2. -m N limits returned changes, not necessarily scanned database rows, so a large scope can still exceed an admin limit. See Perforce's query limit documentation.
On a failed request, automatic paging pauses and existing rows/cursors are retained. There is no automatic retry or silent skipping of changes. Narrow the launch directory if the server limit was reached; r refreshes or + explicitly retries an older page. Automatic change previews omit diffs and show at most 200 files. Enter opens per-file diffs.
If you copied an older configuration example with history_max_scan_rows = 50000, set it to 0 to use normal server limits. The old history_change_window configuration key remains accepted for compatibility and no longer affects paging.
For read-only diagnostics, p4ui --log emits one result-count-limited page as JSON, including history.next, optional scan limits and warnings. p4ui --log --before-change 12345 starts at an inclusive upper changelist bound.
cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo test --locked --test perforce -- --ignored
cargo build --locked
python3 tests/ui_smoke.py
python3 tests/history_ui.pyIntegration fixtures use isolated temporary servers via the local rsh: transport. They do not connect to your server or listen on a network port. Their security overrides apply only to their temporary databases, which are deleted after each test. Python 3 is needed for process-boundary tests and the Unix PTY smoke test. See CONTRIBUTING.md.
MIT. The interface and workflow are inspired by gitui; this implementation is original Rust code using Ratatui and Crossterm, rather than a fork of gitui's Git backend. Perforce, P4, and gitui belong to their respective owners. This is an independent project.