diff --git a/README-LINUX.md b/README-LINUX.md index 6f4cd3a18..a838413b5 100644 --- a/README-LINUX.md +++ b/README-LINUX.md @@ -2,10 +2,14 @@ ## Launching -If installed by a system package or by compiling from source and installing into -`$HOME/.local` (with `zig build -p $HOME/.local -Doptimize=ReleaseFast`) several -configuration files will be installed which allow Ghostty to be launched from -most GUI application launchers (like Gnome Shell or KDE Plasma). +If properly installed, Ghostty will take advantage of D-Bus activation and +`systemd` user services to provide the best experience possible. + +If installed by a system package or by compiling from source and installing +into `$HOME/.local` (with `zig build -p $HOME/.local -Doptimize=ReleaseFast`) +several configuration files will be installed which allow Ghostty to be launched +from most GUI application launchers (like Gnome Shell or KDE Plasma) using D-Bus +activation and a `systemd` user service. These are the files that control the launching of Ghostty if installed as a user: @@ -25,14 +29,50 @@ $PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service $PREFiX/lib/systemd/user/com.mitchellh.ghostty.service ``` -Ghostty takes advantage of D-Bus activation and `systemd` user services to provide -the best experience possible. +If these files are not installed in the proper locations and configured +correctly Ghostty may fail to launch. + +## Checking Ghostty's Status + +The following command will show you Ghostty's status: + +```sh +systemctl status --user com.mitchellh.ghostty.service +``` + +Which should produce output similar to the following: + +``` +● com.mitchellh.ghostty.service - Ghostty + Loaded: loaded (/home/binky/.config/systemd/user/com.mitchellh.ghostty.service; enabled; preset: ignored) + Active: active (running) since Tue 2025-07-01 17:36:57 CDT; 1h 40min ago + Invocation: 75ed691baf914c5baae03beca7d32ff5 + Main PID: 2900191 (.ghostty-wrappe) + Tasks: 0 (limit: 76934) + Memory: 8M (peak: 9.5M) + CPU: 96ms + CGroup: /user.slice/user-1000.slice/user@1000.service/app.slice/com.mitchellh.ghostty.service + ‣ 2900191 /nix/store/bi6rbmzcpmbfd1zyaf8qihk9zggyr0i8-ghostty-1.1.4/bin/ghostty --launched-from=systemd + +Jul 01 17:36:57 pinky ghostty[2900191]: info(font_shared_grid_set): font bold: Adwaita Mono Bold +Jul 01 17:36:57 pinky ghostty[2900191]: info(font_shared_grid_set): font italic: Adwaita Mono Italic +Jul 01 17:36:57 pinky ghostty[2900191]: info(font_shared_grid_set): font bold_italic: Adwaita Mono Bold Italic +``` + +## How Launching Works With D-Bus Activation The application launcher, instead of executing Ghostty directly, will send a -signal to the D-Bus session broker asking it to open a Ghostty window. The -D-Bus session broker will check D-Bus to see if Ghostty is already running. If -Ghostty is already running, the broker will send a D-Bus signal to Ghostty to -create a new window. +signal to the D-Bus session broker asking it to open a Ghostty window. What +happens from there depends on if Ghostty is already running or not. The D-Bus +session broker knows if Ghostty is running or not because Ghostty will claim +a specific bus name on the session bus (`com.mitchellh.ghostty`). If there is +a program running that has claimed that bus name Ghostty will be assumed to +be running. + +### If Ghostty is Already Running + +If Ghostty is already running, the broker will send a D-Bus signal directy to +Ghostty asking it to create a new window. ```mermaid sequenceDiagram @@ -44,6 +84,8 @@ sequenceDiagram Ghostty->>D-Bus: OK ``` +### If Ghostty is Not Running + If Ghostty is not running, the D-Bus session broker will ask `systemd` to start Ghostty in a user service, and then will send Ghostty a D-Bus signal to create a new window. @@ -66,6 +108,8 @@ sequenceDiagram This ensures that any startup delay caused by GTK (or any other initialization) is only incurred once per login. +## Starting Ghostty at Login + The Ghostty `systemd` user service can be configured to start up as soon as you log in by running this command: @@ -73,7 +117,8 @@ log in by running this command: systemctl enable --user com.mitchell.ghostty.service ``` -By doing so, any startup delay will be "hidden" by the time that your system +This will configure your system to start Ghostty, but not create any windows, +when you log in. Any startup delay will be "hidden" by the time that your system needs to finish setting up everything after logging in. ## Stopping Ghostty @@ -99,7 +144,7 @@ this command: journalctl -a -f --user -u com.mitchellh.ghostty.service ``` -## Creating New Windows +## Creating New Windows "Manually" With D-Bus activation and `systemd` user services in use, simply launching `ghostty` from the CLI (or through a global keybind) will not create a new @@ -113,10 +158,18 @@ gdbus call --session --dest com.mitchellh.ghostty --object-path /com/mitchellh/g This command will create a new Ghostty window even if Ghostty is not already running as D-Bus activation will cause Ghostty to be launched. +### Tiling Window Managers + +The above `gdbus` command is useful for tiling window managers like i3, +Hyprland, or River. Simply bind the `gdbus` command to a key to create new +Ghostty windows, even if Ghostty is not already running. This can partially +serve as an alternative to Ghostty's global keybinds for unsupported window +managers (at least for creating a new window). + ## Reloading the Config -In addition to other methods, sending the `USR2` signal to the Ghostty process -will trigger a configuration reload. +In addition to other built-in methods like the keybind action, sending the +`USR2` signal to the Ghostty process will trigger a configuration reload. ## Debug Installations @@ -129,8 +182,8 @@ journalctl -a -f --user -u com.mitchellh.ghostty-debug.service gdbus call --session --dest com.mitchellh.ghostty-debug --object-path /com/mitchellh/ghostty_debug --method org.gtk.Actions.Activate new-window [] [] ``` -These are the files that control the launching of Ghostty if installed as -a user: +These are the files that control the launching of debug versions of Ghostty if +installed as a user: ``` $PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop