My Tooling - Part 2 - Setting up dotfiles manager

Table of Contents

[Subtitle] For a software developer, just like chefs or artists, their setup/tools are an extension of their personal expression.

Its not just business, but very much personal !!!

• • •

Context #

Every developer is an artist, whose creations depend a lot on their tools and setup. It enables them to transform their ideas and manifest not just as functional, but a things of beauty.

Here, I will be sharing the my dev-setup tech tooling, that I love and keep tinkering with - I guess it will exist as a continuous work-in-progress.

Part 1 : My Tooling - Part 1 - Securing a new dev box

Part 2 : My Tooling - Part 2 - Setting up my dotfiles manager

Part 3 : My Tooling - Part 3 - Installing my apps and packages

• • •

Setting up my dotfiles manager #

(As of now, I will be focusing on MacOS Device, but will update as I venture into using Linux/Windows as my dev machines)

To automate managing my dotfiles, I depend on Chezmoi.

But, first, let’s a take step back and state the obvious, “What are dotfiles?” and “Why should anyone care?”

What are dotfiles? #

Dotfiles are configuration files for various programs that help manage their functionality. They are named “dotfiles” because each file and directory starts with a dot (.). On Unix-based systems, dotfiles are hidden by the Operating System by default.

These files control the settings and preferences for applications and your system environment. They can include scripts, aliases, functions, and more that you can use to customize your shell and applications on macOS, Linux, and Windows.

Dotfiles are very important as they backup, restore, and sync the preferences and settings for your toolbox.

Why should a developer care about dotfiles? #

Becasue

Customization and Productivity: Developers spend a significant amount of time tweaking and optimizing settings that best suit their workflow and preferences. Dotfiles provide a way to customize your system to your liking and setup scripts and whatever to making their machine more organized and primed to help make them more productive.
Consistency: Dotfiles provide a consistent environment across not only reboots, but also different machines, in case one frequently switches between different systems.
Backup and Restore: Dotfiles can be used to backup your configuration settings. If your system crashes or if you switch to a new machine, you can easily restore your settings.
Shareability: Dotfiles are easily shareable and reusable by other people.

In summary, the time invested in creating and maintaining your dotfiles will reward you many times over during your development work.

• • •

Chezmoi #

Pronounced as “shay-mwa” (french word)

The WHAT? #

Chezmoi offers a robust, secure, and efficient way to manage dotfiles (configuration files for tools and applications) across multiple machines and operating systems, providing both consistency and customization where needed.

It uses a version-controlled source directory to keep track of changes and apply them to any number of systems.

Chezmoi is particularly adept at handling situations where configuration needs to differ slightly between machines, thanks to its support for templating and scripting within dotfiles.

For more details, see What is Chezmoi?

The WHY? #

Cross-Platform Consistency: Chezmoi works on macOS, Linux, and Windows, making it an ideal tool for users who work across different operating systems but want to maintain a consistent working environment.
Secure and Private: It has built-in support for securely managing secrets (like API keys or passwords) within your dotfiles, ensuring sensitive information is safely handled.
Version Control Integration: Chezmoi is built to work with version control systems like Git, making it easy to track changes to your dotfiles, share them across machines, and even collaborate with others.
Customization and Flexibility: Through templating, Chezmoi allows you to have base configurations that can be customized per machine or environment without duplicating effort. This is particularly useful for settings that need to be slightly different on a work computer versus a personal one.
Simplicity and Automation: Chezmoi simplifies the process of setting up a new machine to your preferences. With a single command, you can have all your familiar tools and configurations ready to go, automating what would otherwise be a manual and error-prone process.
Idempotency: Chezmoi’s operations are idempotent, meaning you can reapply your configurations multiple times without worrying about creating duplicate entries or unintended side effects. This makes it safe and predictable to use.

For more info, see

ALERT!!
Use Chezmoi commands as much as possible, and resist the temptation to using git or other seemingly equivalent commands ... as they are not the same.

Chezmoi commands does extra book keeping and that is needed to keep the configuration system healthy and working as expected.

• • •

The HOW? #

Here is a common usage workflow of Chezmoi

