Metadot: modular dotfile management

Metadot allows you to easilly manage and reuse existing dotfiles repositories by simply cloning then to your ~/.dotfiles/modules and renaming a few files.

By being modular, it's possible to create modules for specific applications (vim, mutt, emacs, git, etc). By using git submodules or subtrees, one can even create her own dotfile collection.

It was inspired by holman does dotfiles and many other initiatives but with a modular design to ease dotfile sharing as the metadot code is split from the dotfiles' folder.

Another approach is to use GNU Stow to manage your dotfiles.


Get the code:

git clone https://git.fluxo.info/metadot

Then check the source integrity of the latest release:

/usr/bin/git -C metadot verify-commit HEAD

Note that /usr/bin/git is called to avoid any other git wrappers or aliases you might have available on your shell.

Save the metadot repository anywhere but make sure it's available in your $PATH. I'm my config I use ~/apps/metadot.

Then get some modules. You can get the whole standard module collection with

metadot clone https://git.fluxo.info/rhatto/dotfiles

Or simply using

metadot clone default

Modules names as dotfiles have a special meaning and are handled like collections and are cloned directly as ~/.dotfiles. After cloning, you can check the current dotfiles revision using

metadot version

Third-party collections will hardly suit your needs, so you can fetch individual modules:

metadot clone https://git.fluxo.info/rhatto/dotfiles/vim

Or even start your own:

metadot create vim

In both cases your vim module will be available at ~/.dotfiles/modules/vim.

You can use just one collection at a time. While you can mixed a collection with individual modules, it's more sane to just start your own collection and keep modules as git submodules or subtrees.


The full list of commands is available with metadot usage. You'll probably want to start with the following.

List existing modules:

metadot ls

Load a module:

metadot load <module>

Load all modules:

metadot load --all

Backups are made whenever a module is loaded.


You can fetch updates in a module collection repository using

metadot fetch

This commands don't automatically update your working copy. Instead, it just does a git fetch in the remotes/origin repository and display it's last commit log including git signature.

You can check version differences using metadot version and also standard git commands such as git-log(1). Once you're satisfied and want to apply changes to the current working copy including updating and initializing submodules, type

metadot merge


  • ~/.dotfiles: where all dotfiles modules are stored
  • ~/.backups: backups of old config files
  • ~/.custom: some modules use this folder for custom configuration overriding default parameters

Module format

Modules rest at ~/.dotfiles/modules and can be git submodules or subtrees. File format is:


Which means files

  • with a .link extension are linked at $HOME.
  • with a .dot.link extension are converted to a dotfile: vimrc.dot.link is linked as ~/.vimrc.
  • with other extensions are ignored.


  • file structure is preserved: apps/scripts.link is linked as $HOME/apps/scripts.
  • nested structures are allowed: config.dot/awesome.link is linked as $HOME/.config/awesome.

See also


  • http://dotshare.it
  • http://dotfiles.org
  • https://dotfiles.github.io
  • https://bitbucket.org/davidn/dotstuff
  • https://github.com/staticshock/seashell
  • https://github.com/robbyrussell/oh-my-zsh
  • https://wiki.archlinux.org/index.php/Dotfiles
  • http://www.madewithtea.com/dotfiles-are-your-digital-backpack.html
  • http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html
  • https://taihen.org/managing-dotfiles-with-gnu-stow/


  • https://github.com/xero/dotfiles


Comments and patches: rhatto at riseup.net