Skip to content

README.md

Latest commit

 

History

History
286 lines (219 loc) · 9.78 KB

README.md

File metadata and controls

286 lines (219 loc) · 9.78 KB

Logo
Ghostty for Windows

Native Windows port of the Ghostty terminal emulator.
Status · Building · Shortcuts · Configuration · Upstream Docs

About

This is a fork of Ghostty that adds native Windows support via a Win32 application runtime. It runs as a standalone .exe — no WSL, no Cygwin, no compatibility layers.

The goal is to track the upstream main branch while maintaining a native Windows port that leverages Ghostty's cross-platform core (terminal emulation, renderer, font system).

Upstream Ghostty supports Linux (GTK) and macOS natively. This fork adds a win32 application runtime alongside those existing backends. See the upstream repository for the original project.

Status

Feature-complete — 100% apprt action coverage (65/65 actions handled). The terminal is ready for daily use.

Features

Terminal

  • Full VT sequence support with OpenGL 4.6 rendering (WGL)
  • FreeType + HarfBuzz fonts with DirectWrite system font discovery
  • ConPTY shell spawning (cmd.exe, PowerShell, WSL)
  • Win32 Input Mode (mode 9001) for full Unicode through ConPTY
  • IME support for CJK input (Japanese, Chinese, Korean)
  • Per-monitor DPI awareness, window resize with grid reflow
  • 463 built-in color themes (same as macOS)

Windows & Tabs

  • Multiple windows, tabbed interface with custom GDI tab bar
  • Tab drag-and-drop reorder, inline rename (double-click), right-click context menu
  • Close tab modes: current, all others, all to the right

Split Panes

  • Split right/down/left/up, navigate between panes
  • Mouse drag to resize dividers, double-click to equalize
  • Toggle split zoom, equalize all splits
  • Independent split tree per tab

Extras

  • Command palette with filterable actions and keybinding hints
  • Quick terminal (slide-in/out from screen edge with global hotkey)
  • Find-in-terminal search bar
  • URL detection with Ctrl+click to open in browser
  • Desktop notifications (OSC 9, OSC 777)
  • Background opacity, fullscreen, window decorations toggle
  • Font size zoom with inheritance to new tabs/splits
  • Config hot-reload, scrollbar
  • DWM dark/light chrome and Win11 22H2+ caption color matching the configured background
  • Shell integration for PowerShell (prompt marking, CWD, title)
  • Drag a file from Explorer onto the terminal to paste its path
  • Visual bell (taskbar flash) when BEL fires on an unfocused window
  • Taskbar flash when a command exits non-zero in an unfocused window
  • Confirm-close dialog when a programmatic close hits a tab with a running command
  • Auto-update check against GitHub releases (rate-limited to once per hour); clicking the "Update available" balloon opens the releases page in your browser
  • Horizontal scroll wheels / trackpad gestures (WM_MOUSEHWHEEL)

Platform-Specific Notes

  • Inspector (debug overlay) — acknowledged but no Win32 UI yet
  • undo/redo — macOS NSUndoManager only, no Win32 equivalent
  • secure_input — macOS EnableSecureEventInput only
  • Release build + installer (MSI/MSIX) — not yet packaged

Building

Requires Zig 0.15.2 or newer.

Cross-compile from Linux/WSL2

zig build -Dapp-runtime=win32 -Dtarget=x86_64-windows

The executable is at zig-out/bin/ghostty.exe. Copy it to a Windows path and run it.

Release build

zig build -Dapp-runtime=win32 -Dtarget=x86_64-windows -Doptimize=ReleaseFast

To debug a release build with stderr visible, add -Dwindows-console=true — it links against /SUBSYSTEM:CONSOLE instead of the default Windows GUI subsystem so the process gets a console attached.

Keyboard Shortcuts

All keybindings are configurable via the keybind config option. These are the defaults:

General

Action Shortcut
New window Ctrl+Shift+N
Close surface (tab/pane) Ctrl+Shift+W
Close window Ctrl+Shift+Q
Toggle fullscreen Ctrl+Enter
Command palette Ctrl+Shift+P
Open config file Ctrl+,
Reload config Ctrl+Shift+,
Quit Ctrl+Shift+Q

Tabs

Action Shortcut
New tab Ctrl+Shift+T
Next tab Ctrl+Page Down
Previous tab Ctrl+Page Up
Go to tab 1–8 Ctrl+1 – Ctrl+8
Go to last tab Ctrl+9
Move tab left Ctrl+Shift+Page Up
Move tab right Ctrl+Shift+Page Down
Drag reorder Mouse drag on tab
Rename tab Double-click tab
Tab context menu Right-click tab

Split Panes

