Using Multiple Git Repositories to Store Dotfiles in a Modular Fashion
Tags: github, git, programming, productivity
Published: 2021-02-04 12:22:54

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][dotfiles1] 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.

## Summary steps

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": `base`, `personal`, and `work`:

1. [Set up the base repo][dotfiles1]
1. Create two additional directories, such as `~/.config/custom/personal` and `~/.config/custom/work` and initialize a git repo in each, similar to the base instructions but using those directories instead of home.
1. Modularize your config files (see below) so that the main config includes related files in subdirectories of `~/.config/custom`
1. Manage the files: `cd` into each module directory and add, commit, push and pull as necessary

## Repository setup

You can continue to use the convenience functions from [the first article][dotfiles1] (`dtfnew` and `dtfrestore`), just make sure you position yourself in the appropriate directory first, and specify the correct repo for each module. For example:

```sh
cd ~
dtfrestore $BASEREPO
mkdir ~/.config/custom
git clone $WORKREPO ~/.config/custom/work
git clone $LAPTOPREPO ~/.config/custom/laptop
```

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 `.bashrc`, `.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](https://github.com/bowmanjd/dotfile-scripts/) for the basic functions used above, in both a [Unix shell version](https://github.com/bowmanjd/dotfile-scripts/blob/main/basic.sh) and a [Powershell version](https://github.com/bowmanjd/dotfile-scripts/blob/main/basic.ps1)

## 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](https://git-scm.com/docs/gitsubmodules). Although that introduces possibilities worth exploring another day...

I use `~/.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:

```
~/.config/custom/
├── base
├── macbook
├── personal
├── server
├── work
└── wsl
```

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

An important strategy with a modular approach is to compartmentalize. 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 `.bashrc` or `.zsheenv` or `.profile` can source files from other directories.

For instance, in `.bashrc` we might place something like the following:

```sh
for file in "$(find $HOME/.config/custom -name 'bashrc')"; do . $file; done
```

This would load any or all of the following files if they exist:

```
~/.config/custom/work/bashrc
~/.config/custom/personal/bashrc
~/.config/custom/wsl/bashrc
~/.config/custom/linuxui/bashrc
```

### SSH configs

In `.ssh/config`, [the `Include` keyword](https://man.openbsd.org/ssh_config#Include) can be used like so

```
Include ~/.config/custom/*/*.ssh
```

This will include any files ending in `.ssh` (such as `config.ssh`) in any subdirectory of `~/.config/custom`. For example, this will include any of the following files, if they are available:

```
~/.config/custom/work/config.ssh
~/.config/custom/personal/personal.ssh
~/.config/custom/server/hosts.ssh
```

And so on. Name the directories in ways that suit you.

### Powershell

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:

```powershell
Get-ChildItem -Recurse "$HOME\.config\dotfiles\*.ps1" | ForEach-Object {& $_.FullName}
```

For example, this will include the following files, if they are available:

```
~\.config\dotfiles\dc1\profile.ps1
~\.config\dotfiles\work\profile.ps1
~\.config\dotfiles\personal\extra.ps1
```

### Vim

With Vim or Neovim, you can load multiple files from a directory of your choice, using the `runtime` command. For instance, add something like the following to `~/.vimrc`:

```vim
runtime! ../.config/custom/**/*.vim
```

This will load any and all files ending with `.vim` in `~/.config/custom` or any subdirectory thereof. Note that the directory path is relative to the vim runtime path (`$VIMRUNTIME`), hence the `..` at the beginning of the path.

## 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` and `personal`, with `base` being our main repo in `$HOME` and `personal` having an additional person Vim config in `~/.config/custom/personal/personal.vim`. Initiating the tracking could look something like this:

```sh
cd ~
git add ~/.vimrc
git commit -m "New Vim config"
git push
cd ~/.config/custom/personal
git add personal.vim
git commit -m "Addition Vim config for personal laptop"
git push
```

## Other hints and recipes?

I hope this offers you some ideas and inspiration for your own configurations. Please feel free to comment below with suggestions and experiences.

[dotfiles1]: https://www.bowmanjd.com/dotfiles/dotfiles-1-simple-no-bare-repo/
[dotfiles2]: https://www.bowmanjd.com/dotfiles/dotfiles-2-bare-repo/