From 2accb8fe22c649910d5915ff6e8f201399b8dbfc Mon Sep 17 00:00:00 2001 From: Anund Date: Sat, 4 Jan 2025 01:06:59 +1100 Subject: [PATCH 1/2] docs: add autogenerated cli actions docs --- .../workflows/warn-autogenerated-files.yaml | 1 + docs/features/commands.mdx | 228 ++++++++++++++++++ docs/nav.json | 5 + 3 files changed, 234 insertions(+) create mode 100644 docs/features/commands.mdx diff --git a/.github/workflows/warn-autogenerated-files.yaml b/.github/workflows/warn-autogenerated-files.yaml index b1bd302e..9c2198b7 100644 --- a/.github/workflows/warn-autogenerated-files.yaml +++ b/.github/workflows/warn-autogenerated-files.yaml @@ -7,6 +7,7 @@ on: paths: - docs/config/reference.mdx - docs/config/keybind/reference.mdx + - docs/features/commands.mdx name: Autogenerated files check diff --git a/docs/features/commands.mdx b/docs/features/commands.mdx new file mode 100644 index 00000000..19587188 --- /dev/null +++ b/docs/features/commands.mdx @@ -0,0 +1,228 @@ +--- +title: Reference +description: Reference of all Ghostty action subcommands. +editOnGithubLink: https://github.com/ghostty-org/ghostty/tree/main/src/cli +--- +Ghostty includes a number of utility actions that can be accessed as subcommands. +Actions provide utilities to work with config, list keybinds, list fonts, demo themes, +and debug. +## version +The `version` command is used to display information about Ghostty. Recognized as +either `+version` or `--version`. + +``` +ghostty --version +``` + +## help +The `help` command shows general help about Ghostty. Recognized as either +`-h, `--help`, or like other actions `+help`. + +You can also specify `--help` or `-h` along with any action such as +`+list-themes` to see help for a specific action. + +``` +ghostty --help +``` + +## list-fonts +The `list-fonts` command is used to list all the available fonts for +Ghostty. This uses the exact same font discovery mechanism Ghostty uses to +find fonts to use. + +When executed with no arguments, this will list all available fonts, sorted +by family name, then font name. If a family name is given with `--family`, +the sorting will be disabled and the results instead will be shown in the +same priority order Ghostty would use to pick a font. + +Flags: + + * `--bold`: Filter results to specific bold styles. It is not guaranteed + that only those styles are returned. They are only prioritized. + + * `--italic`: Filter results to specific italic styles. It is not guaranteed + that only those styles are returned. They are only prioritized. + + * `--style`: Filter results based on the style string advertised by a font. + It is not guaranteed that only those styles are returned. They are only + prioritized. + + * `--family`: Filter results to a specific font family. The family handling + is identical to the `font-family` set of Ghostty configuration values, so + this can be used to debug why your desired font may not be loading. + +``` +ghostty +list-fonts +``` + +## list-keybinds +The `list-keybinds` command is used to list all the available keybinds for +Ghostty. + +When executed without any arguments this will list the current keybinds +loaded by the config file. If no config file is found or there aren't any +changes to the keybinds it will print out the default ones configured for +Ghostty + +Flags: + + * `--default`: will print out all the default keybinds + + * `--docs`: currently does nothing, intended to print out documentation + about the action associated with the keybinds + + * `--plain`: will disable formatting and make the output more + friendly for Unix tooling. This is default when not printing to a tty. + +``` +ghostty +list-keybinds +``` + +## list-themes +The `list-themes` command is used to preview or list all the available +themes for Ghostty. + +If this command is run from a TTY, a TUI preview of the themes will be +shown. While in the preview, `F1` will bring up a help screen and `ESC` will +exit the preview. Other keys that can be used to navigate the preview are +listed in the help screen. + +If this command is not run from a TTY, or the output is piped to another +command, a plain list of theme names will be printed to the screen. A plain +list can be forced using the `--plain` CLI flag. + +Two different directories will be searched for themes. + +The first directory is the `themes` subdirectory of your Ghostty +configuration directory. This is `$XDG_CONFIG_DIR/ghostty/themes` or +`~/.config/ghostty/themes`. + +The second directory is the `themes` subdirectory of the Ghostty resources +directory. Ghostty ships with a multitude of themes that will be installed +into this directory. On macOS, this directory is the +`Ghostty.app/Contents/Resources/ghostty/themes`. On Linux, this directory +is the `share/ghostty/themes` (wherever you installed the Ghostty "share" +directory). If you're running Ghostty from the source, this is the +`zig-out/share/ghostty/themes` directory. + +You can also set the `GHOSTTY_RESOURCES_DIR` environment variable to point +to the resources directory. + +Flags: + + * `--path`: Show the full path to the theme. + + * `--plain`: Force a plain listing of themes. + +``` +ghostty +list-themes +``` + +## list-colors +The `list-colors` command is used to list all the named RGB colors in +Ghostty. + +``` +ghostty +list-colors +``` + +## list-actions +The `list-actions` command is used to list all the available keybind +actions for Ghostty. These are distinct from the CLI Actions which can +be listed via `+help` + +Flags: + + * `--docs`: will print out the documentation for each action. + +``` +ghostty +list-actions +``` + +## show-config +The `show-config` command shows the current configuration in a valid Ghostty +configuration file format. + +When executed without any arguments this will output the current +configuration that is different from the default configuration. If you're +using the default configuration this will output nothing. + +If you are a new user and want to see all available options with +documentation, run `ghostty +show-config --default --docs`. + +The output is not in any specific order, but the order should be consistent +between runs. The output is not guaranteed to be exactly match the input +configuration files, but it will result in the same behavior. Comments, +whitespace, and other formatting is not preserved from user configuration +files. + +Flags: + + * `--default`: Show the default configuration instead of loading + the user configuration. + + * `--changes-only`: Only show the options that have been changed + from the default. This has no effect if `--default` is specified. + + * `--docs`: Print the documentation above each option as a comment, + This is very noisy but is very useful to learn about available + options, especially paired with `--default`. + +``` +ghostty +show-config +``` + +## validate-config +The `validate-config` command is used to validate a Ghostty config file. + +When executed without any arguments, this will load the config from the default +location. + +Flags: + + * `--config-file`: can be passed to validate a specific target config file in + a non-default location + +``` +ghostty +validate-config +``` + +## show-face +The `show-face` command shows what font face Ghostty will use to render a +specific codepoint. Note that this command does not take into consideration +grapheme clustering or any other Unicode features that might modify the +presentation of a codepoint, so this may show a different font face than +Ghostty uses to render a codepoint in a terminal session. + +Flags: + + * `--cp`: Find the face for a single codepoint. The codepoint may be specified + in decimal (`--cp=65`), hexadecimal (`--cp=0x41`), octal (`--cp=0o101`), or + binary (`--cp=0b1000001`). + + * `--string`: Find the face for all of the codepoints in a string. The + string must be a valid UTF-8 sequence. + + * `--style`: Search for a specific style. Valid options are `regular`, `bold`, + `italic`, and `bold_italic`. + + * `--presentation`: If set, force searching for a specific presentation + style. Valid options are `text` and `emoji`. If unset, the presentation + style of a codepoint will be inferred from the Unicode standard. + +``` +ghostty +show-face +``` + +## crash-report +The `crash-report` command is used to inspect and send crash reports. + +When executed without any arguments, this will list existing crash reports. + +This command currently only supports listing crash reports. Viewing +and sending crash reports is unimplemented and will be added in the future. + +``` +ghostty +crash-report +``` + diff --git a/docs/nav.json b/docs/nav.json index 87e9645a..13f990b4 100644 --- a/docs/nav.json +++ b/docs/nav.json @@ -93,6 +93,11 @@ "path": "/", "title": "Overview" }, + { + "type": "link", + "path": "/commands", + "title": "CLI Actions" + }, { "type": "link", "path": "/theme", From ecc123028c5c8b0fd3575bf54c916804a64ec20c Mon Sep 17 00:00:00 2001 From: Anund Date: Wed, 8 Jan 2025 17:45:31 +1100 Subject: [PATCH 2/2] docs: match release version 1.0.1 --- docs/features/commands.mdx | 87 +++++++++++++++----------------------- 1 file changed, 33 insertions(+), 54 deletions(-) diff --git a/docs/features/commands.mdx b/docs/features/commands.mdx index 19587188..4b1d5581 100644 --- a/docs/features/commands.mdx +++ b/docs/features/commands.mdx @@ -7,19 +7,16 @@ Ghostty includes a number of utility actions that can be accessed as subcommands Actions provide utilities to work with config, list keybinds, list fonts, demo themes, and debug. ## version -The `version` command is used to display information about Ghostty. Recognized as -either `+version` or `--version`. +The `version` command is used to display information about Ghostty. ``` ghostty --version ``` ## help -The `help` command shows general help about Ghostty. Recognized as either -`-h, `--help`, or like other actions `+help`. - -You can also specify `--help` or `-h` along with any action such as -`+list-themes` to see help for a specific action. +The `help` command shows general help about Ghostty. You can also specify +`--help` or `-h` along with any action such as `+list-themes` to see help +for a specific action. ``` ghostty --help @@ -35,21 +32,14 @@ by family name, then font name. If a family name is given with `--family`, the sorting will be disabled and the results instead will be shown in the same priority order Ghostty would use to pick a font. -Flags: - - * `--bold`: Filter results to specific bold styles. It is not guaranteed - that only those styles are returned. They are only prioritized. - - * `--italic`: Filter results to specific italic styles. It is not guaranteed - that only those styles are returned. They are only prioritized. - - * `--style`: Filter results based on the style string advertised by a font. - It is not guaranteed that only those styles are returned. They are only - prioritized. +The `--family` argument can be used to filter results to a specific family. +The family handling is identical to the `font-family` set of Ghostty +configuration values, so this can be used to debug why your desired font may +not be loading. - * `--family`: Filter results to a specific font family. The family handling - is identical to the `font-family` set of Ghostty configuration values, so - this can be used to debug why your desired font may not be loading. +The `--bold` and `--italic` arguments can be used to filter results to +specific styles. It is not guaranteed that only those styles are returned, +it will just prioritize fonts that match those styles. ``` ghostty +list-fonts @@ -64,15 +54,11 @@ loaded by the config file. If no config file is found or there aren't any changes to the keybinds it will print out the default ones configured for Ghostty -Flags: - - * `--default`: will print out all the default keybinds - - * `--docs`: currently does nothing, intended to print out documentation - about the action associated with the keybinds +The `--default` argument will print out all the default keybinds configured +for Ghostty - * `--plain`: will disable formatting and make the output more - friendly for Unix tooling. This is default when not printing to a tty. +The `--plain` flag will disable formatting and make the output more +friendly for Unix tooling. This is default when not printing to a tty. ``` ghostty +list-keybinds @@ -111,7 +97,6 @@ to the resources directory. Flags: * `--path`: Show the full path to the theme. - * `--plain`: Force a plain listing of themes. ``` @@ -127,13 +112,10 @@ ghostty +list-colors ``` ## list-actions -The `list-actions` command is used to list all the available keybind -actions for Ghostty. These are distinct from the CLI Actions which can -be listed via `+help` +The `list-actions` command is used to list all the available keybind actions +for Ghostty. -Flags: - - * `--docs`: will print out the documentation for each action. +The `--docs` argument will print out the documentation for each action. ``` ghostty +list-actions @@ -175,18 +157,27 @@ ghostty +show-config ## validate-config The `validate-config` command is used to validate a Ghostty config file. -When executed without any arguments, this will load the config from the default -location. - -Flags: +When executed without any arguments, this will load the config from the default location. - * `--config-file`: can be passed to validate a specific target config file in - a non-default location +The `--config-file` argument can be passed to validate a specific target config +file in a non-default location. ``` ghostty +validate-config ``` +## crash-report +The `crash-report` command is used to inspect and send crash reports. + +When executed without any arguments, this will list existing crash reports. + +This command currently only supports listing crash reports. Viewing +and sending crash reports is unimplemented and will be added in the future. + +``` +ghostty +crash-report +``` + ## show-face The `show-face` command shows what font face Ghostty will use to render a specific codepoint. Note that this command does not take into consideration @@ -214,15 +205,3 @@ Flags: ghostty +show-face ``` -## crash-report -The `crash-report` command is used to inspect and send crash reports. - -When executed without any arguments, this will list existing crash reports. - -This command currently only supports listing crash reports. Viewing -and sending crash reports is unimplemented and will be added in the future. - -``` -ghostty +crash-report -``` -