Switch to TOML for configuration file

[chrisduerr]

I'm quite honestly tired of looking at YAML files with broken indentation. While YAML is an awful format even for experienced users, clearly it's completely impossible for inexperienced ones to grasp its concept. And the documentation of our configuration file with everything commented out by default probably doesn't help.

Since as far as I know all previous issues with TOML have been fixed and escape sequences can be easily specified in TOML strings now, I think it would make sense to switch to TOML as our default format.

In a transitory period we could probably get away with just loading existing YAML files and writing them out as TOML, to allow for backward compatibility. This will probably produce somewhat messy TOML files, but I can't imagine an auto-generated TOML file would be much worse than a YAML file.

The only major drawbacks I see is that this is a rather big change that will no doubt annoy a bunch of people and some more advanced features of YAML (like anchors) are not supported in TOML. But nobody really needs anchors and I kinda like annoying people.

@kchibisov You proposed this a while ago on IRC, do you think this is a bad idea?

See #1217 for prior discussions.

[kchibisov]

@kchibisov You proposed this a while ago on IRC, do you think this is a bad idea?

I do like toml more. In general what we can do is to have support for both at the same time with a warning to do a conversion with some alacritty flag. But having both at the same time doesn't sound like fun to maintain.

I do wonder how stuff like multiple bindings will end up working.

Since as far as I know all previous issues with TOML have been fixed and escape sequences can be easily specified in TOML strings now, I think it would make sense to switch to TOML as our default format.

Is that supported by serde at least? Though, patching shouldn't be a problem.

[keltia]

HCL is also a good if not better choice.

[skyfaller]

Aw man, I use anchors heavily in my Alacritty yaml config, for changing themes with scripting. I'm not quite sure what the best way to do this with TOML is. Do you have any suggestions for rewriting something like this in TOML?

schemes:
  # Colors (Blood Moon)
  blood_moon: &dark
    # Default colors:
    primary:
      background: '#10100E'
      foreground: '#C6C6C4'

    # Normal colors:
    normal:
      black:   '#10100E'
      red:     '#C40233'
      green:   '#009F6B'
      yellow:  '#FFD700'
      blue:    '#0087BD'
      magenta: '#9A4EAE'
      cyan:    '#20B2AA'
      white:   '#C6C6C4'

    # Bright colors:
    bright:
      black:   '#696969'
      red:     '#FF2400'
      green:   '#03C03C'
      yellow:  '#FDFF00'
      blue:    '#007FFF'
      magenta: '#FF1493'
      cyan:    '#00CCCC'
      white:   '#FFFAFA'

  # Colors (Terminal.app Basic)
  terminal_app_basic: &light
    primary:
      background: '#FFFFFF'
      foreground: '#000000'
    normal:
      black:      '#000000'
      red:        '#990000'
      green:      '#00A600'
      yellow:     '#999900'
      blue:       '#0000B2'
      magenta:    '#B200B2'
      cyan:       '#00A6B2'
      white:      '#BFBFBF'
    bright:
      black:      '#666666'
      red:        '#E50000'
      green:      '#00D900'
      yellow:     '#D0D000'
      blue:       '#0000FF'
      magenta:    '#E500E5'
      cyan:       '#00E5E5'
      white:      '#E5E5E5'

  # Colors (Oceanic Next)
  oceanic_next: &blue
    # Default colors:
    primary:
      background: '#1b2b34'
      foreground: '#d8dee9'

    # Colors the cursor will use if `custom_cursor_colors: ` is true
    cursor:
      text: '#1b2b34'
      cursor: '#ffffff'

    # Normal colors:
    normal:
      black:   '#343d46'
      red:     '#EC5f67'
      green:   '#99C794'
      yellow:  '#FAC863'
      blue:    '#6699cc'
      magenta: '#c594c5'
      cyan:    '#5fb3b3'
      white:   '#d8dee9'

    # Bright colors:
    bright:
      black:   '#343d46'
      red:     '#EC5f67'
      green:   '#99C794'
      yellow:  '#FAC863'
      blue:    '#6699cc'
      magenta: '#c594c5'
      cyan:    '#5fb3b3'
      white:   '#d8dee9'

