From 3cf20c608dee63f5f6116bffcf964d06162ecaed Mon Sep 17 00:00:00 2001 From: Gabe Venberg Date: Sun, 13 Aug 2023 13:47:25 -0500 Subject: [PATCH] added post on dotfile management with stow. --- content/posts/dotfileManagement.adoc | 118 ++++++++++++++++++++++++++- 1 file changed, 116 insertions(+), 2 deletions(-) diff --git a/content/posts/dotfileManagement.adoc b/content/posts/dotfileManagement.adoc index 85e6d52..3d776d9 100644 --- a/content/posts/dotfileManagement.adoc +++ b/content/posts/dotfileManagement.adoc @@ -1,7 +1,7 @@ +++ -title = "DotfileManagement" +title = "Dotfile Management with GNU Stow" date = 2023-07-29T16:37:34-05:00 -draft = true +draft = false +++ :caution-caption: pass:[☠] :important-caption: pass:[❗] @@ -10,3 +10,117 @@ draft = true :warning-caption: pass:[⚠] :toc: :toclevels: 6 + +So ive been using git to managing my dotfiles since [checks `git log`]... 2018. +At first, I was going to write some inevitably brittle shell script to handle symlinking from the dotfile repo to where each file should be, +but before I got about to implementing it, I discovered `stow`. +Now, after using stow for dotfile management for over 5 years, I figure I should really document exactly how I go about managing my dotfiles, with an aim to help other people who want to have an easy to manage dotfiles repo that can be quickly deployed on new machines. + +== What Stow does + +https://www.gnu.org/software/stow/[stow] is a 'symlink farm manager', but I almost prefer to think of it a simplistic package manager that makes it incredibly easy to create packages from scratch. +Like most of the gnu progect utility, the https://www.gnu.org/software/stow/manual/stow.html[documentation] covers a lot, but is a bit intimidating if you dont already know the software. + +At its core, if you are in directory `~/foo`, containing a directory `bar`, whitch itself contains some files and folders like so: +``` +~ +└── foo + └── bar + └── .config + └── bar + └── bar.cfg +``` +`cd` ing into `foo` and running `stow bar` will symlink the contents of `bar` into `~`, resulting in a file structure looking like: +``` +. +├── foo +│ └── bar +│ └── .config +│ └── bar +│ └── bar.cfg +└── .config -> ~/foo/bar/.config +``` +now, stow does a neat thing called tree folding, so if you make another 'package' in `foo`, so the file tree looks like: +``` +. +├── foo +│ ├── bar +│ │ └── .config +│ │ └── bar +│ │ └── bar.cfg +│ └── baz +│ └── .config +│ └── baz +│ └── baz.config +└── .config -> ~/foo/bar/.config +``` +then running stow on baz, (`stow baz`) will result in: +``` +. +├── foo +│ ├── bar +│ │ └── .config +│ │ └── bar +│ │ └── bar.cfg +│ └── baz +│ └── .config +│ └── baz +│ └── baz.config +└── .config + ├── bar -> ~/foo/bar/.config/bar + └── baz -> ~/foo/bar/.config/baz +``` +stow realized that both `bar` and `baz` had `.config` in common, and turned it into a real directory, and remade the symlinks one level lower. +Stow calls this https://www.gnu.org/software/stow/manual/stow.html#Tree-folding[tree folding]. +It can do the reverse, as well, running `stow -d bar` will result in: +``` +. +├── foo +│ ├── bar +│ │ └── .config +│ │ └── bar +│ │ └── bar.cfg +│ └── baz +│ └── .config +│ └── baz +│ └── baz.config +└── .config -> ~/foo/baz/.config/baz +``` +It detected that .config was no longer shared, and unfolded the tree, making `.config` a direct symlink again. +Note that if .config contained files that stow doesnt 'own', it would leave it alon,e only deleting the 'bar' symlink when `stow --delete bar` was run. + +In short, you can think of stow taking a folder, and symlinking the contents of that folder exactly 2 levels up the directory tree, symlinking `~/foo/bar/contents` directly to `~/contents`. + +== Ok, how do I use this to manage my dotfiles? + +So now you know how to stow operates, you can make a 'package' for every program you have dotfiles for. +Id encorage you to take a look at the directory structure of my dotfiles https://git.venberg.xyz/Gabe/dotfiles[repo] if you want more examples of the directory structure you should aim for. + +Once you have the file structure down, all you need to install on a new machine is `git` and `stow`, git clone your dotfile repo, `cd` into it, and `stow` the folders for the software you want to install configs for. + +== Non-stow considerations + +Stow helps you manage your configs, but nothing else. +A lot of your more complex configs probably reqire other software beyond the program that reads that config. +for example, my terminal emulator config needs a specific font installed, +my i3 config requires specific programs installed for which keybinds are defined, +my neovim config needs things like wget, gzip, python, cargo, xsel, fzf, and others for things from treesitter to clipboard support. + +Id encorage your repos readme to have a section on each config package that has external dependencies, +explaining what dependencies are needed, +and if the dependency is only needed for a single functionality, +what functionality they add and what part of the config to comment out if the functionality is not needed. + +Id also reccomend you create a directory called `scripts` or something similar that is not a stow package, +but is put on your `$PATH` by your `.zshrc` / `.bashrc` / `.fishrc` / the dotfile for whatever shell you use. +This is for you to put any scripts you develop that may be called by/aliased by your configurations. + +== Bootstrapping + +Stow can be found on pretty much every linux distributions package manager. If for some reason it is not, building from source is... suprisingly easy. + +You can find the source http://ftp.gnu.org/gnu/stow/[here], download `stow-latest.tar.gz`, and decompress it with `tar xvf stow-latest.tar.gz`. cd into the the uncompressed folder, and simply run `autoreconf -iv`, `./configure`, and `make`. The binary will be in `./bin/stow` free for you to move it into your `$PATH`. + +== Conclusion, or something + +So, that more or less explains how I manage every bit of text-based configuration on my machine. Again, Id highly reccomend you check out my https://git.venberg.xyz/Gabe/dotfiles[repo] or the repo of anyone else using stow for dotfile management.