Give Your Dotfiles a Home with GNU Stow

one painful part of keeping a doc house directory is managing symbolic links between your configuration files and the locations where they need to go in your home directory in this video i'll show you how easy it is to use gnu stow to automate the creation of all your sim block links with one single command stick around to learn more what's up everybody welcome to system crafters i'm david wilson and i would like to ask you that if you enjoy this video please click the like button below it really helps out with the youtube algorithm and also if you enjoy the content i make on this channel check out the link below to support the channel it would really help me out a lot i appreciate it so to get started make sure that you've already set up a doc files directory like the one i've described in the video called how to create a dot files folder in this video i'm going to assume that you have a doc files directory located right inside of your home directory and it's called dot dot file so that's the word dot files with a period in front of it if you follow the video that i mentioned before you will have a folder like that already you're also going to need to install gnu stow and you can find it in the package managers of most gnu linux distributions using the package name stow very easy to install just consult your normal documentation about how to install packages for your distribution if you're on mac os you can install it with home brew via the brew install stow command thankfully you have it easily there as well and you might be surprised to find out that on windows you can also install stove via the msys2 command shell follow the link below if you have never heard of that before it's very useful tool and you can use the pacman command there to install stow but one important thing is to make sure that you run the msys2 command shell as an administrator and have the m system sorry the imsys environment variable set to the string that i have below here you can copy and paste from the show notes uh so that it creates symbolic links uh correctly otherwise stow is just going to copy the files which you really don't want you want to have those symbolic links set up correctly so gnusto describes itself as a simlink farm manager but in practical terms it's basically just a program that can mirror the structure of one directory into another by creating symbolic links back to the original files and this is extremely useful when you have a directory full of configuration files like a dot files folder that's managed by git and you want to send all of those configuration files to where they belong in your home directory so we're going to learn today how you can use gnusto to basically link all your dot files to your home folder so let's say we've got our configuration file stored in a directory under the home directory called.files like we should have already we can easily create symbolic links to the files in this directory to the equivalent locations in the home directory using the stow dot command and that's to be run from within that dot dot files folder because we're saying in the files in this folder we want to link these to the home folder but before we run that let's actually take a look at what's already in the dot dot files folder that i have as an example and uh we'll we'll check out the dot files folder and the home directory to see the current state of all the files there so i'm going to jump into this terminal and then uh i guess this is ubuntu 2004 vm i'm gonna look at dot files folder first so let's just check out the dot files and we have a dot config folder dot emax id license file readme.org dot profile so there's a collection of files here that we want to keep as shared configuration files across multiple machines plus some other files that may have documentation and other information like that if we check out the home folder we'll see that none of those same directories are represented we don't have a emacs.d we don't have a readme.org we don't have i mean we do have a config folder but that actually is part of the linux desktop specification so a lot of programs will put their configuration inside of this.config folder so you'll see folders for various different programs so basically what we're going to do is try to sim link all of the files inside of this folder into the home folder so that our programs that we use can pick up the configuration files that we stored in our doc files folder so now we can run that stow command that i mentioned before but we're going to cd into the dot files folder first and then run stow dot and then we're going to see what it actually did so let's go into the dot files folder i'm going to run stow dot and now it doesn't really give us any output doesn't say anything happen but if we use ls-al on the home directory we can see that it actually did create some symbolic links to the dot profile file to this notes.org file to this misc folder in our emacs.d folder so really easy just one command it was able to create all those symbolic links directly one other thing we should take a look at is that inside the config folder we also have a symbolic link to the polybar folder which is actually inside of the dot dot file dot config folder so uh let's talk about how gnusto works oh one one last thing i want to mention is that it's possible that you're gonna receive an error saying that the target file or link already exists if you haven't cleaned up those existing files in your home directory already the solution there is to delete those files if you've already backed them up then you should be able to run stow and everything will be linked correctly all right so the way that this works is that gnusto walks the file and directory hierarchy of the directory that's passed as the source so in in this case we're saying stow dot which means uh in this case dot means the current directory so when we cd into our dot files folder we're telling so take all the files in this folder walk over all the files and directories and then make symbolic links into the equivalent locations in the target directory which is the home directory in this case the important thing to be aware of here is that our dot files directory must have the same layout as where those files should be placed under the home directory this is the only way that stow the only way that stone knows how to link a file to a target location is just by following the same folder structure in the source directory and then replicating that into the destination directory and when it makes these links it will do smart linking based on whether the directory structure in the home folder already exists so we already have that.config folder in the home folder so it only link the poly bar subfolder to the home folder so it sort of knows how to reconcile those things which is good so just make sure that your dot files folder has the equivalent subdirectory structure in place as it should be in the home folder so that all your symbolic links get created correctly um and the other thing you might have noticed is we didn't actually specify what the target directory is we call stowed dot but we don't say where to put the the dot the links for the dot files folder into the home folder and the reason why is that by default stow automatically assumes that the target directory is the parent directory of the directory that you've chosen so in this case the dot files directory's parent directory is the home directory so when you run stow dot inside of the dot files directory it automatically picks the parent directory which is home to make all the symbolic links in which is great because all it means is that in our case it's very easy we just run stove dot inside a folder that's directly under the home directory and we get all the symbolic links set up no configuration needed it works perfectly so if you want to see what the equivalent parameters are to stow in case maybe you want to change where your source directory is excuse me you can uh use the dash dash deer for the parameter for the source directory in this case dot files and dash target for the target directory or the shortened forms of dash d and dash t and this means you have basically full control over where the source and target directories are and a little tip here is that if you keep your doc files directory somewhere other than the home folder like let's say you have a folder where you keep all your git repositories and you want to keep your dot files folder there as well uh you'll definitely need to use this dash d and dash t parameters to make sure that the right locations get picked but you don't have to type that in every time you want to run stow so definitely create a simple bash script that makes it easy to run stow with the correct parameters and i'm actually going to show you an example one of those a little bit later in this video that you can just take and use yourself if you want to all right so by default gnuso actually does a pretty good job of ignoring common files and directories that you may not want to have linked back into your home directory like let's say a readme file a license file source control folders like dot git etc those things don't need to be linked back you really only want the configuration files to be linked now if you check out this link i have here it actually takes you to the new stowe documentation where it shows you the default list of ignore um or files and directories that are ignored so if you want to know what's there by default you can check that out but let's say that you have other files or directories in your dot files folder that you don't want to have linked into your home directory for example our dot files folder actually has a file called notes.org and that really doesn't need to be in the home folder it's something that just stays in our doc files repository so if we want to skip files like this and not have them be linked we can create another file inside of the doc files folder called dot stow local ignore and if you've ever used git before and you've seen a git ignore file this is a similar concept where each line of this file should be a string or a regular expression representing any file or directory pattern that you do not want to have linked to your target folder so you can see an example right here we've got a few different items in this list for this file like the git folder the misc folder that we saw before and then any folder that ends with dot org and if you use emacs and have a literate configuration set up with org mode and org babble then you might want to have this if you have all your org files in the top level of your dot files folder because you don't want those to be linked into your home folder so let's actually try that out right now i'm going to copy over this configuration and then i'm going to go into the dot files folder i'm going to use vim really quickly stow local ignore and then i'll just paste in the stuff that i copied whoops i'm gonna go just clean it up a little bit here and now if i save this then we can take a look at what's in our home folder and i'm going to remove the stuff that we don't want and see if it gets recreated the next time we run stow so i'm going to remove misc i'm going to remove notes.org so um rmrf home notes.org rmrf home misc so now those things aren't there anymore and then if i were to run stow dot and look at what's in our home folder again then we'll see that uh oh now this license file pops up but the misc and um notes.org files are gone so that's good it did actually obey what we said about the um the misc folder and the dot org file so those that no longer get linked but now all of a sudden this license file shows up and the reason why that happens is because when you specify your own custom stow local ignore file it overrides that default set of ignores that gnu still uses so if you want that license file to also be ignored you're going to have to go back into your stove file and then add that line to the file that's the reason why i had that commented out here so that i could make that example so i'm going to save this again i'm going to go remove the license file or the symbolic links that link to the license file from the home folder and we can see that it's gone now i'm gonna run stow.again and then i'll look at the home folder one last time and we'll see that the license file did not get created so whenever you start having a lot more stuff in your doc files folder is pretty likely that you're going to have to use a stow local ignore file so just keep in mind that you're going to have to set up some stuff for that and make sure that when you finally override the defaults you're going to have to be a little bit more explicit about which things you want to ignore so you can just use that example that i provided you with as a guide and then add more things that you need to there one last thing that i forgot to mention before is that when you run stow multiple times it actually will just continue forward without giving you any errors because what it does is it checks all the existing symbolic links to see if they're pointing to the desired target location and if they already do point there then it just does nothing the only time it will ever complain to you is if you have a normal file in a location or normal file or folder in the location where it's trying to place a link then it will complain but otherwise you can run stow as many times as you want and it will just you know have the same outcome which is a really nice thing that it does all right so once again you can just check out that link to the stove manual for types and syntax of ignore lists if you want to have uh see more about the ways that you specify those uh those ignore the ignore listing basically so cleaning up symbolic links so like for if some reason you would like to get rid of all the symbol links that gnu stoke created in your home folder you can actually do that very easily just by adding one extra parameter to the normal way that you invoke stow which is the dash capital d parameter so i'm going to go back to our config here take one last look at the home folder and then i'm going to run stow d dot because we're still in the dot files folder and when i do that i'll look at the home folder again and now that dot profile file is gone.emacs.d folder is gone it basically cleans up all the symbolic links that it had created so that they're not there any longer and you know you may not really need to do this ever but in case you ever just want to clean up your home folder get rid of all those symbolic links that's a very quick and easy way to do that so i just wanted to point that out and one last tip that i'll mention is that if you use git to commit your configuration files to a repository that you share between multiple machines like i do don't forget to run stow each time after you sync your configuration file updates so that any new files get linked into the proper location and you know you may wonder why after you sync all of a sudden your configuration is broken it's probably because some file that you're expecting to have is not actually been linked into your home folder so your configuration doesn't load correctly so to make sure that you never forget to do this you can actually use a script that i'm that i created called sync dot files to automate the whole process what the script does is it will stash your local changes anything that you've changed locally that you haven't committed yet it basically stores them away in a safe place and then pulls any new changes from the remote repository in this case it's the master branch but if you use a different branch name like main you may want to change that and then once it pulls those changes it will reapply those local changes that you had by using stash pop and then it will run stow on that folder so that any new files get linked into the appropriate locations and if you use this script you definitely might want to consider keeping this in your dot files repository or dot files folder under a bin subfolder and then add that to your path so you have access to the script anywhere from inside of your shell so this script is not that long it may look a little bit complex if you've never looked at uh bash shell script before but basically all it does is just run git stash to save your changes it pulls the changes from master and then reapplies your local changes by using good stash pop and then it does one last check using git diff to see if any merged conflicts have happened uh by reapplying your changes just so you have a chance to clean this up and then if everything's clean it just runs stowed dot and then it links everything back into your home folder so this should be helpful to you if you want to have one command that will sync all your dot files and then run stow dot so by the time of recording this video i haven't actually made a video about using git to manage your dot files yet i will do that at some point in the future but if you're watching in the future you may have already seen that video so either way just note that if you use git to manage your dot files this script might be helpful to you and i'll just point out one last time that you may need to change the name of the master branch in the script right here to main if your repository uses that name for the main branch instead all right so the last thing i'll say is that if you want more information about gnustowe and details on other ways that it can be used because it's not just for dot files it's actually for other things as well check out the new stove manual so i hope this video was helpful to you if it was leave a note in the comments and like the video of course also if you have any questions please feel free to leave them in the comments and check out the link in the description to find where you can come chat with the system products community both on discord and irc if you want to ask more questions and until next time thanks so much for watching i really appreciate you being here and happy hacking we'll see you

Channel: System Crafters

Views: 31,011

Keywords: gnu stow, stow, gnu stow tutorial, stow tutorial, dotfiles tutorial, symbolic links, links, symlinks, dotfiles, how to manage dotfiles, dot files, configuration, config files, configuration files, emacs, vim, bash, zsh

Id: CxAT1u8G7is

Length: 16min 34sec (994 seconds)

Published: Wed Sep 22 2021