Applied-Software/ghostty
5
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2025-08-01 14:27:31 +03:00
Code Issues Packages Projects Releases Wiki Activity

linux: expand and clarify documentation

Browse Source
This commit is contained in:
Jeffrey C. Ollie
2025-07-01 19:42:56 -05:00
parent 1f03b7c82c
commit d72751cdbb
1 changed files with 69 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
README-LINUX.md
View File

@ -2,10 +2,14 @@
## Launching ## Launching
If installed by a system package or by compiling from source and installing into If properly installed, Ghostty will take advantage of D-Bus activation and
`$HOME/.local` (with `zig build -p $HOME/.local -Doptimize=ReleaseFast`) several `systemd` user services to provide the best experience possible.
configuration files will be installed which allow Ghostty to be launched from
most GUI application launchers (like Gnome Shell or KDE Plasma). 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 These are the files that control the launching of Ghostty if installed as
a user: a user:
@ -25,14 +29,50 @@ $PREFIX/share/dbus-1/services/com.mitchellh.ghostty.service
$PREFiX/lib/systemd/user/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 If these files are not installed in the proper locations and configured
the best experience possible. 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 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 signal to the D-Bus session broker asking it to open a Ghostty window. What
D-Bus session broker will check D-Bus to see if Ghostty is already running. If happens from there depends on if Ghostty is already running or not. The D-Bus
Ghostty is already running, the broker will send a D-Bus signal to Ghostty to session broker knows if Ghostty is running or not because Ghostty will claim
create a new window. 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 ```mermaid
sequenceDiagram sequenceDiagram
@ -44,6 +84,8 @@ sequenceDiagram
Ghostty->>D-Bus: OK Ghostty->>D-Bus: OK
``` ```
### If Ghostty is Not Running
If Ghostty is not running, the D-Bus session broker will ask `systemd` to start 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 Ghostty in a user service, and then will send Ghostty a D-Bus signal to create a
new window. new window.
@ -66,6 +108,8 @@ sequenceDiagram
This ensures that any startup delay caused by GTK (or any other initialization) is This ensures that any startup delay caused by GTK (or any other initialization) is
only incurred once per login. only incurred once per login.
## Starting Ghostty at Login
The Ghostty `systemd` user service can be configured to start up as soon as you The Ghostty `systemd` user service can be configured to start up as soon as you
log in by running this command: log in by running this command:
@ -73,7 +117,8 @@ log in by running this command:
systemctl enable --user com.mitchell.ghostty.service 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. needs to finish setting up everything after logging in.
## Stopping Ghostty ## Stopping Ghostty
@ -99,7 +144,7 @@ this command:
journalctl -a -f --user -u com.mitchellh.ghostty.service 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 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 `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 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. 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 ## Reloading the Config
In addition to other methods, sending the `USR2` signal to the Ghostty process In addition to other built-in methods like the keybind action, sending the
will trigger a configuration reload. `USR2` signal to the Ghostty process will trigger a configuration reload.
## Debug Installations ## 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 [] [] 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 These are the files that control the launching of debug versions of Ghostty if
a user: installed as a user:
``` ```
$PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop $PREFIX/share/applications/com.mitchellh.ghostty-debug.desktop