Dotfiles Part 1: A Simple Approach to storing Home Directory Config Files in Git without a Bare Repo

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 .bashrc, .zshenv, .vimrc, and so on. Of course, they may include any configuration file, dot or not, such as Documents/WindowsPowerShell/Microsoft.PowerShell_profile.ps1 or pyproject.toml or Library/Application Support/Code/User/settings.json.

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.

🔗Summary commands

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 $REPO variable.)

cd $HOME
git clone -n --separate-git-dir .git $REPO throwaway
rm -r throwaway

# Execute/uncomment one of the following 3 lines unless a .gitignore with '/**' already exists in the repo
git config --local status.showUntrackedFiles no
# echo '/**' >> .git/info/exclude
# echo '/**' >> .gitignore; git add -f .gitignore

# If first-time push to empty repo, add and commit some files, then:
git push -u origin HEAD

# Otherwise, if this is first-time pull from non-empty repo
git checkout

Now git add FILENAME (use git add -f to force add if necessary, depending on which settings you chose above), git commit, 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:

cd $HOME
git clone -n --separate-git-dir .git [email protected]:USERNAME/dotfiles.git throwaway
rm -r throwaway

Where 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: .git

The unneeded but easily-removable directory throwaway has a single .git file of no consequence. The entire throwaway directory can safely be removed.

🔗Preliminary setup

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.

git config --local status.showUntrackedFiles no

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 .

🔗Option #2: .gitignore

The second option is to use a .gitignore file that ignores everything.

echo '/**' >> ~/.gitignore

Of course, you are welcome to use the text editor of your choice.

This .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:

git add ~/.gitignore
git commit -m "feat: Initial commit and .gitignore"

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.

🔗Option #3: .git/info/exclude

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 ~/.git/info/exclude instead:

echo '/**' >> ~/.git/info/exclude

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:

git add -f ~/.bashrc
git commit -m "feat: added Bash config"

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.

git push -u origin HEAD

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:

cd $HOME
git clone -n --separate-git-dir .git $REPO throwaway
rm -r throwaway

# 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

Then,

git checkout

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:

git checkout -f

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.

🔗Convenience functions

You might wish to define shell functions for convenience. I use the following:

dtf () {
   git -C "$HOME" "$@"
}

dtfclone () {
    REPO="$1"
    DISPOSABLE=$(mktemp -dt dtf-XXXXXX)
    git clone -n --separate-git-dir "$HOME/.git" $REPO $DISPOSABLE
    rm -rf $DISPOSABLE

    # Uncomment one of the following 3 lines
    dtf config --local status.showUntrackedFiles no
    # echo '/**' >> "$HOME/.git/info/exclude"
    # echo '/**' >> "$HOME/.gitignore"; git add -f "$HOME/.gitignore"
}

dtfnew () {
    REPO="$1"
    dtfclone "$REPO"

    echo "Please add and commit additional files, then run"
    echo "git push -u origin HEAD"
}

dtfrestore () {
    REPO="$1"
    dtfclone "$REPO"
    dtf checkout || echo -e "Deal with conflicting files, then run (possibly with -f flag if you are OK with overwriting)\ngit checkout"
}

Or the Powershell equivalent:

function dtf {
    git -C "$HOME" @Args
}

function dtfclone {
    Param ([string]$repo)
    $tmpdir = [System.IO.Path]::GetTempPath()
    [string] $tmpname = [System.Guid]::NewGuid()
    $disposable = Join-Path $tmpdir $tmpname
    git clone -n --separate-git-dir "$HOME/.git" $repo $disposable
    Remove-Item -Recurse -Force $disposable

    # Uncomment one of the following 3 lines
    dtf config --local status.showUntrackedFiles no
    # echo '/**' >> "$HOME/.git/info/exclude"
    # echo '/**' >> "$HOME/.gitignore"; git add -f "$HOME/.gitignore"
}

function dtfnew {
    Param ([string]$repo)
    dtfclone $repo

    echo "Please add and commit additional files, then run"
    echo "git push -u origin HEAD"
}

function dtfrestore {
    Param ([string]$repo)
    dtfclone $repo

    dtf checkout
    if ($LASTEXITCODE) {
        echo "Deal with conflicting files, then run (possibly with -f flag if you are OK with overwriting)"
        echo "git checkout"
    }
}

The function dtfnew $REPO will set up a new repo ready to be populated and pushed to an empty remote repository.

The function 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:

OUT="$(mktemp)"; wget -q -O - $URL > $OUT; . $OUT

The above works on Bash/Ash/Zsh, and even on Busybox-based distros. Feel free to try URL="https://raw.githubusercontent.com/bowmanjd/dotfile-scripts/main/basic.sh"

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 --git-dir or --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