I'm going to assume you are reading this because:
you have one or more dotfiles lying around and you don't know how to organize them.
you heard that you can save dotfiles for later use in case your computer explodes or something.
you've seen other people's dotfiles on GitHub, and they look so damn cool.
you like superheros.
The thing about programming, or anything you try to teach yourself for that matter, is that when you start, you don't know what you don't know.
Dotfiles are a perfect example. You don't know about them until either someone tells you they are thing, or you fall down a rabbit hole and find yourself setting the
$PATH variable in your
Eventually you go from not knowing about dotfiles, to really caring about them. You realize just how essential they are for your workflow. How having a good relationship with them can accelerate your ability to solve problems.
And most important, you realize just how picky you really are, and how your dotfiles are a perfect outlet for such pickiness.
What you're probably doing
If you are not managing your dotfiles in any way, then they are probably strewn about your home directory. You probably have a file for your shell, say a
.bashrc or a
.zshrc. You probably have a
.vimrc or something like that. You might even have a
In this scenario your dotfiles are ephemeral. They exist as long as your machine exists. And when your machine goes down for the long nap, so will your dotfiles. You don't want to be that girl or guy setting up a new machine from scratch every single time. It sucks. I've been there. Avoid at all costs!
What you should be doing
Your dotfiles should be stored in such a way that you can access them anywhere at any time. If something happens to your current machine, or you need to setup another one, you're a
git clone away from an identical development environment. That is the dream.
You may have come across resources like Atlassian's How to store dotfiles, or Yet Another Dotfiles Manager. I've tried them both. They work, but they're a little involved.
Instead I recommend you use GNU Stow, a utility that lets you symlink files from different parts of your machine and make them appear as if they are installed in the same place. This will make sense soon.
How to do it
Step one is to create a
.dotfiles directory in your home directory. For example, let's say Alice's home directory is:
Alice will create her
.dotfiles directory here:
Next, you'll need to get your hands on the
stow package. Luckily it is a pretty ubiquitous piece of software, so most package managers should make it available to you. For MacOS users you can use
brew install stow
The third step is to move existing dotfiles to the
.dotfiles directory, and/or create new ones depending on your scenario. This step requires some explanation of how
stow has a few key concepts that, when understood, should make this entire process a breeze. These concepts can be found in the Terminology documentation:
- A package is a folder containing related dotfiles.
- A stow directory is a folder containing one or more packages.
- A target directory is the location in which a package's contents will be symlinked.
What this will look like in practice is:
target-directory ├── stow-directory │ ├── package-1 │ │ └── .dotfile-1 │ ├── package-2 │ │ └── .dotfile-2 │ └── .dotfile-3
Let's use Alice again as an example. Alice's
.dotfiles directory is located at:
.dotfiles directory is her stow directory. Currently it's empty. She will need to create one or more packages within it to house her dotfiles.
Alice has the following dotfiles:
Since each file belongs to a different "package",
git respectively, Alice will create a package for each:
# /Users/alice/.dotfiles mkdir bash mkdir vim mkdir git
Now, Alice can move each dotfile into their respective package directory. As a result, the
.dotfiles directory will look like this:
.dotfiles ├── bash │ └── .bashrc ├── vim │ └── .vimrc └── git └── .gitconfig
.dotfiles is the stow directory.
git are package directories. Their contents are the dotfiles themselves. Now, all that's left is to use the
stow command to target each package inside of the stow directory:
# /Users/alice/.dotfiles stow bash stow vim stow git
The commands above will symlink the contents of each package to the target directory.
But what is the target directory?
stow, the target directory is one directory above the stow directory. In Alice's case, if her stow directory is:
Then her target directory is:
Let me explain these symlinks a little bit better. When you run
stow <package>, the
stow utility will create the least amount of symlinks necessary to mirror the contents of the package to your target directory. If your package had a single dotfile,
stow will create a single symlink:
/Users/alice ├── .dotfiles │ ├── vim │ │ └── .vimrc ├── .vimrc -> .dotfiles/vim/.vimrc
The arrow (->) represents a symlinked file pointing to its original source.
This might seem obvious to some, but what happens if you have a subfolder within a package? For instance, it's common for Vim users to not only have a
.vimrc file in their home directory, but also a
.vim directory with scripts and plugins. How would you stow that?
/Users/alice ├── .dotfiles │ ├── vim │ └── .vimrc │ └── .vim | └── script.vim ├── .vimrc -> .dotfiles/vim/.vimrc ├── .vim -> .dotfiles/vim/.vim | └── script.vim
This gives you a ton of flexibilty, because very often command line tools like
vim use more than dotfiles stored in the home directory. They have their own directories and subdirectories, and being able to model this out within a package is really powerful.
Once you can visualize how
stow mirrors a package's contents to the target directory, structuring your
.dotfiles directory will be easy peezy lemon squeezy.
One more example
The last example I'll give should really drive
stow symlinks home. Let's say Alice is a
vim user, but instead of traditional vim she uses Neovim. Neovim doesn't use a
.vimrc file in her home directory, but instead an
init.vim file which is located at:
init.vim file is heavily nested. If Alice wants to stow this, how would she do it?
It's pretty simple actually. In her
.dotfiles directory she creates a package called
nvim. It would look like this:
.dotfiles ├── nvim │ ├── .config │ └── nvim | └── init.vim
The folder structure starting from
.dotfiles/nvim is the same structure that is expected in Alice's home directory. Now she just needs to stow the
# /Users/alice/.dotfiles stow nvim
And the result will be:
/Users/alice ├── .dotfiles │ ├── nvim │ └── .config | └── nvim | └── init.vim ├── .config -> .dotfiles/nvim/.config
Storing dotfiles in git
.dotfiles directory is just like any old directory on your machine. You can
git init and
git push up to your git repository of choice:
# /path/to/your/.dotfiles git init git add . git commit -m "storing initial dotfiles" git push
You can add a
.gitignore file to prevent unwanted configs from being pushed to your remote repository, and a
README to illustrate how it all works.
I hope this has helped you gain a better understanding of how to manage your dotfiles. This is by no means the only way to do it, but it is my preferred way.
You can really take this as far as you want to go. For instance, I am planning on creating an
install script that can be run on new machines. This script will install a bunch of dependencies like
node and the like, stow my dotfiles so the symlinks are created, etc.
If you want to take a peak at my dotfiles, you can see them here. They're still a work in progress, but it should be a good resource for learning.
If you made it to the end, thanks for reading! Have questions? See a mistake? Just want to say hi? Reach out to me on Twitter.
Top comments (12)
I use similar approach.
I do have dotfiles repo on GitHub that is severely outdated. Instead I have all my dotfiles in a folder called dotfiles in Dropbox.
I symlink them to my home folder.
Benefit : I don't have to remember to git commit/push. They are automatically saved by Dropbox.
I do that too. They're small, so it's free. Yay. I do the same thing with my second brain - Logseq, Obsidian and Craft
I just use chezmoi github.com/twpayne/chezmoi , it uses git to store the dot files for me, it's great
Oh this is great.... I have already put most of my dotfiles in a .dotfiles folder using the same structure, but by hand, invoking the symlink command:
ln -s .dotfiles/package/ ~/
I am in the middle of doing this right now, lol. My question is if I install stow, will it mess up my directory?
Second, if I use snow, and say, import my .dotfiles from my MacBook Pro 16 to my MacBook Pro 15 -> running Lenox, will my Lenox machine recognize them and can it use them?
Also, I tested everything to make universal commands on the Mac to make the symlink in my home directory invisible even when show hidden files are on.
I was also considering doing the same things to manage my paths and executables. Not for back up, only to have them all in one simple place. Like Crontab
About your second question, I'm not sure what Lenox mean. I'm assuming you mean linux.
If that is the case, I've been there.
The problem I faced is that some of my dotfiles had absolute path to the home directory which on macOS is like
/Users/mandar- This results into
path not founderrors on linux where home directory is
One precaution you may take is to use
$HOMErather than actual path.
Stow is pretty sophisticated. It shouldn't mess up your directory.
To answer your second question, you should git clone your .dotfiles directory onto the other machine, install stow and then run stow for each subdirectory within .dotfiles to ensure your configs get placed into the right part of your machine.
I accumulated a lot of conf using this method 👍 Here are my dotfiles github.com/bdelespierre/dotfiles
Great post but I would argue a git bare repo / folder is a better way to go vs symlinks?
Hey Michael thanks for the reply! I've used git bare repos in the past and always felt confused by them. They aren't as intuitive as using
stowin my opinion. But different strokes!
What happens when you have two or more packages that use . config/ ? Will it still try to symlink that directory? It would be much better to make sure the directory is created and only symlink files.
Great question! I can only answer from experience. There may be a more sophisticated answer.
Before setting up my
.dotfilesin the way I described in this post, I had a
.configdirectory with a few subdirectories for packages I use routinely. I don't need to version control these packages, so they aren't stowed in my
stowrealizes this, and instead of symlinking the entire
.configdirectory, it goes one level deeper and symlinks the stowed directory. This preserves the rest of the folders in
.configfrom being symlinked.
So what this looks like using a stowed
Hope this answers your question!