Installing files as hardlinks

doot supports two installation modes for your dotfiles:

• As symlinks (default)
• As hardlinks

Enable hardlinks only if you encounter one of these issues:

1. If your target_dir lives outside your $HOME (for example, when using the doot root custom command to manage system files), some programs might have security protections that prevent them from following symlinks into your home directory.

2. A few (poorly coded) applications might expect a given file to be a regular file and may fail or misbehave when given a symlink.

To switch to hardlink mode, add this line to your <dotfiles dir>/doot/config.toml:

use_hardlinks = true

Hardlinks point to the same inode, so these attributes are shared between the installed file and the file inside your dotfiles directory:

• File permissions
• Owner / group IDs
• Timestamps

Because of this, the installed files have the user who cloned/pulled the dotfiles repository as their owner.
If you run into permission errors, you can do one of the following:

• Change ownership: sudo chown <user>:<group> /path/to/file

• Give write permissions to other users: chmod a+w /path/to/file

You can automate these fixes by defining a custom hook that runs after installation.

If your dotfiles directory resides in a different filesystem than your $HOME / target directory, creating hardlinks is not possible.

For example, if you use Btrfs‍ subvolumes, you will need to either 1) place the dotfiles directory in the same subvolume as the target directory, or 2) use symlinks.

Checking if a file is a hardlink requires one extra syscall compared to a symlink, so the full directory scan that needs to be performed in doot install --full-clean and doot clean --full-clean will be even slower.

Keep in mind that you should not use --full-clean unless your dotfiles installation has somehow become corrupted.