Toml Bombadil is a dotfile manager written in rust.
I wrote Toml Bombadil because I kept changing my desktop environment : switching from i3 to sway, from sway to xfce, from xfce to gnome and back to sway. When you keep changing your working environment like this you end up with several problems : - Some symlinks will end up orphans. - Not every program you use support Xresources and you will most probably have to manually edit some themes/config. - When starting a fresh installation you will very likely need to adapt your existing dotfiles to your new machine. - It is a mess
Toml Bombadil try to solve this with a simple addition to the symlink method used by other tools : instead of creating a symlink from a dotfile to the actual config path of a program, it will create a copy of it and symlink the copy. This additional step allow to use your original dotfile as a template and inject variables in the copy. You can have multiple value files in the same dotfile repository and change color scheme, or any value on the fly.
In addition, this is completely optional, you could start using Toml Bombadil only to generate symlinks and templatize your dot file progressively.
shell script
cargo install toml-bombadil
shell script
yay -S bombadil-bin
1. Setup :
shell script
git clone https://github.com/my_org/dotfiles
cd my_dotfiles && touch bombadil.toml
If you are using git you might want to add .dots to your .gitignore.
2. Configuration :
Toml bombadil needs a toml config file, along this readme we will call it bombadil.toml.
```toml
dotfilesdir = "mydotfiles" [settings]
vars = [ "vars.toml" ]
hooks = [ "sway reload" ] [settings.dots]
source is relative to dotfiles_dirtarget shall be relative to $HOME directory or absolute.sway = { source = "sway", target = ".config/sway" }
alacritty = { source = "alacritty", target = ".config/alacritty/alacritty.yml" } ```
3. Linking bombadil :
For Bombadil to be able to run from any directory and use different config files we need to symlink bombadil config to
$XDG_CONFIG_DIR/bombadil.toml :
shell script
bombadil install -c my_dotfiles/bombadil.toml
If you want to switch to another config simply run :
shell script
bombadil install -c my_dotfiles/bombadil-i3.toml
4. Install template and symlink :
shell script
bombadil link
This command will do the following :
- Remove {dotfiles_dir}/.dots and any symlink pointing to a sub directory/file.
- Inject variables (if you defined some) in a copy of dot entries listed in Bombadil config.
- Write the copies to {dotfiles_dir}/.dots.
- Symlink dot entries.
- Run post install hooks.
Now that your dot files are symlinked with Bombadil you can define some variables. A Bombadil var files is a valid toml file containing only key with string values :
For example you have the following file in {dotfiles_dir}/vars.toml.
toml
terminal = "alacritty"
background = "#292C3E"
foreground = "#EBEBEB"
text = "#FF261E"
cursor = "#FF261E"
black = "#0d0d0d"
red = "#FF301B"
green = "#A0E521"
yellow = "#FFC620"
blue = "#1BA6FA"
You can use the var file by adding the following to your Bombadil config :
toml
[settings]
vars = [ "vars.toml" ]
Let's say you have the following dot entry :
toml
[settings.dots]
alacritty = { source = "alacritty", target = ".config/alacritty/alacritty.yml" }
alacritty.yaml color scheme could look like this :
```yaml
...
colors: primary: background: "[background]" foreground: "[foreground]" cursor: text: "[text]" cursor: "[cursor]" ... ```
The output file actually linked to alacritty config would be this :
```yaml ...
colors: primary: background: "#292C3E" foreground: "#EBEBEB" cursor: text: "#FF261E" cursor: "#FF261E" ... ```
To update variables, and the current config simply run bombadil link.
Sometimes it could be handy to use different variables names for the same values. For instance if you want to define a system wide color scheme, you could define the following variables references :
```toml
[settings] vars = [ "vars.toml", "themevars.toml", "alacrittyvars.toml", "sway_vars.toml" ]
```
By prefixing a variable value with % you tell bombadil to look for a variable reference.
Here %red, %black and %green will be replaced with the actual red, black and green values.
```toml
red = "#ff0000" black = "#000000" green = "#008000" ```
```toml
swayclientfocusedbackground = "%black" swayclientfocusedborder = "#ffff00"
```
```toml
alacrittybackground = "%black" alacrittycursor = "%green"
```
Before going further with this ensure .dots is in dotfiles repository's .gitignore!
To use encryption this you need to have gnupg installed, and a pair of gpg keys.
Add your gpg user id to bombadil's config :
```toml dotfile_dir = "bombadil-example"
gpguserid = "me@example.org"
vars = [ "vars.toml" ]
[settings.dots] maven = { source = "maven/settings.xml", target = ".m2/settings.xml"} ```
Add secret variable :
bombadil add-secret -k "server_password" -v "hunter2" -f vars.toml
or if you want to avoid having secrets in your shell history :
bombadil add-secret -k "server_password" -f vars.toml --ask
Use the secret value in any dot entry :
xml
<server>
<id>my.server</id>
<username>Tom</username>
<password>__[server_password]__</password>
</server>
Make sure the secret has been written and encrypted :
bombadil get secrets
bombadil get vars | grep server_password
Relink your dotfile to inject the secret value :
bombadil link
This is it, you can now commit your secret safely to your dotfile repository !
When linking entire directories you might want to ignore some file or subfolder from the copy/symlink process.
Given the following directory : ```
├── alacritty-nord.toml └── alacritty.yml ```
You can prevent alacritty-nord.toml var file from being copied and linked to your system by adding the following
to your alacritty dot config :
toml
alacritty = { source = "alacritty", target = ".config/alacritty", ignore = [ "*.toml" ] }
ignore field accept an array of glob pattern. ignore entries support gitignore's extended glob syntax. Although it is perfectly fine to use only var files using settings.vars, managing themes and profile can be a tedious
process. To provide isolation between dotfiles vars, you can use the dot var attribute :
By default, bombadil will look for a file named vars.toml in every dot entry dir.
For this example the var file is explicitly namedwofi_vars.toml but my_dot_dir/vars.toml would be automatically picked.
dotfiles/wofi
├── config
├── solarized.toml
├── style.css
└── wofi_vars.toml
Here we define variables that will only be resolved when rendering wofi template dots.
- Global vars defined under settings.vars will still be accessible in wofi dotfiles.
- Global vars defined under settings.vars will be overridden by colliding local variables.
toml
[settings.dots]
wofi = { source = "wofi", target = ".config/wofi", vars = "wofi_vars.toml" }
A common pattern to organize your themes and profiles would be to maintain a global variable file for each variant, and a corresponding local variable file for each dot entry :
```toml dotfilesdir = "mydotfiles"
[settings] vars = [ "themes/default.toml" ]
[settings.dots] wofi = { source = "wofi", target = ".config/wofi", vars = "wofi_vars.toml" }
[profiles.solarized]
vars = [ "themes/solarized.toml" ]
[[dots]]
wofi = { vars = "solarized.toml" } ```
As we saw Bombadil allows to define a default profile. For some programs you might want to set an alternate configuration.
Bombadil allow you two do this in several ways :
- overriding a dot entry source and/or target value.
- adding a new dot entry.
- adding new variables.
- overriding existing variable.
- adding hooks to the profile.
Let's say you are using maven for several java projects, some of them are open source, and some of them uses a corporate repository :
let's assume your dotfiles have the following structure :
shell script
~/bombadil-example
├── bombadil.toml
└── maven
├── settings.corporate.xml
└── settings.xml
Your bombadil config contains a single dot entry with an alternate profile :
```toml
dotfile_dir = "bombadil-example" [settings.dots] maven = { source = "maven/settings.xml", target = ".m2/settings.xml"}
[profiles.corporate.dots] maven = { source = "maven/settings.corporate.xml" } ```
When overriding a default dot entry under a new profile source and target property are optional,
the default profile value will be used if not specified. You can also define a new dot entry in which case source
and target are required.
If you now run bombadil link --help you should notice a new profile value is available :
``` USAGE: bombadil link
OPTIONS:
-p, --profiles
bombadil link would produce the following link :
shell script
❯ bombadil link
"/home/okno/dotfiles/.dots/maven/settings.xml" => "/home/okno/.m2/settings.xml"
Linking with the corporate profile would use the alternate source for .m2/settings.xml :
shell script
❯ bombadil link -p corporate
"/home/okno/dotfiles/.dots/maven/settings.corporate.xml" => "/home/okno/.m2/settings.xml"
Here is an example bombadil config :
shell script
~/bombadil-example
├── bashrc
├── bombadil.toml
├── java10-vars.toml
└── vars.toml
Adding or overriding variables can be done this way :
```toml
dotfile_dir = "bombadil-example" [settings] vars = [ "vars.toml" ]
[settings.dots] bashrc = { source = "bashrc", target = ".bashrc"}
[profiles.corporate] vars = [ "java10-vars.toml" ] ```
```shell script
export JAVAHOME=[javahome]
```
```shell script
java_home = "/etc/java-openjdk"
```
```shell script
java_home = "/etc/java10-openjdk"
```
Running bombadil link -p corporate would produce the following .bashrc :
shell script
export JAVA_HOME=/etc/java10-openjdk
To add hooks for a profile simply add them under the profiles.{profile_name} section. Note that the default ones will
always be run.
```toml
dotfile_dir = "bombadil-example" [settings] hooks = [ "echo \"default profile\"" ]
[profiles.corporate] hooks = [ "echo \"corporate profile\"" ] ```
If you use Wofi as a menu/launcher, you can run the user script
contrib/wofi-bombadil-switch-profile.sh.
Create a keyboard shortcut for this script to make switching Toml Bombadil profiles even more convenient.
So far we have not talked about hooks, as we saw they can be declared as an entry in the config :
toml
dotfiles_dir = "bombadil-example.toml"
[settings]
hooks = [ "sway reload" ]
This will invoke the sway reload command after bombadil link has updated your dotfiles.
The default hooks will always run regardless of the activated profiles. You can also add hooks for a specific profile.
```toml dotfiles_dir = "bombadil-example.toml"
[settings]
hooks = [ "sway reload", "echo 42" ]
[profiles.corporate]
corporatehooks = [ "echo \"Welcome to evil corp\"" ] ```
toml
hooks = [ "source /home/user/.zshrc" ] # This does not work !
toml
hooks = [ "echo $HOME" ] # This will print "$HOME"
toml
hooks = [ "zsh -c \"echo $HOME\"" ] # This works
As your dotfiles configuration grows bigger, it might be useful to split it into multiple files.
To achieve this you can use the [[import]] option in your bombadil config :
```toml
dotfiles_dir = "bombadil-example"
[settings] hooks = ["sway reload"]
[settings.dots] alacritty = { source = "alacritty", target = ".config/alacritty" } wofi = { source = "wofi", target = ".config/wofi" } sway = { source = "sway", target = ".config/sway" } waybar = { source = "waybar", target = ".config/waybar" }
[[import]] path = "bombadil-example/shell-config.toml" ```
Given the following imported file, both config will be merged before running any bombadil command.
```toml
[settings]
vars = [ "bombadil-example/vars.toml" ]
[settings.dots] zsh = { source = "zsh/zshrc", target = ".zshrc" } zsh_env = { source = "zsh/zshenv", target = ".zshenv" } starship = { source = "zsh/starship.toml", target = ".config/starhip.toml" } ```
If you'd like to remove all dotfile symlinks defined in your bombadil.toml configuration, simply run:
shell script
❯ bombadil unlink
Command line completion scripts for several popular shells can be generated by running bombadil generate-completions. An example for generating a completion script and outputting it to a file for zsh would be bombadil generate-completions zsh > <somewhere on your $fpath>/_bombadil. Available shells are: bash, elvish, fish, and zsh.
If you get lost you can use bombadil get {resource_name} to see what is currently configured.
Available resources are dots, hooks, path, profiles, vars, secrets.
Optionally you can display resources for a profile with the --profiles flag.
If you use Bombadil please submit an issue, or a PR to update this section, we will be happy to reference your dotfiles here !
Found a bug, have a suggestion for a new feature ? Please read the contribution guideline and submit an issue.
All the code in this repository is released under the MIT License, for more information take a look at the LICENSE file.