# Colors (Gruvbox light)
  gruvbox_light: &yellow
    # Default colors:
    primary:
      # hard contrast: background = '#f9f5d7'
      background: '#fbf1c7'
      # soft contrast: background = '#f2e5bc'
      foreground: '#3c3836'

    # Normal colors:
    normal:
      black:   '#fbf1c7'
      red:     '#cc241d'
      green:   '#98971a'
      yellow:  '#d79921'
      blue:    '#458588'
      magenta: '#b16286'
      cyan:    '#689d6a'
      white:   '#7c6f64'

    # Bright colors:
    bright:
      black:   '#928374'
      red:     '#9d0006'
      green:   '#79740e'
      yellow:  '#b57614'
      blue:    '#076678'
      magenta: '#8f3f71'
      cyan:    '#427b58'
      white:   '#3c3836'

  # Colors (Tango)
  tango: &green
    primary:
      background: '#000000'
      foreground: '#00ff00'

    # Normal colors:
    normal:
        black:   '#2e3436'
        red:     '#cc0000'
        green:   '#73d216'
        yellow:  '#edd400'
        blue:    '#3465a4'
        magenta: '#75507b'
        cyan:    '#06989a'
        white:   '#d3d7cf'

    # Bright colors:
    bright:
        black:   '#2e3436'
        red:     '#ef2929'
        green:   '#8ae234'
        yellow:  '#fce94f'
        blue:    '#729fcf'
        magenta: '#ad7fa8'
        cyan:    '#34e2e2'
        white:   '#eeeeec'

  # Colors (Monokai Soda)
  monokai_soda: &purple
    # Default colors:
    primary:
      background: '#1a1a1a'
      foreground: '#c4c5b5'

    # Normal colors:
    normal:
      black:   '#1a1a1a'
      red:     '#f4005f'
      green:   '#98e024'
      yellow:  '#fa8419'
      blue:    '#9d65ff'
      magenta: '#f4005f'
      cyan:    '#58d1eb'
      white:   '#c4c5b5'

    # Bright colors:
    bright:
      black:   '#625e4c'
      red:     '#f4005f'
      green:   '#98e024'
      yellow:  '#e0d561'
      blue:    '#9d65ff'
      magenta: '#f4005f'
      cyan:    '#58d1eb'
      white:   '#f6f6ef'

  # Colors (Darkside)
  darkside: &red
    primary:
      background: '#222324'
      foreground: '#BABABA'

    # Normal colors
    normal:
      black:    '#000000'
      red:      '#E8341C'
      green:    '#68C256'
      yellow:   '#F2D42C'
      blue:     '#1C98E8'
      magenta:  '#8E69C9'
      cyan:     '#1C98E8'
      white:    '#BABABA'

    # Bright colors
    bright:
      black:    '#666666'
      red:      '#E05A4F'
      green:    '#77B869'
      yellow:   '#EFD64B'
      blue:     '#387CD3'
      magenta:  '#957BBE'
      cyan:     '#3D97E2'
      white:    '#BABABA'

  dracula: &lavender
    primary:
      background: '0x282a36'
      foreground: '0xf8f8f2'
    cursor:
      text: CellBackground
      cursor: CellForeground
    vi_mode_cursor:
      text: CellBackground
      cursor: CellForeground
    search:
      matches:
        foreground: '0x44475a'
        background: '0x50fa7b'
      focused_match:
        foreground: '0x44475a'
        background: '0xffb86c'
      bar:
        background: '0x282a36'
        foreground: '0xf8f8f2'
    line_indicator:
      foreground: None
      background: None
    selection:
      text: CellForeground
      background: '0x44475a'
    normal:
      black:   '0x000000'
      red:     '0xff5555'
      green:   '0x50fa7b'
      yellow:  '0xf1fa8c'
      blue:    '0xbd93f9'
      magenta: '0xff79c6'
      cyan:    '0x8be9fd'
      white:   '0xbfbfbf'
    bright:
      black:   '0x4d4d4d'
      red:     '0xff6e67'
      green:   '0x5af78e'
      yellow:  '0xf4f99d'
      blue:    '0xcaa9fa'
      magenta: '0xff92d0'
      cyan:    '0x9aedfe'
      white:   '0xe6e6e6'
    dim:
      black:   '0x14151b'
      red:     '0xff2222'
      green:   '0x1ef956'
      yellow:  '0xebf85b'
      blue:    '0x4d5b86'
      magenta: '0xff46b0'
      cyan:    '0x59dffc'
      white:   '0xe6e6d1'