Action Shortcut
Split right Ctrl+Shift+O
Split down Ctrl+Shift+E
Focus next pane Ctrl+Shift+]
Focus previous pane Ctrl+Shift+[
Equalize splits Configurable (equalize_splits)
Toggle split zoom Configurable (toggle_split_zoom)
Resize split Mouse drag on divider
Equalize split Double-click divider

Text & Clipboard

Action Shortcut
Copy Ctrl+Shift+C
Paste Ctrl+Shift+V
Select all Ctrl+Shift+A
Find Ctrl+Shift+F
Find next Enter (in search bar)
Find previous Shift+Enter (in search bar)
Close search Escape

Font Size

Action Shortcut
Increase font size Ctrl+=
Decrease font size Ctrl+-
Reset font size Ctrl+0

Mouse

Action Gesture
Vertical scroll Mouse wheel
Horizontal scroll Trackpad swipe / horizontal wheel
Drag-select Left-click drag
Open URL Ctrl+Click on a detected URL
Middle-click paste Middle button (configurable via middle-click-action)
Drop file Drag a file from Explorer onto the terminal — its path is pasted

Quick Terminal

The quick terminal requires a keybinding in your config:

keybind = global:ctrl+grave_accent=toggle_quick_terminal

The global: prefix makes it work system-wide, even when Ghostty isn't focused.

Configuration

Ghostty reads its config file from %LOCALAPPDATA%\ghostty\config (or %XDG_CONFIG_HOME%\ghostty\config if set). Example:

# Font
font-family = JetBrains Mono
font-size = 14

# Colors
background = #1e1e2e
foreground = #cdd6f4

# Shell
command = powershell.exe

# Behavior
quit-after-last-window-closed = true

# Quick terminal (global hotkey)
keybind = global:ctrl+grave_accent=toggle_quick_terminal

See the upstream documentation for the full list of config options. Most settings work on Windows — the exceptions are platform-specific options (GTK, macOS).

Architecture

The Windows port adds a win32 application runtime (src/apprt/win32/) alongside the existing GTK (Linux) and AppKit (macOS) runtimes. It reuses Ghostty's cross-platform core:

  • Terminal emulation: Shared VT parser, screen, scrollback (src/terminal/)
  • Rendering: OpenGL 4.3+ with WGL context management (src/renderer/)
  • Fonts: FreeType rasterization + HarfBuzz shaping + DirectWrite discovery (src/font/)
  • PTY: Windows ConPTY via CreatePseudoConsole (src/pty.zig)
  • I/O: libxev with IOCP backend (src/termio/)

Key files

src/apprt/win32/
  App.zig             — Win32 message loop, window classes, action dispatch
  Window.zig          — Top-level container HWND, tab bar, splits, tab lifecycle
  Surface.zig         — WS_CHILD HWND, WGL context, input, clipboard, search, command palette
  QuickTerminal.zig   — Quick terminal popup with slide animation
  win32.zig           — Win32 API type definitions and extern declarations

src/shell-integration/powershell/
  ghostty-shell-integration.ps1  — PowerShell prompt marking, CWD, title

Testing

A test harness runs from WSL2 using PowerShell automation:

bash test/win32/ghostty_test.sh all

25+ automated tests cover: launch/close, window properties, keyboard input, multiple windows, clipboard, config loading, scrollbar, close confirmation, URL detection, notifications, window sizing, window resize (real assertion), search bar, config reload, tabs (new/switch/close), opacity, command palette, tab drag reorder, inline tab rename, split panes, font zoom, fullscreen toggle, open config, and quick terminal.

Tab and split tests run in PowerShell sessions:

powershell.exe -ExecutionPolicy Bypass -File test/win32/test_tabs.ps1 -ExePath path\to\ghostty.exe
powershell.exe -ExecutionPolicy Bypass -File test/win32/test_splits.ps1 -ExePath path\to\ghostty.exe

Syncing with Upstream

This fork tracks ghostty-org/ghostty main branch. To sync:

git remote add upstream https://github.com/ghostty-org/ghostty.git
git fetch upstream
git merge upstream/main

git rerere is enabled in the local repo so previously-resolved conflict resolutions get re-applied automatically on subsequent merges.

When resolving conflicts, default to keep upstream for any file outside src/apprt/win32/, dist/windows/, or test/win32/. The .win32 switch arms (.none, .win32 => void and similar) need to be preserved in upstream switches that handle apprt variants.

Files most likely to conflict on upstream merges:

  • src/Surface.zig, src/config/Config.zig, src/font/discovery.zig, src/font/DeferredFace.zig, src/font/backend.zig
  • Switch-arm files: src/apprt/runtime.zig, src/apprt.zig, src/datastruct/split_tree.zig, src/input/Binding.zig, src/font/face.zig, src/terminal/mouse.zig

License

Same as upstream Ghostty — see LICENSE.