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]" ... ```
And 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"
```
Bombadil maintain a pgp encrypted variable store called secret_store.gpg at the root of your dotfile directory.
This allows to safely commit encrypted secret on a public repository.
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 your bombadil config :
```toml dotfiledir = "bombadil-example" gpguser_id = "me@example.org"
[settings.dots] maven = { source = "maven/settings.xml", target = ".m2/settings.xml"} ```
Add secret variable :
bombadil add-secret -k "server_password" -v "hunter2"
Use the secret value in any dot entry :
xml
<server>
<id>my.server</id>
<username>Tom</username>
<password>__[server_password]__</password>
</server>
Relink your dotfile to inject the secret values in your dotfiles :
bombadil link
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 are the following :
shell script
~/bombadil-example
❯ tree
.
├── 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
❯ tree
.
├── 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
alway be run.
```toml
dotfile_dir = "bombadil-example" [settings] hooks = [ "echo \"default profile\"" ]
[profiles.corporate] hooks = [ "echo \"corporate profile\"" ] ```
So far we have no talked about hooks, as we saw they can be invoked 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 be 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 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.