dchaploeb's dotfiles

Welcome to my dotfiles repo. I use chezmoi to manage my home directory, synchronize application settings, and install packages on my computers. The goals here is to make setting up environments fast, easy, reproducible, and idempotent; to keep setups consistent between multiple environments whenever possible; and to facilitate a computing environment that is efficient for how I work!

This readme is both an explanation for others of some of what I've set up in this repo, and a reminder for me of how to use it!

Setting up a new environment

1. Make sure the environment has git, ssh, and the appropriate package manager. In particular, as of July 2025, new Windows 11 installs have a git that doesn't support ssh, so winget install Git.Git is necessary. And turning on Developer mode is necessary. (I think turning on Developer mode also sets the execution Policy correctly; if not do that too). Also July 2025, I happened to try to set up a subset of this environment on Windows server 2016 (and made some modifications to support that). It's a nice reminder of how far Windows has come-- a lot of the stuff I rely on routinely cannot be installed on Server 2016.
   Some rough notes on the setup I did for Server 2016 are in the repo; I may flesh them out in the future. The main thing that's different is that winget doesn't exist on Server 2016.
   I feel comfortable installing a few tools using scoop though...

2. Make an ssh key-- ssh-keygen-- and upload it to github

3. Install chezmoi and have it apply my dotfiles repository from github. This installs a set of packages, which depend on the OS I'm running on. (The "installing the right set of packages" part is a work in progress, as discussed below).

   In Linux: sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply git@github.com:dchaploeb/dotfiles.git

   or in powershell: iex "&{$(irm 'https://get.chezmoi.io/ps1')} -- init --apply git@github.com:dchaploeb/dotfiles.git" (TODO: test this; it didn't work last time I tried it but I think I had the quotes in the wrong place.)

4. For some environments, we may be done! But if we want applications installed, tweak settings in .chezmoi.toml.tmpl to specify which sets of packages chezmoi should install. If anything was changed, run chezmoi apply again to install them.

5. Install packages manually if needed. Right now, some of the packages get installed by running scripts which live in bin/ and some packages I use regularly aren't supported by my cheezmoi apply workflow yet.
   I try not to install anything with a gui installer-- as noted, I want reproducible processes, and downloading an installer and double clicking on it is not that! So the goal is that this step eventually doesn't exist. (syncthing is currently a semi-manual setup)

6. Set up additional sync services. There are too many of these. I keep trying to consolidate down but each service has benefits and limitations. syncthing is a recent addition to this and may end up replacing some of the cloud services.

   1. syncthing
   2. Proton Drive
   3. vscode sync
   4. Obsidian sync
   5. Brave sync
   6. iCloud
   7. Google Drive.
   8. OneDrive

That's it! Everything I need is installed, my data is synced and configured the way I like it at this point. Of course, steps 5 and 6 still involve some manual work, but it's a lot less than was needed in the past.

chezmoi workflow

This is how I use chezmoi.

I have auto-commit and auto-push turned on. Both zsh and powershell are set to run chezmoi update and chezmoi apply at login. After editing a dotfile in my home directory or changing settings that I want to keep synced, I run chezmoi re-add, which picks up the change, commits it, and pushes it to github.

Editorial comment: chezmoi re-add turns out to be the command that makes chezmoi really a time-saver for me. When I read people complaining about chezmoi on the web, it's the process of editing files in the chezmoi directory rather than where they're being used that turns people off. For the most part, you don't have to do this. Edit files that have been added to chezmoi in-place, then run chezmoi re-add.

For dotfiles, the exception to this is files generated by chezmoi templates. If you're using this feature, changing those files means editing the templates in the chezmoi directory. This is a tradeoff-- the template allows me to maintain one file which modifies itself based on environment, but in order to make that work I have to edit the template rather than the real file. If a file needs this treatment, use chezmoi add --template to convert it to a template.

And of course, chezmoi scripts and config files live in the chezmoi directory and get edited there.

For easy access to scripts and templates, I have chezmoi create a symlink at ~/chezmoi pointing to ~/.local/share/chezmoi. This allows me to easily switch to the directory, or open it in vscode with code chezmoi

After editing stuff in the chezmoi directory, I still just run chezmoi re-add and that triggers chezmoi to commit and push my changes.

I don't currently use chezmoi's password manager integration, though it looks pretty neat.

Functionality (and desired functionality)

Dotfiles, Profiles, and Preferences

• ✅ Sync .gitconfig
• ✅ Sync zsh dotfiles
• ✅ Sync powershell profile: The Powershell profile installs to all of the places it might be needed (4 of them, at the moment; there will be one more if I start using pwsh on linux). Because this multi-install makes running the actual $PROFILE file awkward, I now use a profile directory and run everything in it, which honestly seems better anyway. In the rare event that I need to edit the actual profile script, the editable version of that lives at ~/chezmoi/.chezmoitemplates/Microsoft.PowerShell_profile.ps1.tmpl
• ✅ Sync Windows Terminal Settings
• ✅ Sync icons for use with windows terminal.
• ✅ Sync my custom retrobar theme and settings on Windows
• TODO: set editor to something other than code on systems accessed via ssh

Scripts and aliases

• ✅ On windows, my defines a unix-like ls function and a useful Add-ToPath function
• ✅ Python convert_png_to_ico.py (works!)
• TODO: More to come from dev environments.

Package management

Controlled by .chezmoi.toml.tmpl and .chezmoidata/packages.yaml

• ✅ Install needed packages on linux
• ✅ Install zsh and set it to be my shell.
• ✅ Install scoop and my favorite Nerd font
• ✅ Install Nuget and the Winget Powershell module
• ✅ Winget Package installation is in something like a final form.
• Unfortunately I need a fresh computer to test changes to this, so it tends to be a little while between updates. But I am closer to something I feel comfortable running on a computer that is not just going to be mine-- the default config installs some basic CLI tools and nothing else, and should do most of its work under the user it runs as.
• TODO: move some application installs to scoop instead of winget so they are installed for the current user rather than system-wide. Probably some of the apps I use are going to require an administrative login, but I'd like to minimize this, and eliminate it entirely on the smaller group of apps I install on computers that aren't mine.
• scoop could also be used to install CLI tools on older Windows servers, where winget is not available.

Start Menus, bars, launchers, and Web Shortcuts (on Windows)

• ✅ Sync Retrobar theme and prefs
• ✅ Sync yasb theme and prefs
• ✅ Make sure Brave Profiles exist with appropriate names
• ✅ Build and install Web shortcuts
• TODO: Something's still glitchy with the initial setup of web shortcuts.
• TODO: Window management tool prefs, once I have a stable configuration

Web shortcuts are controlled by .chezmoidata/braveapps.yaml and run_onchange_setup-brave-shortcuts.ps1.tmpl; it depends on Python, the PIL library, and the bin/convert_png_to_ico.py script (all of which are installed by my dotfiles, but since I don't imagine anyone else will be using my whole set of dotfiles...)

The web shortcuts feature is my favorite thing in here and deserves some comment:

I make pretty heavy use of Brave Browser's "application" shortcuts, which install into the start menu. (You could do something similar with any chromium-based browser). But those "applications" aren't easily syncable between computers, nor is there a simple way to script making the browser create them. So I created an alternative.

(It would be nice if my alternative worked in any desktop environment, but that's a distant TODO. For now I'm constructing Windows shortcuts.)

This is working now; the system will build shortcuts for me based on a config file and put them in a start menu folder, updating them as needed. Still some tweaks to this to come, but it's a working feature (and should be adaptable to any Chromium-based browser that supports application shortcuts).

This now also creates the Brave profiles if needed. It does something unsupported to make this work-- it edits the Brave "LocalState" file in a minor way. If someone can suggest a supported way to make sure that a profile with a particular name exists on a newly-installed system without creating it manually, I'm all ears.