Config docs don't match the load order in the code (config vs config.ghostty, and config-file)

[meop]

Issue Description

Two places where https://ghostty.org/docs/config doesn't match src/config/Config.zig (1.3.1, same on main):

1. Legacy config and config.ghostty: the docs list config.ghostty first and say files load "in the order above with conflicting values in later files overriding earlier ones", so config would win. loadDefaultFiles loads config first and config.ghostty second, so config.ghostty wins.

2. config-file includes: the docs say they "are processed at the end of the current file", and that the macOS app support files load after the XDG ones. Config.load loads every default file (XDG, then app support), then CLI args, and only then all includes (loadRecursiveFiles). So an include from the XDG file overrides the app support file, and CLI flags too.

Either the docs or the code should change; I'm not sure which is intended.

(I used Claude Code to read the source and run the checks.)

Expected Behavior

As the docs describe: with both files present, config overrides config.ghostty; and on macOS, ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty overrides the XDG file, including what the XDG file pulls in with config-file. And CLI flags override config files.

Actual Behavior

config.ghostty overrides config, and a file included with config-file from the XDG config overrides the app support config and CLI flags.

Reproduction Steps

1. Linux or macOS: put font-size = 11 in $XDG_CONFIG_HOME/ghostty/config and font-size = 22 in $XDG_CONFIG_HOME/ghostty/config.ghostty. ghostty +show-config prints font-size = 22.

2. macOS: put config-file = extra in ~/.config/ghostty/config.ghostty, font-size = 14 in ~/.config/ghostty/extra, and font-size = 12 in ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty. ghostty +show-config prints font-size = 14.

3. Linux: put config-file = extra in $XDG_CONFIG_HOME/ghostty/config.ghostty and font-size = 8 in $XDG_CONFIG_HOME/ghostty/extra, then run ghostty --gtk-single-instance=false --font-size=30 (so it doesn't reuse a running instance). The window opens at size 8. With extra at 30 and --font-size=8, it opens at 30.

Ghostty Logs

No response

Ghostty Version

Ghostty 1.3.1

Version
  - version: 1.3.1
  - channel: stable
Build Config
  - Zig version   : 0.15.2
  - build mode    : .ReleaseFast
  - app runtime   : .none
  - font engine   : .coretext
  - renderer      : renderer.generic.Renderer(renderer.Metal)
  - libxev        : kqueue

OS Version Information

macOS 27.0.1 (26A434); steps 1 and 3 on Arch Linux, Ghostty 1.3.1-arch2

(Linux only) Display Server

Wayland

(Linux only) Desktop Environment/Window Manager

GNOME

Minimal Ghostty Configuration

# ~/.config/ghostty/config.ghostty
config-file = extra

# ~/.config/ghostty/extra
font-size = 14

# ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty
font-size = 12

Additional Relevant Configuration

No response

I acknowledge that:

• I have reviewed the FAQ and confirm that my issue is NOT among them.
• I have searched the Ghostty documentation and confirm there doesn't exist a configuration option that solves my issue.
• I have searched the Ghostty repository (both open and closed Discussions and Issues) and confirm this is not a duplicate of an existing issue or discussion.
• I have checked the "Preview" tab on all text fields to ensure that everything looks right, and have wrapped all configuration and code in code blocks with a group of three backticks (```) on separate lines.

[zisam-glitch]

Both observations are accurate—one is a documentation ordering mistake and the other is a genuine evaluation-order bug in src/config/Config.zig:

1. config vs config.ghostty (Documentation Bug, Code is Intended)

When config.ghostty was added so editors/LSPs could detect .ghostty filetypes by extension, config.ghostty was intended to take precedence over the legacy extensionless config file in the same directory. loadDefaultFiles loading config first and config.ghostty second is the intended behavior; the bullet order on ghostty.org/docs/config is inverted relative to loadDefaultFiles.

2. config-file Overriding Later Default Configs & CLI Flags (Code Bug in Config.load)

In src/config/Config.zig, Config.load currently executes:

1. loadDefaultFiles() (which appends config-file paths into the pending queue rather than resolving them inline at the end of each file)
2. loadCliArgs()
3. loadRecursiveFiles()

Because loadRecursiveFiles() runs after both loadDefaultFiles() and loadCliArgs(), any key set inside an included config-file overwrites both:

• Values from higher-precedence default files (such as ~/Library/Application Support/com.mitchellh.ghostty/config.ghostty on macOS when config-file was declared in ~/.config/ghostty/config.ghostty), and
• Explicit CLI flags (--font-size=...), unless --config-file itself was passed on the CLI.

To match the documented semantics ("processed at the end of the current file" and CLI flags taking highest precedence), loadRecursiveFiles should be drained immediately after each root config file in loadDefaultFiles (and once more after loadCliArgs only if CLI args themselves specify --config-file), before re-applying or preserving CLI flag overrides.

[meop]

The config-file comment in Config.zig says includes load after the entire configuration, so that part looks intended. I opened ghostty-org/website#500 to fix the docs.

One question left: --font-size=30 loses to a font-size in an included file. Is that intended?

[kova1max]

Yes, as the code is written today. Config.load documents its order as defaults, then the XDG config, then Application Support on macOS, then CLI flags, and only then "recursively defined configuration files". Every config-file, whether it came from a file or from --config-file on the CLI, is loaded in that last step. So a value from an include beats a CLI flag.

This is the same rule the config-file option describes: included files "do not take effect until after the entire configuration is loaded". CLI flags are part of that configuration, so they count as "before" too.

So the docs should say that includes load after everything, CLI flags included. Your website PR is the right place for that. If you think CLI flags should win over includes, that is a behaviour change, and it would need its own issue. It is not a mismatch between the code and its documented intent.

Source, if you want it: the doc comment on Config.load and the config-file option docs in src/config/Config.zig on main, checked against Ghostty 1.4.0.