dfm is a generic file syncing utility to keep two directories in sync, using symbolic links. It's targeted at keeping a home directory in sync with a dotfiles repository, but can be used in other circumstances as well.
Features:
This project is "done". It's maintained, but there are no planned new features. It's actively used to handle the author's dotfiles and possibly others with few issues reported. If you identify a bug or dfm is not compatible with some OS, please don't hesitate to file a pull request or open an issue.
dfm is distributed as a single binary and can be installed anywhere. To install it to your /usr/local/bin
directory, use a script like this one:
DFM_VERSION=$(uname -s | tr A-Z a-z)_amd64 # "darwin_amd64" or "linux_amd64"
curl -sSL https://github.com/cgamesplay/dfm/releases/latest/download/$DFM_VERSION.tar.gz -o dfm.tar.gz
tar -xf dfm.tar.gz
sudo mv dfm /usr/local/bin/
dfm --version
To get started with dfm from a blank slate (to see how it works), try these commands:
$ mkdir -p ~/dotfiles/files
$ export DFM_DIR=~/dotfiles
$ dfm init --repos files
$ dfm add ~/.bashrc ~/.vimrc
$ ls -la ~/.bashrc ~/.vimrc ~/dotfiles/files
Notice that ~/.bashrc
and ~/.vimrc
have been replaced with symlinks, and the real files live in ~/dotfiles/files
. You can store ~/dotfiles/files
in a source control system, or even the entire ~/dotfiles
directory, if you have extra scripts that you would like to add. Note that .dfm.toml
is machine-specific and should not be added to source control.
When you are setting up a new machine, assuming you have already created ~/dotfiles/files
on that machine (e.g. by cloning your git repository, syncing, whatever):
export DFM_DIR=~/dotfiles
dfm init --repos files
dfm link --dry-run
dfm link
dfm link
will scan ~/dotfiles/files
and create symlinks in your home folder for each file found. If you have removed files from the repository, running dfm link
again will automatically delete those broken symlinks.
dfm includes a help command that explains all available options. Run one of these to learn more:
dfm help
dfm help init
dfm help add
dfm help link
This is the recommended workflow to effectively use dfm with your dotfiles. Look at CGamesPlay/dotfiles for a working example of this workflow.
go get
might be an option if you prefer. The single binary can be placed anywhere; I prefer to place it in ~/dotfiles/bin
.function dfm() { ~/dotfiles/bin/dfm --dfm-dir=~/dotfiles "$@" }
If you don't mind global configuration, you can also place dfm anywhere in your $PATH
and set a global environment variable DFM_DIR=~/dotfiles
. dfm init --repos=files
on each machine to configure it to use ~/dotfiles/files
as the main file repository.dfm add
to add all of your existing configuration to ~/dotfiles/files
, or copy them from your existing dotfiles repository. dfm does not rename files, so the file structure in ~/dotfiles/files
should look exactly like you want it to appear in ~/
.dfm link
to synchronize all of the symlinks in your home directory.dfm supports multiple repositories of files. When multiple repositories are configured, dfm link
will link to the file in the last listed repository which has the file in question. For example:
$ export DFM_DIR=~/dotfiles
# Assume this directory structure:
# ~/dotfiles
# /shared
# /.bashrc
# /.my.cnf
# /work
# /.my.cnf
$ dfm init --repos=shared,work
$ dfm link
shared/.bashrc -> ~/.bashrc
work/.my.cnf -> ~/.my.cnf
Notice that .my.cnf
was listed in both shared
and work
. Because work
was listed second in the dfm init
call, it is the repository that was used for .my.cnf
.
Tip: repos are just paths relative to the dfm directory. You could use machines/web
as a repo, or even an absolute path like ~/other-dotfiles
.
If you want to stop using dfm for some files, you can use dfm eject
to copy it to your home directory and prevent dfm from automatically cleaning it up later. For example:
export DFM_DIR=~/dotfiles
dfm eject ~/.bashrc
rm ~/dotfiles/files/.bashrc
dfm will always use a hard copy when using eject
, so it's safe to simply delete the files from the dfm repo afterwards. Keep in mind that if your dfm directory is shared, any other machines using it will simply see that the files were deleted, and will automatically clean them up when you next run dfm link
.
If you want to stop using dfm entirely, dfm eject
with no arguments will eject all tracked files. You can remove your dfm repos afterwards.
Each dfm directory manages a single target directory. For dotfiles, the target directory is your home folder, but dfm can manage any directory you choose, by configuring that directory in dfm init
.
dfm -d ~/vhosts init --repos files --target /etc/nginx/vhost.d
dfm -d ~/vhosts link
dfm is built with go, so make sure you have a go compiler set up on your system. The project is a go module, so the other dependencies will be installed automatically when you build the software.
To make and install locally:
make install
To test:
make test
There are lots of other dotfile managers out there, which dfm draws inspiration from:
links
functionality with a task to run dfm
.