# Dark options: dark,green,purple,blue,red,lavender
# Light options: light,yellow
colors: *light
# To change color theme using sd, try:
# sd '^colors: *.*$' 'colors: *light' ~/.config/alacritty/alacritty.yml
# I've also defined a fish function "theme-alacritty"

[kchibisov]

@skyfaller use imports.

[skyfaller]

Thank you for the tip. For anyone who needs more detail on imports, some documentation: https://github.com/alacritty/alacritty/blob/master/extra/man/alacritty.5.scd#general

Any chance you could show some examples of how imports are used? Is there a sample config file somewhere?

[chrisduerr]

If you're looking for toml syntax docs, you can find array docs here: https://toml.io/en/v1.0.0#array

Other than that it's just exactly as documented in the manpage. I strongly recommend looking at the raw text of the manpage, the markdown rendering is pretty screwed up (it strips the type from the array for example).

[pi-rho]

Is it hard to support both? TOML pokes me in the eye while YAML is super comfy. Everyone has their preferences. Can't serde shield Alacritty and allow users to pick their favorite?

[kchibisov]

@pi-rho you better not know how many issues we've got because option is not working and broken indention with yml, it's not fun to spend our time on trouble shooting them, with toml we warn on unused keys and you don't have to deal with indention, and you really don't have to deal with configuring alacritty that much anyway. It's true that generated config might be a bit off, but hand written ones are not that bad.

[pi-rho]

That may be so, but this is where I'm at today. ;)

