GNU Stow is used to manage configuration files for my Linux/UNIX tools and applications on all of my personal systems. The term “Dot Files” is
a reference to configuration files for many Linux/UNIX tools that prefix their configuration files with a “.” (in other words a “dot”). I maintain the configuration files in a shared directory (~/Shared/DotFiles) that is replicated across systems using SyncThing. Stow creates a series of symbolic links from the standard and known locations for those configuration files to the actual location of the configuration files in the shared configuration directory.
These instructions in this post serve as a reminder to me on how I use Stow to add new configuration files in the shared configuration folder or to update existing files. Perhaps, this content can be helpful for you too.
TL;DR
Use these commands to link dotfiles using the Stow command:
$ cd ~/Shared/DotFiles
$ stow -v --target=$HOME -S PKG
The PKG parameter is a directory in the ~/Shared/DotFiles directory that contains a collection of related files and directories. For example, I have a series of files for my Bash configuration in the bash directory. To install those, use the following command:
$ cd ~/Shared/DotFiles
$ stow -v --target=$HOME -S bash
Use the same command with each package directory in ~/Shared/DotFiles to install the symbolic links for that package.
Stowing Dotfiles from a Shared Directory
Here is a simple example for using Stow to create a link to the configuration file for Starship.
$ cd ~/Shared/DotFiles
$ stow -v --target=$HOME -S starship
There is only one file to link: ~/.config/starship.toml
Here is another example to update the configuration files for Doom Emacs.
$ cd ~/Shared/DotFiles
$ stow -v --target=$HOME -S doom
Doom Emacs is unique in that it has configuration files that can be shared across systems stored in ~/.config/doom. However, it also compiles code unique to each system it runs on that can’t be shared due to machine instruction differences (e.g., x86_64 versus arm64 machine code). Doom Emacs includes a script to manage the packages used and the compilation process, which is separate from the configuration file management tasks using Stow.
Creating Package Directories for Stow
The collection of configuration files and directories that can be linked to with Stow are referred to as packages. You must organize the files and directories under the package directories as they should appear under your home directory.
Here is an example to create a simple package for a single configuration file:
$ cd ~/Shared/DotFiles
$ mkdir bash
$ mv ~/.bashrc bash
Just remember that the .bashrc file will be hidden since it is prefixed with a “.”.
Here is a more complicated example that uses the ~/.config folder:
$ cd ~/Shared/DotFiles
$ mkdir -p starship/.config
$ mv ~/.config/starship.toml starship/.config
Stow will create a symbolic link in the ~/.config directory named starship.toml which points to the ~/Shared/DotFiles/starship/.config/starship.toml configuration file.
Create your package directories so that they have a file structure that mimics the structure needed for Stow to create symbolic links to appropriate files and directories.
Using Stow
Stow is described in the documentation as a link farm manager and was originally designed to administer software packages. Its flexibility allows for this use as a personal configuration file management tool. For more information see the main Stow documentation.
Shared Configuration File and Directory Location
When using Stow, you should change to the directory where the shared configuration files are stored. In my case that is ~/Shared/Dotfiles.
$ cd ~/Shared/DotFiles
Once there, you can execute the Stow commands.
Hidden Files in Packages
The ~/Shared/DotFiles directory contains packages with hidden files. These hidden files are configuration files with file names prefixed with a ‘.’. Be sure to look for hidden files in those sub-directories.
Stow Options
There are several Stow options to be aware of.
Verbose Output
Use the “-v” option generate verbose output from the stow command. This might help with diagnosing issues.
Show But Don’t Do
You may want to see what stow would do before you want to make changes. You can use the “-n”, “–no”, or “–simulate” options to show the actions stow would take.
Set Your Target
Stow needs to know where to create links. Use the “-t DIR” or “–target=DIR” options to set the location where stow should build symbolic links to your dot files. In almost all cases, this should your home directory: $HOME. For example, I use “–target=$HOME”.
Stow Those Files
To create the links, use the “-S” or “–stow” option.
Unstow Those Files
To delete the links, use the “-D” or “–delete” option. This will delete previously created links.
Restow Those Files
Why would you ever want to do this? Well you need to cleanup some older obsolete symbolic links. Use the “-R” or “–restow” option to unstow/delete and then to stow the packages.
Adopt Existing Files
You can use Stow to take existing files and incorporate or adopt them into the DotFiles package structure. This might not do want you intend. Use caution with this option.
Version Control with git
You can use git or another source code management tool to track changes to the DotFiles packages over time. I have not yet implemented this, but I plan to document the use of git for this purpose at a later date.
ikawnoclastic thoughts 