How do you handle your dotfiles that lie in multiple servers that you administer or support? Be it the .bashrc or .zshrc that contain your precious aliases and other useful settings to other myriads of dotfiles that make your work easier or worth it, you agree that it immediately becomes tedious to be creating them every time you move to a new environment or when you have new workloads (servers) in your cluster. This guide bears good news for all of those who are in need of something that will take the pain of creating them over and over away.

With Chezmoi, you have the opportunity of managing your dotfiles across multiple machines in a well ordered, presentable and secure fashion. You will be able to manage configuration files across multiple machines, for example your personal macOS laptop, your work Ubuntu desktop, and your work Linux laptop. And we take a deep dive into this miracle of a tool and make sure that your dotfiles will no longer be a thorn in the flesh of your work. We shall therefore install and see how Chezmoi does the work it has been tasked and burdened with to accomplish.

Chezmoi’s key features

Chezmoi gets lots of your dot files problems solved with the following features:

  • Flexibility: You can share as much configuration across machines as you want, while still being able to control machine-specific details.
  • Personal and security: You can use the version control system of your choice to manage your configuration, and you can write the configuration file in the format of your choice. chezmoi can retrieve secrets from 1Password, Bitwarden, gopass, KeePassXC, LastPass, pass, Vault, Keychain, Keyring, or any command-line utility of your choice.
  • Transparency: chezmoi includes verbose and dry run modes so you can review exactly what changes it will make to your home directory before making them.
  • It is declarative and robust: You declare the desired state of files, directories, and symbolic links in your source of truth and chezmoi updates your home directory to match that state.
  • It is fast and easy to use: chezmoi runs in fractions of a second and makes most day-to-day operations one line commands, including installation, initialization, and keeping your machines up-to-date

Please note that you need a Git account and repo in any Git system you prefer (GitLab, GitHub, BitBucket etc)

Before that, it is worth noting that Chezmoi can be installed using various ways as it has been documented on their GitHub page

Install Chezmoi on various Linux Distributions

Before installing chezmoi, it is prudent to first update your system and install git.

###Install git on Centos###
sudo yum -y install git

###Install git on Ubuntu###
sudo apt install git -y

###Install git on Arch Linux###
sudo pacman -S git

Chezmoi can be installed in various Linux distributions as follows.

Install on Alpine Linux

apk add chezmoi

Install on Arch Linux

sudo pacman -S chezmoi

Install on Guix Linux

guix install chezmoi

Install on NixOS Linux

nix-env -i chezmoi

Install on Void Linux

xbps-install -S chezmoi

Install Chezmoi on macOS

Get Chezmoi installed on macOS using Homebrew as follows

brew install chezmoi

Install Chezmoi using One-line binary

Another option to install chezmoi is by using the One-line binary. This way the correct binary for your operating system and architecture will be installed in ./bin with a single command.

cd ~
curl -sfL | sh
sudo cp -r ~/bin/chezmoi /usr/local/bin 

Getting Chezmoi to Work

From its documentation, chezmoi stores the desired state of your dotfiles in the directory ~/.local/share/chezmoi. When you run chezmoi apply, chezmoi calculates the desired contents and permissions for each dotfile and then makes any changes necessary so that your dotfiles match that state.

To start using chezmoi, we will have to initialize it as follows:

$ chezmoi init

Initialized empty Git repository in /home/tech/.local/share/chezmoi/.git/

This will create a new git repository in ~/.local/share/chezmoi with permissions 0700 where chezmoi will store the source state. chezmoi only modifies files in the working copy. It is your responsibility to commit changes.

In case you already have dotfiles that you would wish to “onboard” to chezmoi, you can manage that with the following chezmoi command

chezmoi add ~/.zshrc

Doing that will copy ~/.zshrc to ~/.local/share/chezmoi/dot_bashrc. If you want to add a whole folder to chezmoi, you have to add the -r argument/switch after add.

After adding your file to chezmoi, you can edit the source state of a file like so:

chezmoi edit ~/.zshrc

This will open ~/.local/share/chezmoi/dot_zshrc in your $EDITOR. For me, it will open the file using vi editor since that is the default editor. You can change this by editing what $EDITOR environment variable points to. Make some changes and save them.

A good thing about chezmoi is that you can see what changes chezmoi would make before saving the file like this:

chezmoi diff

Once you are satisfied with the edits, you can apply the changes as follows:

