Dotfiles Part 3: A Modular Approach Using Multiple Git RepositoriesJonathan Bowman Created: February 04, 2021 Updated: July 10, 2023 [Dev] #dotfiles #commandline #git
In this article, I offer an approach for managing dotfiles in a modular way. I find a modular approach important because only some config files are useful in all contexts, while others are unique to a specific environment. For instance, my text editor configuration (
.vimrc, in my case) is used on my Windows laptop, Linux laptop, FreeBSD server, and even my phone. On the other hand, files for configuring a Linux graphical environment, a developer’s Macbook, Windows Subsystem for Linux (WSL), or Windows Powershell, may not make sense to clutter or confuse environments to which they do not apply.
It would be nice to use multiple Git repositories, or multiple branches of one Git repository, in order to customize various environments.
In a previous article, I outlined a simple approach to storing dotfiles that makes the entire home directory a git repository.
Let’s build on that approach, exploring the possibility of using multiple repositories in a modular fashion.
Feel free to browse the whole series if interested in exploring a variety of approaches.
Feel free to read the full article below for detailed explanation and options. As a quick summary, the following steps should get you started with three “modules”:
- Set up the base repo
- Create two additional directories, such as
~/.config/custom/workand initialize a git repo in each, similar to the base instructions but using those directories instead of home.
- Modularize your config files (see below) so that the main config includes related files in subdirectories of
- Manage the files:
cdinto each module directory and add, commit, push and pull as necessary
You can continue to use the convenience functions from the first article (
dtfrestore), just make sure you position yourself in the appropriate directory first, and specify the correct repo for each module. For example:
In the above, we first create a base repository in the home directory. This is the repo in which are stored the main files like
.profile, etc. As noted below, these files should be configured to load other files in other directories.
Then we clone the remote repositories to the given directories after creating them.
You can browse the companion Github repo for the basic functions used above, in both a Unix shell version and a Powershell version
🔗One directory per “module” with a common parent directory
Choose a parent directory in which you will place each module directory. I use the term “module” here to refer to a repository that adds additional config files. I do not mean to refer to git submodules. Although that introduces possibilities worth exploring another day…
~/.config/custom as the parent directory, but you can use any location that serves you well.
Underneath that parent directory, create a directory for each “module.” The end result may look something like this:
Perhaps you don’t need that many, but you get the idea.
Within each directory, you can place relevant config files. I suggest some advance planning to determine naming scheme, as follows.
🔗Modularize your config files as needed
The first step to a layered or modular approach is to think in modules. Rather than imagining a single config file that changes per system, use that file to load other config files if they are present.
Here are some ideas, specific to various tools:
🔗Unix shell configs
Shell configurations like
.profile can source files from other directories.
For instance, in
.bashrc we might place something like the following:
This would load any or all of the following files if they exist:
Include keyword can be used like so
For example, this will include any of the following files, if they are available:
Or a different
Include line to find files in other directories:
This will include any files ending in
.ssh (such as
config.ssh) in any subdirectory of
And so on. Name the directories in ways that suit you.
In Windows, the Powershell profile in
~\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 is automatically loaded. Within that file, you could loop through files in a directory of your choice and load them:
Get-ChildItem -Recurse "$HOME\.config\dotfiles\*.ps1" | ForEach-Object
For example, this will include the following files, if they are available:
With Vim or Neovim, you can place any vim script ending with
~/.vim/plugin of subdirectory thereof, and it will autoload. In Vim 8 and above, a more modern location is something like
~/.vim/pack/personal/start and so on.
You can also load multiple files from a directory of your choice, using the
runtime command. For instance, add something like the following to
This will load any and all files ending with
~/.config/dotfiles or any subdirectory thereof.
🔗Maintaining config files in module directories
The above are examples to demonstrate a theme: create base config files that simply load an arbitrary number of other files, in a directory of your choosing. Once this is done, individual files as well as directories of files can be added to Git repo(s).
As noted, this requires thinking through directory and file structure carefully, because files are tracked in entirely separate git directories. But that careful organization pays off with simplicity:
cd into the module directory, then use
git as you like, no extra command line options needed. For instance, imagine that we have two modules:
base being our main repo in
personal having an additional person Vim config in
~/.config/custom/personal/personal.vim. Initiating the tracking could look something like this:
🔗Other hints and recipes?
I hope this offers you some ideas and inspiration for your own configurations. Please feel free to send me feedback with suggestions and experiences.
View my entire dotfiles series for more exploration of the topic.
Back to top