At a glance
typecraft opens on a fresh Linux box with broken fonts, ugly colors, and a completely unconfigured Neovim, then runs one command and watches his entire environment snap into place: terminal gorgeous, Neovim perfect. The tool is GNU Stow, a symlink farm manager, and paired with a git repository it turns your dotfiles into something you can replicate on any machine, Linux or macOS, with a single command. The video builds the whole idea from the ground up: what Stow is, what a symlink actually is (demonstrated live with ln -s), the naming convention Stow expects, and then a real hands on demo stowing his Neovim and tmux configs. By the end you understand the full loop: edit a config anywhere, the change flows through the symlink into the repo, commit and push, and every other machine picks it up with a pull. This page rebuilds the whole tutorial, every command, every directory layout, and every joke, in the video's own order.
The one command demo
The video opens with the pitch, delivered at full typecraft energy: he has found the most amazing way to manage all of his dotfiles across all of his machines, and it does not even matter whether he is on Linux, which he uses Arch by the way, or macOS.
To prove it he shows the before state. He is on his Linux machine with essentially no dotfiles installed. The terminal is decent looking but the fonts are messed up and the colors, in his words, look like crap. He opens Neovim and it is completely unconfigured: it does not look very good and overall it is just a bad experience.
Then the trick. He runs one command, and it installs both his Alacritty configuration (Alacritty is the terminal emulator he uses) and his Neovim configuration immediately. He exits the terminal, reopens it, and everything looks gorgeous. Basically perfect. He opens Neovim and Neovim looks perfect too.
What is this amazing tool? It is called GNU Stow, and the rest of the video shows what it is, how it works, and why it is so awesome. Seriously, stick around.
What is GNU Stow?
So what is GNU Stow, how does it work, and why should you be interested in it? All great questions. Look at you, asking great questions and being handsome.
The motivation first. If you are anything like him, you have accumulated a certain set of tools over time as a software developer. When you switch between machines, maybe one machine breaks and you need a new one, or you get a new machine for work, you want your dotfiles and configurations set up as quickly as possible. GNU Stow is a game changer for exactly that.
The official definition, straight from the GNU Stow project: GNU Stow is a symlink farm manager which takes distinct packages of software and or data located in separate directories on the filesystem and makes them appear to be installed in the same place. For example, /usr/local/bin could contain symlinks to files within /usr/local/stow/emacs/bin, /usr/local/stow/perl/bin, and so on. His reaction to the docs choosing Emacs and Perl as the examples: "Man, these Emacs people in GNU, huh?"
The big picture, drawn out
To show how Stow transports dotfiles from one machine to another, he draws the whole system out on a whiteboard (the diagramming is done in Eraser, the video's sponsor). Start with a list of dotfiles. They could be large or small, but you have a bunch of different kinds:
- Your
.zshrcfile for Zsh. - Your Neovim configuration, which itself contains Lua files, plugins, and more.
- Your terminal configuration. For him that is Alacritty, which has a color scheme and the actual setup
.tomlfile inside it.
All of these configuration files can live in a single dotfiles repository in git. GNU Stow then creates symlinks to manage those files on completely different computers. Say the repository is your dotfiles repo on GitHub. You can use it to add your dotfiles to any computer you want.
Take his macOS machine. Using Stow he can basically copy and paste all of his dotfiles onto the Mac from the repo, and the cool part is that because of how symlinks work, if he ever changes any of those files on the Mac, the changes can be committed straight back to the same repository. Now take a Linux machine: same principle exactly. You essentially copy and paste the same dotfile setup and repurpose it for the Linux box, all done with symlinks. Draw some arrows, one more arrow, and the picture is complete: with GNU Stow and git you can replicate your dotfiles on any machine, macOS or Linux, and probably even WSL on Windows, though he does not own a Windows machine with WSL to test it. He is sure you can do it like that too, though.
stow, which plants symlinks from the expected home directory locations back into the clone. Because the files on each machine are symlinks rather than copies, an edit made anywhere lands in the clone, gets committed and pushed, and every other machine picks it up with a plain git pull.The learn.typecraft.dev plug
Mid video, a word from the typecraft platform itself. By the way, nerds: the video you are watching was released days earlier, ad free, on learn.typecraft.dev. Members get videos early with accompanying material that is basically a full tutorial in and of itself. YouTube channel members get free memberships on the platform, thanks for being ride or die typecraft gang. Members also get full courses, at recording time one on Neovim and one on tmux, with a Linux course coming soon, plus community posts, special Discord access and roles, and all kinds of goodies. Alright, back to the video.
What is a symlink?
The whole scheme runs on symlinks, so he stops to answer the obvious question: what exactly is a symlink?
A symlink is a special file in Linux, or in Unix systems generally, that acts as a pointer to another location in the filesystem, or even across filesystems. It lets you access data from another location without having to duplicate that data. A typical use in Linux is exposing an executable buried deep in the filesystem at a more convenient path so you can run it more easily.
The ln -s demo, live
He demos it from scratch. In a directory called some-random-folder he has an executable file called echo-something.sh. Run it and it echoes out hello world. A pretty simple file.
Now, he does not want to type the whole some-random-folder path every time. He could move the file to his home directory, but then he would be duplicating data, and if the file lived in a GitHub repository he would be moving it out of the repository to a local spot, which he does not want either. This is the perfect use case for a symlink:
ln -s some-random-folder/echo-something.sh something.sh
Piece by piece: ln is the tool that creates links from one file to another in Linux. The -s option stands for symbolic, meaning it creates a symbolic link, a special file that just points to another file in the system. The first argument is the file to link to, and the second is the name the new link should get. He picks something.sh.
With the symlink created, he verifies it by listing the directory with the long flag, which shows links:
ls -l
# something.sh -> /home/chris/some-random-folder/echo-something.sh
Two things to notice in that output. The arrow shows exactly which file the link points at. And all the way on the left of the listing, the permissions string starts with an l: that l stands for link, marking the file as a pointer to the file specified on the right. Pretty cool, right? Now instead of typing the whole directory out, sh something.sh does the same thing as running the original, because it is linked to that file.
The part that matters later: linked files are married
Here is the property the entire dotfiles workflow depends on. He opens the symlink something.sh and edits it, changing the output to hello poops. Something professional like that. Run the link: it says hello poops. Now go look at the original file in some-random-folder, the one the symlink points to, and it has changed as well.
Interesting. These two files are married together. They are completely coupled: change one and the other one changes. That, he says, is something to keep in mind for later in the video, because it is exactly the mechanism that lets an edit on any machine flow back into the dotfiles repository.
ln -s demo as a picture. The symlink stores only a pointer, so reading or editing something.sh really reads or edits echo-something.sh. When he changed the link's contents to "hello poops," the original changed too, because there is only one file. This coupling is the engine of the whole dotfiles workflow: edit the config your machine uses and you have edited the repo's copy, because they are the same file.GNU Stow and symlinks
Back to the amazing diagram, where the power of GNU Stow is now obvious. All GNU Stow really does under the hood is manage the creation and deletion, and a couple of other things, of symlinks. If you have a repository full of dotfiles, you can use Stow and the stow command to create symlinks in a smart way on all of your machines. On each machine, every file in your dotfiles is symlinked to the dotfiles repository that was cloned onto that machine.
That is the entire trick. No agent, no daemon, no sync service. A git repo holds the real files, and Stow plants the pointers where each program expects to find its config.
| Approach | What you type | What can go wrong |
|---|---|---|
| Copy files by hand | One cp per config, on every machine, every time anything changes | Copies drift apart immediately; the repo goes stale the first time you tweak a setting locally |
| Manual symlinks | One ln -s per file or directory, with the full source and target paths spelled out each time | Tedious and error prone at scale; you maintain the mapping in your head |
| GNU Stow | stow nvim from the dotfiles directory | The package layout IS the mapping; one command per tool, links created and removed for you |
ln -s works, as the demo showed, but you become the symlink manager. Stow derives every link from the directory structure of the package itself, which is what makes the one command install in the intro possible.The GNU Stow naming convention
Now the practical part. He sets up an example dotfiles folder to stow away his dotfiles, with the eventual goal of pushing it up to git. Stow has conventions around how it stows dotfiles, and the naming convention is interesting, but once you understand it, it makes plenty of sense.
The rule: in your Stow directory, each dotfile set is named after a package, and inside that package you recreate the exact directory path where the config needs to live on the machine, relative to your home directory. Then everything can live underneath that.
He works through three examples, from most nested to simplest:
- Neovim. On your machine the config exists at
~/.config/nvim. So in the Stow directory you create a new package callednvim, and within it you recreate the directory the config must live in:nvim/.config/nvim, with everything underneath that. - Alacritty. Alacritty configurations live in
~/.config/alacritty(Alacritty being the terminal emulator he has been using on Arch, and he uses Arch by the way). Same shape as Neovim: a new package namedalacrittycontaining the recreated path,alacritty/.config/alacritty. - Zsh. The super simple one. Your
.zshrcexists basically in the home directory as a dotfile, so the package iszshand the file goes exactly where it needs to go relative to home:zsh/.zshrc. Simple. Cool. Awesome.
$HOME. Run stow <package> from the dotfiles directory and Stow walks the package tree and plants a matching symlink in the home directory for each entry. No mapping file, no configuration: the directory structure is the configuration.Stowing the Neovim and tmux configs for real
Time to see it in practice. Everything in this section happens live on his machine.
Neovim first
He moves his real Neovim configuration, which currently lives under ~/.config/nvim, into the new nvim package he created in the example dotfiles folder, under its .config subdirectory. Looking inside the dotfiles folder confirms the shape: nvim contains .config, which contains nvim, which includes all of his Neovim configuration files.
And now the before state, recreated deliberately: because he just moved all his configuration files out of ~/.config/nvim and into the dotfiles directory, opening Neovim gives him a completely bare editor. There is nothing to it.
The fix is the whole point of the video. From the base of the dotfiles directory, type the stow command plus the name of the package to stow onto this computer:
stow nvim
Hit enter, and Stow links everything under the nvim package into the home directory. Which means ~/.config/nvim is now symlinked to the package's .config/nvim. He proves it by listing the config directory and searching for nvim:
ls -l ~/.config | grep nvim
# nvim -> ../example-dotfiles/nvim/.config/nvim
There is the nvim folder, and it is really just a symlink to example-dotfiles/nvim/.config/nvim. That is how GNU Stow works: super easy to move all of your configuration files into the Stow directory and then recreate the existing dotfile setup on any computer you have.
tmux, one more time, to get it in our brains
He runs the drill once more so it sticks, this time with tmux. He wants his tmux configuration in the example dotfiles repo, so he creates a new package, a top level directory in the dotfiles folder called tmux, and changes into it. His tmux configuration currently lives at the base of his home directory as ~/.tmux.conf, and since home is where it needs to end up, the file goes directly under the package: tmux/.tmux.conf.
With the config moved out, opening tmux shows a base tmux setup. Nothing interesting going on. Then, from the base Stow directory:
stow tmux
ls -la ~ | grep tmux
# .tmux.conf -> example-dotfiles/tmux/.tmux.conf
The .tmux.conf file is now symbolically linked to example-dotfiles/tmux/.tmux.conf. Awesome. Open tmux again and it is back to its original glory, the exact configuration he had built before he removed it from the machine, put back using symlinks.
Closing the loop: edit anywhere, commit, pull everywhere
Now the payoff of the "married files" property from the symlink section. Say you want to change something in one of your configuration files, for example one of your Neovim plugins. Change the plugin file locally, and because it is symlinked, the change also lands where the link points: the dotfiles folder gets those changes too. So on any computer where your dotfiles are deployed with Stow, any edit you make can be committed right back to the GitHub repo, and all the rest of your computers get every change the moment they pull the repo down.
That is managing your dotfiles from anywhere, for every computer. His verdict, verbatim: GNU Stow truly is a game changer when it comes to managing dotfiles and managing different computers and configurations throughout your life. I love it. I think it is amazing. His own dotfiles repository is linked below, so check that out. And hey, thanks nerds.
Key takeaways
- Dotfiles belong in one git repository, deployed everywhere by symlink. The repo holds the only real copy of every config; each machine gets pointers, not duplicates.
- GNU Stow is just a symlink manager with a convention. Under the hood it only creates and deletes symlinks, but it derives every link from the package's directory layout, so deploying a tool's whole config is one command:
stow nvim. - The naming convention is the entire API. Name a top level package after the tool, then recreate the path the config expects relative to
$HOMEinside it:nvim/.config/nvim,alacritty/.config/alacritty,zsh/.zshrc. - Symlinked files are coupled by design. Edit the config your editor actually loads and you have edited the repo's working copy, because they are the same file. That is what makes changes committable from any machine.
- The full workflow is clone, stow, edit, commit, pull. New machine: clone the repo and run stow per package. Ongoing: edit anywhere, push, and every other machine catches up with a pull. Works across Linux and macOS, and probably WSL too.
- A symlink is a pointer file, made with
ln -s target linkname, identified by the leadinglinls -loutput and the arrow showing its target.
Chapters
- 0:00 intro
- 1:04 what is gnu stow?
- 4:54 what is a symlink?
- 8:00 gnu stow and symlinks
- 8:40 gnu stow naming convention
- 10:30 stow our nvim and tmux configs
Notable quotes
- 0:00 "I have found the most amazing way to manage all of my dotfiles across all of my machines, and it doesn't even matter if I'm using Linux, which I use Arch by the way, or macOS." (typecraft)
- 1:04 "Okay, so what is GNU Stow, how does it work, and why should I be interested in it? Well, these are all great questions. So look at you, asking great questions and being handsome." (typecraft)
- 1:40 "GNU Stow is a symlink farm manager which takes distinct packages of software and or data located in separate directories on the filesystem and makes them appear to be installed in the same place." (typecraft, quoting the GNU Stow documentation)
- 2:05 "Man, these Emacs people in GNU, huh?" (typecraft)
- 7:40 "These two files are married together. They're completely coupled. If I change one, the other one changes. That's something to keep in mind for later on in this video." (typecraft)
- 8:00 "All GNU Stow really does under the hood is manage the creation and deletion, and a couple other things, of symlinks." (typecraft)
- 14:00 "GNU Stow truly is a game changer when it comes to managing dotfiles and managing different computers and configurations throughout your life. I love it. I think it's amazing." (typecraft)
- 14:20 "And hey, thanks nerds." (typecraft)
Resources mentioned
- GNU Stow, the symlink farm manager the whole video is about, with its official manual.
- typecraft's dotfiles repository, the repo he links below the video as a working example.
- learn.typecraft.dev, his platform with early ad free videos, accompanying tutorial material, and full courses: Neovim for Newbs and Tmux for Newbs, with a Linux course coming soon.
- Eraser, the video's sponsor and the whiteboard tool the diagrams are drawn in.
- Neovim, the editor whose config gets stowed in the main demo.
- tmux, the terminal multiplexer stowed in the second demo.
- Alacritty, the terminal emulator he uses on Arch, one of the naming convention examples.
- Zsh and its
.zshrc, the simple home directory dotfile example. - Arch Linux, which he uses, by the way.
- ln, the coreutils tool used with
-sto create symbolic links in the demo. - Git and GitHub, the sync layer that moves the stowed dotfiles between machines.
- WSL, the Windows Subsystem for Linux, his "probably works there too" aside.
- GNU Emacs and Perl, the examples in the official Stow definition that prompted the Emacs people joke.
- typecraft on YouTube, the channel.