diff --git i/alacritty/src/config/mod.rs w/alacritty/src/config/mod.rs
index 821e9b6b..312b8828 100644
--- i/alacritty/src/config/mod.rs
+++ w/alacritty/src/config/mod.rs
@@ -228,7 +228,7 @@ pub fn deserialize_config(path: &Path) -> Result<Value> {
     // Convert YAML to TOML as a transitionary fallback mechanism.
     let extension = path.extension().unwrap_or_default();
     if (extension == "yaml" || extension == "yml") && !contents.trim().is_empty() {
-        warn!("YAML config {path:?} is deprecated, please migrate to TOML");
+        //warn!("YAML config {path:?} is deprecated, please migrate to TOML");

         let value: serde_yaml::Value = serde_yaml::from_str(&contents)?;
         contents = toml::to_string(&value)?;

[chrisduerr]

Sooner or later support for YAML will be dropped. There is no reason why we'd maintain both and even the current YAML implementation is just a subpar fill-in for the transition period.

[nickeb96]

Do I need to do something specific to enable the TOML escape sequences mentioned above? I'm getting an error when I try to use them:

[8215.690349958s] [ERROR] [alacritty_config_derive] Unable to load config
Config error: TOML parse error at line 122, column 12
    |
122 | chars = "\e[13;2u"
    |            ^
invalid escape sequence
expected `b`, `f`, `n`, `r`, `t`, `u`, `U`, `\`, `"`

[chrisduerr]

\e is not supported in TOML (yet). You need to use \u001b instead.

Both \e and \x1b will be supported with the next TOML release.

[bluz71]

And the documentation of our configuration file with everything commented out by default probably doesn't help.

Can an alacritty.toml be created in this base of this repository mimicking the previous alacritty.yml file? That is with all options listed and mostly commented out?

I can't tell how many times I referred to that file to tweak a setting here and there.

That document was the document I referred to as the configuration source of truth. Now I feel lost.

[kchibisov]

That document was the document I referred to as the configuration source of truth. Now I feel lost.

But you have man page now with all the options? And a separate for all default bindings.

[bluz71]

Ok, I had a look now. The alacritty.5 man page has the information, so that is good to know it exists somewhere.

I don't think it is quite is quick and easy as the previous alacritty.yml example/instance file. But opinions will vary.

Thanks for the knowledge.

[kchibisov]

But you can type man 5 alacritty in your terminal and have all the docs without a need to go on a github.com, because config before wasn't shipped even.

[Lucksinia]

...I am sorry for opening this one, but No manual entry for alacritty in section 5?

But you can type man 5 alacritty in your terminal and have all the docs without a need to go on a github.com, because config before wasn't shipped even.

[kchibisov]

I am sorry for opening this one, but No manual entry for alacritty in section 5?

if you've built from source build man pages as well, no stable release was made with toml yet.

[pi-rho]

my eyes are bleeding

[[keyboard.bindings]]
action = "ClearSelection"
key = "C"
mode = "Vi|~Search"
mods = "Control|Shift"

[[keyboard.bindings]]
action = "PasteSelection"
key = "Insert"
mods = "Shift"

[[keyboard.bindings]]
action = "ResetFontSize"
key = "Key0"
mods = "Control"

[[keyboard.bindings]]
action = "IncreaseFontSize"
key = "Equals"
mods = "Control"

:)

[kchibisov]

@pi-rho

you're free to format the config however you want, you can use something like that

[keyboard]
bindings = [
  { key = "C", mods = "Control|Shift", mode = "Vi|Search", action = "ClearSelection" },
  { key = "Insert", mods = "Shift", action = "Paste" }
]

[cy8aer]

It would be nice to have an example toml now because you are not able to prepare a color scheme based theming without the knowledge how to transform it from yaml. Migration makes the new toml unfunctional for example.

[J-MR-T]

I am so sick and tired of things always changing and breaking on me.

Then don't use software in beta? Is that such a difficult concept to grasp?

The readme says

The software is considered to be at a beta level of readiness; there are a few missing features and bugs to be fixed

not

The software is considered to be at a beta level of readiness; we "kinda like annoying people" so be prepared to be annoyed.

---

To be clear, I don't even question the migration itself, breaking changes are sometimes beneficial or even required; personally, I also don't mind migrating some alacritty config files once per year, but this comment really threw me off.

TL;DR: I don't like using software that wants to annoy me.

[bluz71]

I found the migration simple and effective, a small amount of customization later, 10 mins all in all. Easy-peasy.

I suspect there is a silent majority where that is the case.

I am pleased with the change, TOML is a far better config format in comparison to YAML.

[J-MR-T]

As I said, I don't question this migration itself. I question the attitude of liking to annoy people.

Side note, I'm sure you could read the comment about annoying people as a joke, but even if it was, that sort of joke only works, if there is a kernel of truth to it.

[aarav2you]

HCL is also a good if not better choice.

Unfortunately your opinion is flat out wrong

[zeionara]

That may be so, but this is where I'm at today. ;)

diff --git i/alacritty/src/config/mod.rs w/alacritty/src/config/mod.rs
index 821e9b6b..312b8828 100644
--- i/alacritty/src/config/mod.rs
+++ w/alacritty/src/config/mod.rs
@@ -228,7 +228,7 @@ pub fn deserialize_config(path: &Path) -> Result<Value> {
     // Convert YAML to TOML as a transitionary fallback mechanism.
     let extension = path.extension().unwrap_or_default();
     if (extension == "yaml" || extension == "yml") && !contents.trim().is_empty() {
-        warn!("YAML config {path:?} is deprecated, please migrate to TOML");
+        //warn!("YAML config {path:?} is deprecated, please migrate to TOML");

         let value: serde_yaml::Value = serde_yaml::from_str(&contents)?;
         contents = toml::to_string(&value)?;

Thank you! I despise the TOML format. It is pain to read and edit the text. No other option than to disable the annoying warning in source.

Are there really people who think TOML is better than YAML? Why do you believe so?

In any case, I would be happy if you don't stop supporting YAML format

[ikouchiha47]

Which is fine. migrating to toml. But I hope I find a migration tool from yaml to toml. I mean I have had my dotfiles there for nearly half a decade now. Only change was for neovim. But then it was an eniterly different thing. Who is going to change the config manually now. Its easier to just find another terminal. 😆

[chrisduerr]

If only Alacritty devs had integrated an automatic migration tool specifically built to ease this transition for existing users.

[anonhostpi]

I don't understand the practice of not supporting both config formats. Even moreso, deprecating a defacto standard.

Even if you are running into the problem of "too many indentation issues," then write a better SEO-optimized wiki, or add the problem to the issue template. It shouldn't take a lot of effort to educate end users on the defacto standard for configuration files.

Hell, you probably don't need to do more than update the issue template, because there are plenty of free education tools for YAML. Even linking a simple YAML validator in the issue template (and the installation docs) like https://www.yamllint.com/ should fix the original problem statement.

I will say that adding and switching the default configuration language to toml does make sense, because of the aforementioned better support for character escaping, but fully deprecating yaml does not.

You can't really justify deprecation with "can't support" either, because yaml and toml are just wrappers for json. If you can support one of the 3 (yaml, toml, or json), your app can support the other 2.

You might justify it with "don't want to support," but even then that is resolved with the above statement "write a better SEO-optimized wiki, or add the problem to the issue template"

[kchibisov]

Even if you are running into the problem of "too many indentation issues," then write a better SEO-optimized wiki, or add the problem to the issue template. It shouldn't take a lot of effort to educate end users on the defacto standard for configuration files.

No one ever reads, remember that, people who read don't have issues with any of that. Alacritty is also not a stable software, as in pre 1.0, so we don't have to bother with legacy, this is stated in README and it was like that for a long time. After 1.0 no one will ever change the config format.

I will say that adding and switching the default configuration language to toml does make sense, because of the aforementioned better support for character escaping, but fully deprecating yaml does not.

toml is much simpler to work with, where with yaml you have e.g. yaml hooks.

You might justify it with "don't want to support," but even then that is resolved with the above statement "write a better SEO-optimized wiki, or add the problem to the issue template"

again, no one ever reads any of that, even with TOML all the docs are right there with examples and such, yet no one ever reads and asks ChatGPT or says on issues tracker how bad we are.

Also, keep in mind that unless someone rewrites serde(rust library for serialization) none of that is an easy task, because you have to convert between formats, and you can't convert yaml hooks at all, so you have to develop 2 internal reprs for all of that, which is just a madness and no-one has time for that thing (if you have go ahead and write serde alternative in rust for us, though by this point we'll sunset yaml config all together).

[anonhostpi]

The problem is that eventually, once Alacritty matures, this deprecated feature will turn right back into a feature request, since YAML is more widely adopted.

Also, "simple" is subjective. As you can see from the above, people will have complaints about TOML as well as YAML. People who are comfortable programming in Python and writing microservices (e.g. docker, gh-actions, etc) are going to find YAML simpler than TOML. People who deal with OS configuration files regularly are going to find TOML simpler than YAML. Using "simpler" or "better" when it comes to describing 2 languages that do the same things nearly identically is futile.

What you said about Rust's support for serialization languages does make sense, but then you end up with the problem in my first sentence. By the time that Alacritty matures, it is likely that Rust will have more reliable support for serialization languages.

But that's not even the main problem. It is very likely that people are going to request adding it back before Rust fixes serde, just simply because of it's wider adoption, end-user preference, and established precedence. As you said, people are going to continue to ignore the docs, and just use copilot/gpt-generated files to install your software, which are all going to tell them to use YAML. So, instead of getting "YAML indentation" issue-spam, you're going to get "why is yaml deprecated?"/"FR: add YAML" issue-spam.

[chrisduerr]

The problem is that eventually, once Alacritty matures, this deprecated feature will turn right back into a feature request

How is this a problem? There will always be a bunch of garbage feature requests, rejecting them is not an issue.

What you said about Rust's support for serialization languages does make sense, but then you end up with the problem in my first sentence. By the time that Alacritty matures, it is likely that Rust will have more reliable support for serialization languages.

This just demonstrates lack of knowledge of the Rust ecosystem.

So, instead of getting "YAML indentation" issue-spam, you're going to get "why is yaml deprecated?"/"FR: add YAML" issue-spam.

So instead of hunting bugs in user configs we can just close issues immediately. I don't see how this isn't an easy win.

[anonhostpi]

The problem is that eventually, once Alacritty matures, this deprecated feature will turn right back into a feature request

How is this a problem? There will always be a bunch of garbage feature requests, rejecting them is not an issue.

So is rejecting "indentation issues"

What you said about Rust's support for serialization languages does make sense, but then you end up with the problem in my first sentence. By the time that Alacritty matures, it is likely that Rust will have more reliable support for serialization languages.

This just demonstrates lack of knowledge of the Rust ecosystem.

I have doubts that it is an inaccurate statement based off the lifetimes of several other languages. Serialization is a basic language feature. I doubt that any language community isn't going to work towards adopting de facto serialization standards.

From what I understand from the Rust ecosystem is that they do intend to offer competent YAML support: https://docs.rs/serde_yaml/latest/serde_yaml/

So, instead of getting "YAML indentation" issue-spam, you're going to get "why is yaml deprecated?"/"FR: add YAML" issue-spam.

So instead of hunting bugs in user configs we can just close issues immediately. I don't see how this isn't an easy win.

You won't have to bug hunt yaml indentation problems, if you add yaml and toml linters to the issue template.

If an end user doesn't lint their own files, then don't troubleshoot. It doesn't matter if its YAML or TOML.

[chrisduerr]

From what I understand from the Rust ecosystem is that they do intend to offer competent YAML support: https://docs.rs/serde_yaml/latest/serde_yaml/

Version 0.8 of this library was using yaml-rs, which was abandoned because yaml is an awful file format that you cannot write parsers for. Version 0.9 switched to a Rust translation of libyaml, a C Library that was abandoned 3 years ago and has numerous known security issues.

So since you're clearly an expert in this field, please tell me more about the plethora of amazing deserialization options for yaml. It's such a cool format, I'd love to learn about more popular Rust libraries supporting it.

[amne]

Docs say you can override shell with

[shell]
program="myshell"
args=["myargs","more"]

And then immediately after that it says working_directory is either a string or None but it's a root level field.
How do you parse this?

[shell]
program="myshell"
args=["myargs","more"]

working_directory="/home/whatever"

[kchibisov]

How do you parse this?

The working directory ends up in the [shell] section, you should just put it above everything else.

[SidOfc]

Hello all, at first I liked my yaml config and I found that the generated toml version looked a bit clunky (not trying to dunk on tools which convert my config file for essentially free, thank you for saving me time! <3).

• Initial alacritty.yml
• Generated alacritty.toml

So I went and found this issue because I was wondering about whether yaml support was actually being completely phased out (which seems to be desired by the OP). I figured the next best thing was to try and improve the readability of the toml file since that seems to be the way forward. I took a quick stroll through the specs which are actually remarkably easy to understand and came up with this version:

• Current alacritty.toml

Honestly it's quite good, I think I'm liking this more than my yaml config actually :)
Nobody particularly "loves" changes like this but OP has done the work to provide a deprecation warning accompanied by tooling to automatically get to a working toml version. Technically Alacritty is still in "beta" as well so it shouldn't come as a surprise that some changes will still be made.

All this is just to say please try to understand the OP's reasoning, take 5 minutes to improve the generated toml file using info from the specs and enjoy the result knowing it's very likely here to stay.

Finally, my apologies if this adds just more noise to the conversation. Just wanted to share some thoughts since there were some small arguments going on in the conversation.

[chrisduerr]

All this is just to say please try to understand the OP's reasoning, take 5 minutes to improve the generated toml file using info from the specs and enjoy the result knowing it's very likely here to stay.

There's no point in manually writing toml formatters to try and get it into a subjectively better format when there's no way we'll ever match exactly the way it should be either. I used the automated tool to get started, then cleaned it up by hand, if people have an issue with that they can write their own migration tool.

[SidOfc]

That makes complete sense to me, I'm already happy about the fact that some simple conversion is included and just works. Taking a little bit of time to further refine automatically converted configuration is a small price to pay for what is in my opinion the best terminal out there.

Thanks for all your work!

[amne]

How do you parse this?

The working directory ends up in the [shell] section, you should just put it above everything else.

of course. but how do you get out of section and back to root level? is toml limited here?

[chrisduerr]

of course. but how do you get out of section and back to root level? is toml limited here?

Yeah this can be a bit confusing for people new to toml. Hopefully #7908 will resolve this but unfortunately it has stalled (for now). I'd like to see that land in Alacritty's next stable release.