Upstream reference checkouts¶
The ignored upstream/ directory holds local checkouts used for building,
research, and behavioral comparison. These repositories are not vendored into
Revenant, and their presence is not required for a stub build.
tools/fetch-libghostty pins an exact Ghostty development commit and leaves the
checkout detached at that revision. Use tools/fetch-libghostty --print-reference
to read the configured pin. A local checkout may have been advanced independently;
inspect the actual build inputs and binary provenance rather than assuming the
checkout and configured pin agree.
The maintainer selects dependency revisions. The coordinated Unicode 18 migration adopted
27e8b3fa85d9cf8c7cd5ae2ced348bcb0a4fba9c; see the
provenance and behavior record. When Ghostty 1.4.0 is released,
review the intervening changes and pin its exact release commit. Do not replace
the fetcher's full-hash contract with a moving branch or repeat the Unicode
migration unless the release introduces a relevant data delta. The other checkouts are also working references:
record compatibility decisions in the
xterm differences ledger or roadmap.
Checkouts¶
| Directory | Repository | Role in Revenant |
|---|---|---|
upstream/ghostty |
https://github.com/ghostty-org/ghostty | Source of the selected libghostty-vt build. It owns VT parsing, terminal state, reflow, key and mouse encoding, history, selection primitives, and other terminal-core facilities. tools/fetch-libghostty selects an exact development commit. Adopt the exact Ghostty 1.4.0 release commit after a maintainer review when it is available. |
upstream/ghostling |
https://github.com/ghostty-org/ghostling | Minimal C consumer of libghostty-vt and the functional-baseline reference for Revenant. Its integrations show which terminal capabilities can already be exposed by a thin host application. It is a reference, not a linked dependency. |
upstream/xterm-snapshots |
https://github.com/ThomasDickey/xterm-snapshots | The xterm source-code behavioral oracle is the exact xterm-411 tag. The working checkout may be ahead; inspect the pinned tag for baseline comparisons. Advance the oracle only as part of an intentional compatibility-baseline migration. |
upstream/xterm.dev |
https://github.com/xterm-x11/xterm.dev | Source for the xterm project website and published documentation. It is useful for release notes and public documentation, but is not the source-code behavioral oracle. |
The neighboring /home/toppk/workspace/xterm repository remains useful as a
historical patch-410 working reference. It no longer defines the compatibility
baseline; upstream/xterm-snapshots at xterm-411 is the current oracle used
for the checked-in resource, app-default, and action catalogs under compat/.
Review evidence policy¶
Before accepting a review finding, compatibility decision, or documentation
statement of the form “xterm does X,” check the claim against
upstream/xterm-snapshots at the pinned oracle revision. Record the relevant
source file and symbol (and line when useful) in the review or change rationale.
Memory, manual-page interpretation, and observations from a live xterm are
useful supporting evidence, but they do not replace checking the available
source. If source and observed behavior appear to disagree, record both as an
open discrepancy and investigate rather than promoting either recollection to
a finding.
Revision and update policy¶
- Do not edit a checkout under
upstream/as part of a Revenant change. - Do not commit generated Ghostty build output or an upstream checkout.
- Update the Ghostty reference in
tools/fetch-libghosttydeliberately, then compile and test both the stub and libghostty configurations. - When Ghostty changes its C API, keep
src/terminal.hbackend-neutral rather than leaking Ghostty handles into the Xt widget or application layer. - When Ghostling adds a user-visible terminal capability, review the parity matrix in the roadmap.
- When advancing the xterm oracle, update all four
compat/xterm-411-*artifacts (and rename them for the new patch), the xterm differences ledger, and documentation in one compatibility checkpoint.
Useful inspection commands:
git -C upstream/ghostty show -s --format='%H %cs %s' HEAD
git -C upstream/ghostling show -s --format='%H %cs %s' HEAD
git -C upstream/xterm-snapshots show -s --format='%H %cs %s' HEAD
git -C upstream/xterm.dev show -s --format='%H %cs %s' HEAD