Installation
First, you need to install Chezmoi. This can be done via various package managers or by downloading a binary directly. For example, on macOS with Homebrew:
```
brew install chezmoi
```
First time initialization
Initialize Chezmoi for the first time. This will create a Chezmoi source directory where your dotfiles and scripts will be stored.
```
chezmoi init
```
Adding Dotfiles
Add your existing dotfiles to the Chezmoi source directory (~/.local/share/chezmoi). Chezmoi will track these files and manage their deployment to your home directory.
```
chezmoi add ~/.bashrc
chezmoi add ~/.vimrc
```
Dealing with symlinks
If an existing dotfile in home folder is a symlink, if you chezmoi add such a symlink, chezmoi will add the symlink, not the file. To assist with migrating from symlink-based systems, use the --follow option to chezmoi add - see Migrate from a dotfile manager that uses symlinks
Adding files from sub-folders of home diectory
To add files that are in subfolders of your home folder, you can use the --exact flag with chezmoi add to indicate that the file’s full path should be preserved. To this, Chezmoi creates a path within the source directory that mirrors the file’s intended path with each folder getting a prefix of exact_.
For example
```
$ chezmoi add --exact ~/subfolder1/subfolder2/config
```
It results in ~/.local/share/chezmoi/exact_subfolder1/exact_subfolder2/config (note: ~/.local/share/chezmoi is Chezmoi source directory)
NOTE: One can also use Chezmoi to manage files outside of user folder (say /etc/ssl/openssl.cnf). But it is an involved process.
Managing File Permissions
Chezmoi can also manage file permissions. When you add a file with Chezmoi, it records the file’s permissions in the source state file (chezmoistate.boltdb by default). When Chezmoi applies the file, it sets the permissions to match the recorded state.
You can manually specify permissions when adding a file using the --chmod flag:
```
chezmoi add --chmod=644 /path/to/your/file
```
Or, for files already managed by Chezmoi, you can modify permissions directly in the source directory’s filename. For example, to set a script to be executable:
```
chmod +x ~/.local/share/chezmoi/path/to/your/script
chezmoi add ~/.local/share/chezmoi/path/to/your/script
```
How/Where does Chezmoi store File Attributes
Chezmoi stores file attributes, including permissions, in the source state file (chezmoistate.boltdb). This database includes metadata about each managed file, such as its permissions and whether it’s a template or an encrypted file. For version 1.x of Chezmoi, this information was stored in the filename itself (e.g., executable_, private_ prefixes), but Chezmoi version 2.x uses the state file for a cleaner and more flexible approach.

Initial Commit

Once all the files

git remote add origin git@github.com:your-awesome-username/dotfiles-branchname.git 
git branch -M main

Editing Dotfiles
Edit your dotfiles directly through Chezmoi. This ensures changes are made in the source directory (~/.local/share/chezmoi) and can be applied or pushed to your repository.
```
chezmoi edit ~/.bashrc
```
The editor used will be based on
- Chezmoi being configured to use a specific editor by setting the edit.command variable in the chezmoi configuration file (~/.config/chezmoi/chezmoi.toml).
  
  For example, to use VSCode, you can add the following lines to the chezmoi configuration file:
```
[edit]
    command = "code"
    args = ["--wait"]
```
- If above doesn’t apply, Chezmoi opens the default editor set by the user (based on $VISUAL or $EDITOR env variables).
- If neither of the above apply, it falls back to a default editor depending on your operating system (vi on UNIX-like operating systems, notepad.exe on Windows)
Applying Changes
After making changes using previous step, apply the changes to your home directory. This makes the current state of the Chezmoi source directory (~/.local/share/chezmoi) reflected in your actual dotfiles (home folder)
```
chezmoi apply
```
Committing Changes
After making and verifying the changes, commit them to your dotfiles repository. This involves using Git commands within the Chezmoi source directory.
```
chezmoi cd
git add .
git commit -S -m "Update dotfiles"
git push
```
Non-first initializations (on a new machine where we want to use existing Chezmoi config)
If you already have a dotfiles repository on github, Chezmoi can clone it for you and initialize with it:
```
chezmoi init <your-git-repo-url>
```
Besides official <your-git-repo-url>, Chezmoi also takes a few simpler patterns (like <github-username>/<github-repository-name>) and tries to guess the github repo link from it, for example. For more details of all patterns allowed, see Chezmoi docs for init command.
Updating (pulling) changes to configuration files (Dotfiles etc.) from remote repo
To pull and apply changes from your dotfiles repository to another machine, use:
```
chezmoi update
```
Just to have a better understanding, chezmoi update command triggers git pull --autostash --rebase --recurse-submodules besides other book keeping activities.
Managing Secrets
For managing secrets (like API keys or passwords), Chezmoi integrates with many of the commonly used password managers. See https://www.chezmoi.io/user-guide/password-managers/
Script Execution
Chezmoi allows you to run scripts automatically during the apply process. Scripts prefixed with run_once_ are executed only once, while those with run_ can be executed every time.
```
chezmoi add ~/.local/share/chezmoi/run_once_setup-script.sh
```
Reapplying or Forcing Scripts
If you need to reapply all changes or force the re-execution of run_once_ scripts:
```
chezmoi apply --force
```
This workflow covers the basics of getting started with Chezmoi, managing your dotfiles, and keeping them synchronized across multiple machines. Chezmoi’s documentation provides more detailed information on advanced features and configurations to tailor its behavior to your needs.

Resources

────── 〔✿〕──────
──────────── 〔✿〕────────────