Dotfiles are an accessible, powerful way of configuring your Linux system. But how do you keep track of them all and reuse them when necessary? Try git.
What Are Dotfiles?
On Linux, any file whose name begins with a “.” is a hidden file. By default, it won’t show in your file manager or a file listing on the command line.
Some Linux programs use hidden files for configuration, often dumping them in your home directory. This is a useful setup because it keeps configuration out of the way while ensuring it’s still accessible. Since this configuration is in plain text files, it’s easy to read and edit. You can also use the Linux command-line toolset to work with your system’s configuration.
Common examples of dotfiles include:
- .bashrc, .zshrc
- .exrc
- .gitconfig
- .npmrc
How Can Git or GitHub Help?
Dotfiles are great, but they’re system-specific. When you need to replace your computer, use a secondary device, or access a remote server, you might find yourself setting things up all over again.
Storing your dotfiles in a VCS (Version Control System) can help you avoid this repetitive task, allowing you to instantly reuse your configuration on another machine. Just check out your repository and you’ll get the same shell aliases, familiar themes, and consistent behavior.
What’s more, storing dotfiles in git is a robust backup option. You can even inspect your repository’s history to discover when—and why—you changed specific configuration. In a collaborative setting, you might even share your dotfiles via git to ensure all team members have a consistent environment.
For this purpose, GitHub is the cream of the crop. If you have another place to host your git repository, you can certainly do that, but GitHub makes it a lot easier.
The Best Way of Managing Your Dotfiles With Git and GitHub
First, understand that any form of storing your dotfiles in git will be a major win. There are specific details on exactly the best way to do so, but if you can store a file in git, update it, and check it out, you will benefit significantly from managing your dotfiles this way.
However, the following approach is widely recommended online and it works for me. This particular setup should help you keep everything in sync with the least effort.
Set up a Bare Repository and Some Scaffolding
Since your home directory likely has a lot of stuff you don’t want in your dotfiles repository, it’s best to avoid a standard setup. Instead, you can manage your dotfiles in a bare repository.
A bare repository is like a normal repository without the actual project files. It has all the git metadata that describes the history of those files, it just doesn’t have the files themselves. The files can live elsewhere—in your work directory—you’ll just use the bare repository to version control them.
Start by creating a bare repository in a new location, for example:
mkdir $HOME/.dotfiles
git init --bare $HOME/.dotfiles
When you work with this repository, you’ll need to supply a working directory (for the files) and a git directory (for the repository itself):
git --work-tree=$HOME --git-dir=$HOME/.dotfiles ...
Rather than typing this each time you use git, it makes sense to set up an alias. You can also supply the path to the bare repository itself so you can use it from any directory:
alias dotfiles="/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME"
Store Your Dotfiles
Start by identifying a dotfile you want to version control.
You can then run these commands to start version controlling your .bashrc file, for example:
cd $HOME
dotfiles add .bashrc
dotfiles commit -m "Bash run control file"
Apart from using the dotfiles alias instead of the plain git command, you can use git to track these files just as you normally would. This approach is actually slightly easier because you can run a command like “dotfiles log” from any directory.
Upload Your Repository to GitHub
You may find it convenient to host your repository on a provider like GitHub. This can make it easier to share access to your dotfiles, especially from machines on a different network. It’s easy to do this, even with an existing repository:
- Start at the Create a New Repository page.
- Enter a Repository Name.
- Choose either a Public or Private repository; Private is probably best (see below).
- Click Create Repository.
At this point, you’ll be shown a screen with setup instructions. To push your existing repository, simply run these two commands:
dotfiles remote add origin https://github.com//.git
dotfiles push -u origin main
Where is your GitHub username and is the name you chose for your repository.
Be very careful about uploading your repo to GitHub: your dotfiles may contain sensitive data. Ideally, you should avoid committing files that contain passwords to any repository. If you can’t avoid it, consider at least using a private GitHub repository; you will need to pay for this, however.
Use on Another System
To share your dotfiles on another machine, you’ll need to repeat the above processes and check out the bare repository. In particular, this means there are two important steps. First, check out a bare copy of your repository:
cd $HOME
git clone --bare https://github.com//.git
This will typically check out into a directory named .git. Once checked out, you are free to rename this.
Recreate the git wrapper alias you’re using:
alias dotfiles="/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME"
You can now populate your working directory—your HOME—with your version-controlled dotfiles:
dotfiles checkout
At this point, you may see an error about overwriting working tree files. This is because you probably already have old or default dotfiles like .bashrc. Simply remove or move these, then repeat the checkout.
Version controlling your dotfiles will save a lot of hassle when you upgrade or switch systems. You’ll also be able to check a complete history and see when you changed what, and why.
