line-review

line-review is a persistent, Git-aware terminal application for reviewing files one line at a time. It highlights added code and configurable unprofessional language, lets you classify individual lines as Problem or Re-review, and exports the active findings as Markdown and JSON.

The reviewed files are never edited. The only writes inside a target directory are report files whose destination you explicitly approve.

Installation

line-review requires Python 3.12 or newer. Git must be on PATH to use the Git-aware scopes; ordinary directories can be reviewed without Git.

Install the published package with pip:

python -m pip install line-review
line-review C:\path\to\repository

Alternatively, run it in an isolated environment with uv:

uvx line-review C:\path\to\repository

The path is optional and defaults to the current directory. A terminal with mouse support and at least 100 columns is recommended.

Startup scopes

Every run begins with a scope dialog.

• This commit selects only files touched by HEAD compared with its first parent. It displays the latest working-tree copies of those files, but excludes unrelated dirty and untracked paths. A root commit is compared with an empty tree.
• Full file tree includes tracked and nonignored untracked text files. In an ordinary directory, it recursively scans text files while honoring .gitignore files and common cache/vendor exclusions.
• Since a commit accepts a SHA, tag, branch, or expression such as HEAD~3. The ref is resolved to a commit and compared from its merge-base with HEAD through the current working tree, including committed, staged, unstaged, and nonignored untracked changes.

When the selected path is a repository subdirectory, review paths and reports remain relative to that subtree while Git metadata comes from the enclosing repository. Non-Git directories offer only Full file tree.

Reviewing

The left sidebar contains four collapsible, independently scrolling lists:

1. Reviewed
2. Unreviewed
3. Problems, with a marked-line count per file
4. Re-review, with a marked-line count per file

The sidebar stays available in narrow terminals in a compact 22-column form; at under 96 columns the secondary toolbar buttons are hidden but remain available from their keyboard shortcuts, so Done or Reload file stays reachable.

Reviewed status is content-addressed. Mark done & next stores the exact current snapshot; if the file later changes, it automatically returns to Unreviewed. A file may be Done and still contain Problem or Re-review findings.

Clicking a source row repeatedly cycles its persistent state:

Unmarked -> Problem -> Re-review -> Unmarked

The third state removes the finding completely; no cleared audit entry is retained. Problem rows use a red ! marker and Re-review rows use a blue ? marker.

• Added and replacement lines since the file's previous Done snapshot have a pale green background.
• Built-in and workspace-added keywords have a yellow background. Automatic keyword matches are hints only and are not reported until their line is manually marked.
• New only retains three context lines around changed chunks and replaces larger unchanged ranges with clickable gap rows. Deletion-only hunks receive a compact non-markable banner.
• On the first Full file tree review there is no previous baseline, so green highlighting and New only are disabled until the file has been marked Done once.
• Markdown is shown as syntax-highlighted source so every visible row retains its original line identity.

If a file changes while open, marking and Done are disabled until it is reloaded. Identical lines are remapped across moves using surrounding context; a finding is removed when its marked source line has been edited or deleted.

Mouse and keyboard

The Textual footer also exposes active bindings as clickable controls.

Keywords

The packaged default list contains common profanity and unprofessional terms such as dumb and stupid. Matching is case-insensitive and respects whole word/phrase boundaries, so a short term does not highlight part of an identifier.

The Settings dialog accepts one addition or exclusion per line. These overrides are stored only for the current reviewed workspace; they do not create a repository configuration file.

History and reports

Review state lives in a per-user SQLite database selected by platformdirs—on Windows this is normally beneath %APPDATA%\line-review\line-review. The database stores:

• canonical workspace and keyword settings;
• resumable review sessions and their resolved Git scopes;
• one compressed Done baseline per reviewed file; and
• only currently active Problem/Re-review findings.

Each finding records its file/line/text fingerprint, content hash, timestamp, full HEAD SHA, every exact tag pointing at HEAD, branch/describe metadata, and whether the working tree was dirty. Non-Git reviews leave Git fields empty.

When all eligible files in the current scope are Done, the report dialog opens automatically. It defaults to current-scope findings and offers an all active workspace findings toggle. Export writes sibling .md and .json files from the chosen basename. Existing targets require confirmation. The pair is protected by a single-process export lock and rollback: both complete temporary files are prepared before replacement, and a failed replacement restores the prior pair. Reports written beneath the review root are remembered and excluded from later scans.

JSON includes schema_version: 1; both formats share a unique report ID, group findings into Problem and Re-review sections, and include review coverage, summary scope, Git scope, tag, dirty, reviewed, and skipped-file metadata. The report preview is revalidated when it is submitted, so a file that changes while the completion dialog is open returns to Unreviewed instead of completing stale work.

Binary files, submodules, inaccessible files, deleted paths, and symlinks escaping the selected root are skipped and do not block completion. Text files over 2 MiB or 50,000 lines remain reviewable but use plain-text rendering to keep navigation responsive. For an in-root symlink, Git historical comparison is disabled until the displayed target has its own Done snapshot, avoiding a comparison between link text and target contents.

Development

uv sync --extra dev
uv run ruff check src tests
uv run pytest

The tests create temporary Git repositories and use Textual's headless Pilot to verify mouse hit mapping, click cycling, syntax/keyword layers, collapsed hunks, sidebar counts, persistence, Done/next navigation, and report prompting/export.