chezmoi -v apply

Finally, open a shell in the source directory, commit your changes to the local git repository and exit. Issuing “chezmoi cd” navigates you to ~/.local/share/chezmoi directory.

chezmoi cd
git add dot_zshrc
git commit -m "Add .zshrc"

Create a configuration file

chezmoi init” can create a config file automatically, if one does not already exist. In your repository cerate a file called “.chezmoi.<format>.tmpl” where format is one of the supported config file formats (e.g. json, toml, or yaml) then chezmoi init will execute that template to generate your initial config file as follows. Kindly choose one file format that you prefer.

$ chezmoi cd

##For toml file format##
touch .chezmoi.toml.tmpl 

##For json file format##
touch .chezmoi.json.tmpl

##For yaml file format##
touch .chezmoi.yaml.tmpl

After creating the file, run chezmoi init to create “~/.config/chezmoi/chezmoi.toml” config file. Note that the extension will change depending on the file format you chose above.

chezmoi init

Using chezmoi across multiple machines

In order to access your local dotfiles on different computers, we need to have a central place where your files are kept. Chezmoi works with Git. Proceed to clone the git repo in ~/.local/share/chezmoi to a hosted Git service for example GitHub, GitLab, or BitBucket.

chezmoi cd
git init
git commit -m "dotfiles commit"
git branch -M main
git remote add origin
git push -u origin main

You can call your repository any name but many people prefer calling their dotfiles repos dotfiles. From there, setup chezmoi in a separate computer as it has been covered in the previous steps then clone your git repo as follows:

Note: You must have created a repository with a name of your choice such as dotfiles.

$ chezmoi init

Cloning into '/home/tech/.local/share/chezmoi'...
Username for '': <your-username> 
Password for 'https://<your-username>': 
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.

This will check out the repo and any submodules and optionally create a chezmoi config file for you. It won’t make any changes to your home directory until you run:

chezmoi apply

Alternatively, you can pull the latest changes from your repository and see what would change, without actually applying the changes by running:

chezmoi source pull -- --rebase && chezmoi diff

This command runs git pull –rebase in your source directory and chezmoi diff then shows the difference between the target state computed from your source directory and the actual state.

Once you make any changes on the git repository files, you can login to any of your machine, pull and apply the latest changes from your repo with the following command:

chezmoi update

And with that, it is now simple to have all of your dotfiles in any machine you wish to have them on. No more writing new dotfiles in each new machine you find yourself in. Your work should now be as simple as typing chezmoi commands.

Use Bitwarden to keep your secrets

chezmoi includes support for Bitwarden using the Bitwarden CLI to expose data as a template function. If you do not have Bitwarden installed, you can use Snapcraft to get it installed easily. Also, you must have a Bitwarden account to be able to use their services.

Install Bitwarden CLI using snap or npm as follows

$ sudo snap install bw

##or using npm##

$ npm install -g @bitwarden/cli

Then you can login to your account

$ bw login                                                                                                    
? Email address: <your-email-address>
? Master password: [hidden]
You are logged in!

Unlock your Bitwarden vault:

bw unlock

Set the BW_SESSION environment variable, as instructed.

###For Linux###SSS
export BW_SESSION="2cvamm4lAfeH+Ztlsdtwerhwrtjwt3qEbTqsdfasgry36ceIuY7/lfC1pVS7esIHDFoITq7DIy3V3xTpFK=="

###For PowerShell###

The structured data from “bw get” is available as the bitwarden template function in your config files, for example:

username = {{ (bitwarden "item" "GeeksAdmin").login.username }}
password = {{ (bitwarden "item" "StrongPassword").login.password }}

Concluding Remarks

What we have covered thus far in the guide is just a drop in the sea. With Chezmoi, you can use your favorite password security tools like Bitwarden, gopass and KeePassXC among others to secure your most private dotfiles. For a deeper look into what chezmoi can do, view their detailed how-to guide and get to experience more features that this amazing tool can offer.

Your support is our everlasting motivation,
that cup of coffee is what keeps us going!

As we continue to grow, we would wish to reach and impact more people who visit and take advantage of the guides we have on our blog. This is a big task for us and we are so far extremely grateful for the kind people who have shown amazing support for our work over the time we have been online.

Thank You for your support as we work to give you the best of guides and articles. Click below to buy us a coffee.


Please enter your comment!
Please enter your name here