Repository files navigation

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:

• No dependency on git. dfm works fine with git, Dropbox, or any other file syncing tool.
• No configuration files. Add files to be tracked just by placing them in the directory.
• No runtime dependencies. dfm can be run directly from the single binary file on a brand new machine.
• Overlay multiple repositories on top of each other.
• Automatically clean up removed files.

This project is "done". It's maintained, but there are no planned new features. It's actively used to handlethe 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.gztar -xf dfm.tar.gzsudo 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=~/dotfilesdfm init --repos filesdfm link --dry-rundfm 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, runningdfm 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:

dfmhelpdfmhelp initdfmhelp adddfmhelp link

This is the recommended workflow to effectively use dfm with your dotfiles. Look atCGamesPlay/dotfiles for a working example of this workflow.

1. Write a bootstrap script that installs dfm. I recommend downloading the binary from github via curl, butgo get might be an option if you prefer. The single binary can be placed anywhere; I prefer to place it in~/dotfiles/bin.
2. Configure the dfm directory. It's best to make a shell function: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 variableDFM_DIR=~/dotfiles.
3. Rundfm init --repos=files on each machine to configure it to use~/dotfiles/files as the main file repository.
4. Usedfm 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~/.
5. Rundfm 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 linkshared/.bashrc ->~/.bashrcwork/.my.cnf ->~/.my.cnf

Notice that.my.cnf was listed in bothshared andwork. Becausework was listed second in thedfm init call, it is the repository that was used for.my.cnf.

Tip: repos are just paths relative to the dfm directory. You could usemachines/web as a repo, or even an absolute path like~/other-dotfiles.

If you want to stop using dfm for some files, you can usedfm eject to copy it to your home directory and prevent dfm from automatically cleaning it up later. For example:

export DFM_DIR=~/dotfilesdfm eject~/.bashrcrm~/dotfiles/files/.bashrc

dfm will always use a hard copy when usingeject, 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 rundfm 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 indfm init.

dfm -d~/vhosts init --repos files --target /etc/nginx/vhost.ddfm -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:

maketest

There are lots of other dotfile managers out there, which dfm draws inspiration from:

• bonclay is similar in scope to dfm (built for dotfiles but applicable to general file syncing). It supports renaming config files, but requires managing a configuration file to do so. The automatic cleanup is limited to scanning the directory for broken symlinks.
• homemaker has many of the same goals as dfm, but requires a configuration file. The tasks functionality is potentially useful, and you could replace homemaker'slinks functionality with a task to rundfm.
• There's plenty of other options onGithub does dotfiles, but either require too many software dependencies, are too tied to specific workflows, or require too much configuration/learning to adopt easily.