Config files created automatically by the open_config action should have an explanation for users, because an empty file just staring you in the face doesn't leave you much of a path forward without turning around and looking at the documentation. While the user should be reading documentation, it's also preferable for them to not need to proactively do so in most cases.
The default config file then should be a header which explains the config and references the documentation. Important elements of this explanation:
- Where is this file located? So that the user knows how to edit it in their preferred editor if they don't like the one that was opened when they used the action. This should prevent issues where a user creates a config on macOS in the
Application Support location and then a second one in the XDG location which conflicts.
- What is this file format? So that the user knows how to specify config options.
- What config options are available? A link to the docs should be included as well as a reference to
+show-config.
Here is my suggestion:
# </path/to/ghostty/config>
#
# Docs: https://ghostty.org/docs/config
#
# This is the configuration file for Ghostty. This file is created automatically
# if the `open_config` action is invoked and Ghostty can't find any config files
# on your system. It has been placed at the path listed at the top of the file.
#
# This file is not initialized with any default options set because the majority
# of users should only need to set a few things. While it is recommended to read
# the docs, a brief explanation of the syntax for this file can be found below.
#
# Syntax
# ---
# # Any line beginning with a # is a comment. It's not possible to put
# # a comment after a config option, it will be interpreted as a part
# # of the value. For example, this will have a value of "#123abc":
# background = #123abc
#
# # Spacing around the equals sign does not matter.
# # All of these are identical:
# key=value
# key= value
# key =value
# key = value
#
# # Empty values are used to reset config keys to default
# key =
#
# # Some config options have unique syntax for their value,
# # which is explained in the docs for that config option.
# ---
#
# Tip: You can run `ghostty +show-config --default --docs` to view a
# list of all available config options and their default values.
#
# See also: `man ghostty`
#
# Please consider reading the full docs.
Config files created automatically by the
open_configaction should have an explanation for users, because an empty file just staring you in the face doesn't leave you much of a path forward without turning around and looking at the documentation. While the user should be reading documentation, it's also preferable for them to not need to proactively do so in most cases.The default config file then should be a header which explains the config and references the documentation. Important elements of this explanation:
Application Supportlocation and then a second one in the XDG location which conflicts.+show-config.Here is my suggestion: