April 21, 2015


By Drew Barontini

Firstly, what are “dotfiles”? Well, dotfiles is a name used to denote a set of configuration files (generally hidden ones with a . before the filename) that are used to set up and configure various applications and settings, such as:

  • Bash
  • Git
  • Vim
  • Sublime Text
  • OS X
  • Ruby
  • & more

Why use dotfiles?

Here are a few reasons we should have our dotfiles set up properly:


It’s useful to keep “dotfiles” organized in a single location in order to easily edit and update our configuration files. Instead of being scattered across our Home directory, they are neatly organized in a curated directory structure that we can continually refine.


With our dotfiles in a source code management system like GitHub, we can easily share configuration settings with others. Not only will this help others improve their dotfiles, but it will also improve ours, should others see areas where they can suggest improvement.


If disaster strikes and we lose data on our machine, we can just pull down our dotfiles to restore important configuration settings. Additionally, setup tasks can be built into dotfiles to automatically update configuration settings across a machine. Personally, I’m a lot less hesitant to do a fresh install on my computer knowing that I can easily set up the tedious configuration files in an efficient and effective manner.

Setting up the dotfiles

Okay, so how do we set up our dotfiles? Well, we should first survey our ~ root user directory in the Terminal.

I’m going to base this setup on Mac OS X, but the process should be similar in other environments.

In the shell, run the following:

cd ~
ls -A | grep '^\.'

This will print out all of the files in our Home directory that are hidden, or those files which have a . to begin the filename. Doing so will help us to identify which sort of configuration files we have in our local environment.

Since the process is relatively the same, we will just set up Bash in our dotfiles. The same process can be applied to other configuration files.

1. Create a “.dotfiles” directory

First, create a directory called “.dotfiles” (the . is important because we want the directory to be hidden by default) in your ~ root Home directory.

cd ~
mkdir .dotfiles

Next, move into that directory and create a bash subdirectory.

cd .dotfiles
mkdir bash

2. Copy file contents

Now, we will want to copy the contents of the intended configuration file. The file we want to copy is ~/.bash_profile (the file used by the Terminal to configure your shell environment on OS X).

  • Open up the file and copy the contents (or run cat ~/.bash_profile | pbcopy in the Terminal).
  • Next, create a file within ~/.dotfiles/bash/ of the same name, but without the . in the filename (~/.dotfiles/bash/bash_profile).
cd ~/.dotfiles/bash
touch bash_profile

3. Remove original file

Now that we’ve copied the original file’s contents into the newly created file in our dotfiles, we can then remove the original file at ~/.bash_profile.

rm ~/.bash_profile

Make sure that you have copied the file’s contents before removing the original file.

4. Create symlink

In computing, a symbolic link (also symlink or soft link) is a special type of file that contains a reference to another file or directory in the form of an absolute or relative path and that affects pathname resolution. – Wikipedia

Next, we need to create a symlink that uses our dotfiles’ bash_profile file in the place of the original file, which is the location the filesystem is expecting.

ln -s ~/.dotfiles/bash/bash_profile ~/.bash_profile

In order to verify this worked, run the following in the shell:

cd ~
ls -la | grep .-\>

You should see the .bash_profile file with an arrow (->) pointing to the location of the file within your dotfiles.

With this symbolic link created, everything should work as it did before, but now our dotfiles are in an easy-to-edit location. However, this isn’t useful until we have it properly version controlled.

5. Version control

The final step is to create a Git repository within our ‘dotfiles’ directory, and then create and push it to GitHub (or similar service).

cd ~/.dotfiles
git init
git add .
git commit -m 'Initial commit'

Create the repository on GitHub and then push. Simple as that.

That’s All, Folks

That’s all there is to setting up your version-controlled dotfiles. Now you have the system in place to easily add new configuration files that you can share with others, across your machines, or use when setting up a new machine.


© 2019 Drew Barontini — Building products under Drewbio, LLC