manage-dotfiles

Instructions

On Linux and macOS, dotfiles will be managed via GNU stow.

The stored dotfiles will use the XDG configuration for simplicity and organization.

The commands below assume that there is a specific config package which is being interacted with (eg: nvim )

Syncing Dotfiles - Exporting Configurations

Sync a dotfiles package to its target location using GNU stow.

Instructions

Validate the package exists at ~/dotfiles/{package} :

If it doesn't exist, list available packages (top-level directories in ~/dotfiles that aren't hidden or special like result , docs , ░▒▓ OLD ▓▒░ )
Fail with a clear error message

Run stow to deploy the package:

stow -v -d ~/dotfiles -t ~ {package}

Report what was linked. If stow reports conflicts, explain what's blocking and suggest using stow -D to unstow first, or stow -R to restow.

Importing Configurations

Import an external config into the dotfiles repository and stow it.

Instructions

Resolve the path: Expand ~ and resolve to an absolute path. Verify the file/directory exists.

Compute the home-relative path: The path must be under $HOME . Strip the $HOME prefix to get the relative path.

Derive the package name:

For .config/<app>/... paths → package name is <app>
For .<dotfile> (hidden file in home root) → package name is <dotfile> without the leading dot
For .local/share/<app>/... → package name is <app>
For other structures → use the first directory component, or ask the user

Create the package structure in ~/dotfiles :

mkdir -p ~/dotfiles/<package>/<parent-dirs>

Where <parent-dirs> mirrors the home-relative path's directory structure.

Move the config into the package:

mv <original-path> ~/dotfiles/<package>/<home-relative-path>

Stow the package to create symlinks:

stow -v -d ~/dotfiles -t ~ <package>

Verify: Confirm the original path is now a symlink pointing into dotfiles.

Example

Importing ~/.config/wezterm/wezterm.lua :

Notes

If the package already exists, merge the new config into it
Do NOT use ln
only use stow for symlinking
If importing a single file from a directory that has other files, ask if the user wants to import the entire directory or just the file

Source Transparency