Config files. For use with GNU stow on supported platforms.
|
2 days ago | |
---|---|---|
alacritty | 3 days ago | |
neofetch | 3 days ago | |
vim | 3 days ago | |
.gitignore | 3 days ago | |
Readme.md | 2 days ago | |
dot | 2 days ago |
Manage your personal dotfiles with GNU Stow.
Keep your dotfiles in your git repo and symlink them into the correct place, allowing you to edit them without forgetting to copy those changes back into your repo.
Further, you can apply your dotfiles to another system by simply checking out your dotfiles repo and running:
./dot apply <package>
Any existing dotfiles on the system will be left as is. So there is no risk of accidentally clobbering untracked dotfiles.
NOTE: because clobbering existing dotfiles is avoided, you will have to manually delete or move existing config files out of the way. This only applies to files with same name and location as those in your dotfiles repo. Any other unrelated files (even in the same directory) can co-exist just fine.
Your applied config can be cleaned up by running:
./dot remove <package>
This removes the symlinks to your dotfiles that were previously applied effictively wiping your config.
Only symlinks to your config files are created, and only symlinks are removed. Therefore there is no risk of losing any changes you may have made since you applied your config.
The files here are structured for compatibility with GNU Stow to keep things as simple as possible and reduce reliance on custom logic.
You can package you dotfiles however you like, either by program or a collection of programs.
Packages that require config files in multiple locations are supported, so you don't have to jump through hoops to keep all your config in a single file or directory.
You can optionally apply only part of your config depending on requirements:
./dot apply <package> system
./dot apply <package> user
A package is simply a collection of dotfiles (or any config file) that should be applied together.
For added flexability, a package may also contain one or more targets.
All config files for a specific package are kept together in a top level subdirectory of the repo.
The directory structure of each package target is compatible with GNU stow.
A package is therefore simply one of thes top level directories and can consist of a config for one or more programs depending on your needs.
When discussing how package targets are handled, the following repo structure will be assumed:
Example with dotfiles repo checked out to ./dotfiles
(DOTFILES_DIR
):
./dotfiles
├── Readme.md
├── ssh
│ ├── system
│ │ └── etc
│ │ └── ssh
│ │ ├── ssh_config
│ │ └── sshd_config
│ └── user
│ └── .ssh
│ └── config
└── vim
└── .vimrc
This shows a repo with two packages:
user
target)system
and user
There is a custom wrapper bash script (useing GNU Stow) that you can use to easily install a config package:
Example Install the config for the vim
package:
./dot apply vim
Or, if the vim
package has no other targets, you can use GNU Stow directly:
stow -t "$HOME" vim
Multiple targets are supported in the case a given package has a mix of user config and system config.
Example Install only system config for the ssh
package:
./dot apply ssh system
Example Install all config for the ssh
package:
./dot apply ssh
You can still use GNU Stow directly, with just a minor tweak to the stow options to support the multi-target directory structure:
stow -d ssh -t "/" system
stow -d ssh -t "$HOME" user
NOTE: the package name is now passed to stow as the stow directory and the package target is passed as the package name.
At risk of improving upon the perfection that is GNU Stow, the concept of package targets is added to handle programs that do not store all config in a single location, or for when you want to keep some config separate depending on the target.
For example, you may want to stow your personal and system ssh(d) config on your home computer, but only your personal ssh config on a remote server.
By keeping the system and user config separate (as is typically the case when installed), then you can optionally instruct GNU Stow to apply only one of the targets.
Each package may have files that target the system or the user file heirarchy.
Therefore, each package may have a subdirectory containing any of:
In the case no target subdirectories are present for a given package, then the target is assumed to be the user
target.
NOTE: More targets may be added in the future:
/home/acme/.config
)/home/acme/.local
)/opt
)/usr/local
)/usr/local/lib
)But for now, $HOME
and /
is suffient to cover most use cases whilst keeping the package structure as simple as possible (albeiet with long somewhat redundant paths).
All directories under the user target are relative to $HOME
.
Example Stow the .vimrc
at $HOME
:
./dot apply vim
Given the example repo structure, the resulting $HOME
dir will look like:
/home/acme
└── .vimrc -> ./path/to/dotfiles/vim/.vimrc
On a GNU Stow compatible system this is equivalent to:
stow -d "$DOTFILES_DIR" -t "/home/$USER" vim
All directories under the system targt are relative to /
.
Example Stow system/user ssh
config at $HOME
and /
respectively:
./dot apply ssh
Given the example repo structure, the resulting $HOME
and /
dir will look like:
/home/acme
└── .ssh
├── config -> ./path/to/dotfiles/ssh/user/.ssh/config
├── id_ecdsa
├── id_ecdsa.pub
└── known_hosts
/etc
└── ssh
├── ssh_config -> ./path/to/dotfiles/ssh/system/etc/ssh/ssh_config
├── ssh_config.d
└── sshd_config -> ./path/to/dotfiles/ssh/system/etc/ssh/sshd_config
NOTE: given that one of the ssh package targets is a
system
target, you will likely need to run./dot
as root. In most cases, this should be fine as the files created will be symlinks, so permissions are not relevant. However, if this is not an option for you, you can apply theuser
andsystem
targets separately, requiring only running thesystem
target as root.
On GNU Stow compatible system this is equivalent to:
stow -d "$DOTFILES_DIR/ssh" -t "/home/$USER" user
stow -d "$DOTFILES_DIR/ssh" -t / system # needs root permissions obviously
To see what GNU Stow would do without making any changes, set the DEBUG environment var.
DEBUG=2 ./dot apply vim
The var can be an integer between 1 and 5 to increase verbosity.
Further more, if the DEBUG
environment variable is set, then the stow commands
being run will be printed - handy if you would prefer to just run stow directly
but would like a template to work with.