Dotfiles Part 1: A Simple Approach to storing Home Directory Config Files in Git without a Bare RepoJonathan Bowman Created: January 17, 2021 Updated: July 10, 2023 [Dev] #dotfiles #commandline #git
Configuration files that reside in your home directory are both precious and dynamic. Given this, storing them in a version control system like Git makes good sense. Due to concerns around complexity, security, and cleanliness, though, no one wants to manage all files in their home directory with version control. Let’s explore how to manage just the important configuration files, also known as “dotfiles”, by selectively committing only the desired files to version control.
Dotfiles? Because these files are often prefixed with a “.” (period, full stop, what have you), they are sometimes called “dotfiles.” Examples include
.vimrc, and so on. Of course, they may include any configuration file, dot or not, such as
In the approach detailed in this article, we make the home directory a git repo, then add and commit handpicked files, pushing and pulling from the remote repository as desired.
Just need a quick up-and-running approach? Please see the easy article. Also feel free to browse the whole series.
Feel free to read the full article for detailed explanation and options. As a quick summary, the following commands offer an introduction. (The url for your Git repo should be assigned to or substituted for the
# Execute/uncomment one of the following 3 lines unless a .gitignore with '/**' already exists in the repo # echo '/**' >> .git/info/exclude # echo '/**' >> .gitignore; git add -f .gitignore # If first-time push to empty repo, add and commit some files, then: # Otherwise, if this is first-time pull from non-empty repo
git add FILENAME (use
git add -f to force add if necessary, depending on which settings you chose above),
git push, and
git pull to your heart’s content.
For a more detailed exploration, please read on…
🔗Create or locate a remote Git repository
If you do not already have a Git repository, then you will want to create one before undertaking the steps described here.
You can create such a repository in the way you prefer. For instance, create a new repo on Github or Gitlab. Or BitBucket, CodeCommit, Codeberg, sourcehut, random ssh server… A private repository is safer than a public one, in case you accidentally or intentionally commit secrets or sensitive information. On the other hand, a public repository is far more convenient, as you don’t need to worry about authentication when first cloning. You decide.
Github has helpful instructions for creating a repo, and so does Gitlab.
You may also host a Git repository anywhere you like, such as another local directory (perhaps one that is synchronized with cloud storage somehow), or on your own server with SSH access. In both of these scenarios, you will initialize a bare remote repository with
git init --bare.
Once you have a remote Git repository that is empty, or already has your dotfiles in it, you can manage that repo from your home directory, with the methods described in this article.
Note: the commands in this article have been tested with the following shells: Bash, Zsh, Ash, and Powershell. Unless you have configured things differently (good for you), Linux users will probably use Bash, Windows users Powershell, and Mac users Zsh. Feel free to send me feedback if there are additional tweaks needed for other shells.
🔗Clone the Git repository
We will selectively manage dotfiles by making the entire home directory a git working directory, but ignore all files by default or disable tracking on files not already in the repo.
First, we clone the git repo in the home directory:
USERNAME is your Github username. Gitlab users would use
gitlab.com in place of
github.com. I use SSH, but if you prefer HTTPS, then the URL should look more like
https://github.com/USERNAME/dotfiles.git but with your username. Thankfully, both Github and Gitlab make it easy to copy the entire clone URL on the repository page. Other platforms should have a similar option.
The use of
--separate-git-dir .git takes some explanation. It is impossible to
git clone into a non-empty directory without some extra steps. This trick does it in one step (two if you count the deletion of the throwaway directory). Tell Git to use a separate Git directory but then we pull one over on git, and name the directory the default:
The unneeded but easily-removable directory
throwaway has a single
.git file of no consequence. The entire
throwaway directory can safely be removed.
There are three options for excluding the files that you don’t want in the repo. (You may also have heard of an approach involving setting up a bare Git repo in a separate directory, then pointing git to the home directory as a working directory. That is an option we explore in a separate article.)
🔗Option #1: disable status tracking of non-repo files
The first option, and my favorite, involves simply disabling status tracking on non-repo files. This way,
git status will not list all of the files you might add, but just the ones you already have chosen. This option assumes you can keep yourself from typing
git add . so as not to accidentally add every file in your home directory.
Note that this is necessary when creating a new repository, and also when checking out the repository for the first time on a new machine. In other words, this setting is not restored automatically when fetching the repo; it must be run manually at every first-time setup.
When using this option, add additional files with
git add FILENAME. Do not use
git add .
The second option is to use a
.gitignore file that ignores everything.
Of course, you are welcome to use the text editor of your choice.
.gitignore can then be included in your repository, so that when you clone it on another machine, the ignores will be checked out as well.
If you are choosing this option, and you are starting fresh with an empty repository, add the
.gitignore to the repo, and commit the change:
When using this option, add additional files by force-adding ignored files with
git add -f FILENAME. Another way is the two-step approach of first allowing the file in the
.gitignore, then either
git add FILENAME or
git add . See below for further explanation.
A third option, if you want to hide this away, and don’t mind an extra configuration step every time you clone the repo, is to place the exclude line in
Very clean, just a little more labor repetitive, as you will need to do it the first time you download your dotfiles to any new environment.
🔗Adding files with option #2 or #3
At this point, adding other files is possible. To add a
.bashrc file, for instance, it either needs to be force-added with
git add -f .bashrc or allowed in the
.gitignore with a
!/.bashrc line. This means do not (
! means “not”) ignore the file
/bashrc. Then you can add without forcing by simply using
git add .bashrc or even just
git add . to add every allowed file. My preference is to use the one-step process of force-adding rather than the two-step of adding to a file then adding again with git. So:
I should note some advantages/disadvantages of the one-step vs two-step approach: if you like typing
git add . and cannot keep yourself from doing so, then use the two-step approach: add a line including the filename in
.gitignore then use
git add . without fear. Easy, even if it is the two steps. But if you prefer the force method with
git add -f FILENAME then whatever you do, do not use
git add -f . as it will commit the entire contents of your home directory.
🔗Push to remote repository
Once files are committed to the local repo, we can set the upstream repo and push.
From this point on, since the upstream repo is now set, a simple
git push will upload your commits to the remote repository.
🔗Working with existing dotfiles
Once you have a remote repository populated with your dotfiles, these are the steps to download those to a new home directory:
First, repeat the above setup steps, making the same choices about how to exclude/include files. Something like this:
# Unless a .gitignore with '/**' already exists in the repo, # execute/uncomment one (not both) of # the following 2 lines # git config --local status.showUntrackedFiles no # echo '/**' >> .git/info/exclude
This might work; however, if there are already files in your home directory with the same name as in the remote repository, Git will complain and refuse to overwrite them. Review the files now, make backups if appropriate, then try again.
If you are OK with overwriting existing files, you may use the force (
-f) flag like so:
From this point on, you can
git add any files you want to track,
git commit to index those files,
git push to upload them to the remote repo, and
git pull to download any changes you may have made elsewhere.
You might wish to define shell functions for convenience. I use the following:
Or the Powershell equivalent:
dtfnew $REPO will set up a new repo ready to be populated and pushed to an empty remote repository.
dtfrestore $REPO will accept an already-populated remote repository URL, and pull the files into your home directory.
I suggest customizing the above functions as you like, then placing them in a Git repo or Github Gist or Gitlab Snippet. Assign $URL appropriately, then use something like:
The above works on Bash/Ash/Zsh, and even on Busybox-based distros. Feel free to try
For a Powershell example, try something like:
Set-ExecutionPolicy RemoteSigned -scope CurrentUser iwr -useb $URL | iex
For the above, feel free to try
$URL = "https://raw.githubusercontent.com/bowmanjd/dotfile-scripts/main/basic.ps1"
🔗Pros and cons of this approach
I like this approach because it leaves you with a repo that pretty much works the way repos are supposed to work. No need for extra
--work-tree options that the bare repo approach requires.
The only problem I see with this simplicity is that even when a subdirectory of your home directory is not configured as a git repo (with
git init or
git clone, for instance), it is considered a git repo.
In other words, if you start a new project and type
git status you will notice that your fresh project is automatically a part of a pre-existing Git working tree. Of course, type
git init or
git clone or what have you, and all is well. Once a
.git directory exists, then
git status will know not to refer to the home directory repo.
If this is a concern, you may wish to consider the bare repo approach, although it does add a layer of complexity.
🔗Adapt, customize, learn
Hopefully this gives you some ideas for managing your configurations, thereby making your life easier. Admittedly, there are many options along the way, including opportunities to simply learn Git better, considering how it might serve your needs. Feel free to send me feedback if you have creative ideas and thoughts!
Read additional articles on this topic, including modular approaches, for when some environments have both shared and distinct configurations from other environments. And, of course, the bare repo approach. Or explore chezmoi or yadm. So many possibilities.
Back to top