At one point or another, every developer will have to set up his workspace on a completely new machine. The reason could be anything (e.g. new hardware or operating system), but what is sure is that this day will come sooner or later. And when it comes, be sure to have prepared for it so it doesn't take you days but hours at most.

How do we prepare for it? Well, the biggest workload when setting up a workspace is configuration. It takes time to set up partitions, install the operating system, install all applications you need, and setting up password manager. But the biggest gotcha is configuring your applications to fit your need. Be it a simple vscode config file or a fully fledged nvim IDE, it does not get better the longer you are working in this field.

But there is a simple solution I found that does not have any dependencies and is really easy to implement. And it also works on both Linux and macOS! So, let's get to work!

Requirements

• Basic knowledge of the CLI

The problem we are trying to solve

Our goal is to push all important configuration files (also called dotfiles, because they usually start with a .) to a GitHub repository. Now there is one big caveat we have to deal with in order for this to work.

The configuration files are not in one place, but actually spread across the whole system. This means we can't just push one folder to GitHub because we need the dotfiles at different locations in the system. And if we were push one folder to GitHub, we would need to replace the configuration file each time we make a change. No bueno.

The solution is actually pretty easy. We just have to create one folder where we put all our config files in and then create symlink for each file to its required location. The symlink then makes a copy to that location and the file gets consumed by the corresponding application. This way, any changes we make on our current system will immediately take place without us having to copy and paste files.

How symlinks are the way to go

But let's take one step back. What are symlinks? Symlinks, or symbolic links, are file-system objects that point toward another file or folder. These links act as shortcuts with advanced properties that allow acces from locations other than their original place in the folder hierarchy by providing operating systems with instructions on where the "target" file can be found.

These type of links began to appear in operating systems in the late 70's such as RDOS. In modern computing, symbolic links are present in most Unix-like operating systems which are supported by the POSIX standard. They are also used in many cloud-storage services like OneDrive, Google Drive or Dropbox to manage the storage location of files.

Symbolic links are further divided into two types, hard links and soft links. We won't need hard links, but in a nutshell, they are actual files that point to the exact same data in storage as the file the link was created with. When you create a hard link, and then change that new file, the old file also reflects those changes (which not only includes the content but also permissions, ownership, timestamps, etc...). When you remove the old file, the data still exists under the secondary hard link. The data is only removed from your drive when all links to the data have been removed.

Soft links are the ones that interest us, and they are usually the links that people talk about when they refer to symbolic links. A soft link differs from a hard link in that it is not an actual file, but a special file with the sole responsibility to point to the original file. So every time you open and edit a soft link, what you are actually doing is editing the original file. This also means that if you delete the original file of the soft link, the soft link is now broken and the data is lost. Be sure to keep this in mind.

Creating our first symlink

Now that we know what symlinks are, the solution seems simple. The only thing we need to do is to move all our important config files to one monorepo and set up symlinks to their desired locations. Let's see this in action.

Suppose we have a .bashrc with our custom configuration that we want to push to GitHub. The first thing we need to do is to create a folder for our repo. I'll create mine at ~/Desktop/dotfiles. I will also create a folder for the .bashrc to maintain structure. This will come in handy when we got several configuration files, trust me.

mkdir -p ~/Desktop/dotfiles/bash
cd ~/Desktop/dotfiles/bash

Now we need to move our existing .bashrc to our newly created folder and create a symlink to where that file originally resided. There are several ways to create symlinks, but in my opinion, it is the easiest to just go to the location you want to create the symlink and enter the command ln -s <FILE_LOCATION>.

mv ~/.bashrc ./
cd ~
ln -s ~/Desktop/dotfiles/bash/.bashrc

This will create the symlink in the current directory with the same name as the original file. It might seem a bit hard at first, but after you've done it a couple of times, it becomes really easy. In fact, you could say it gets... soft. (Because, you know, soft links.)

Once you’ve repeated this process for your other configuration files, your dotfiles repo will gradually become your personal toolkit for any new machine. The best part? The next time you switch computers, all you’ll need to do is clone your repository and re-establish the symlinks. In just a few commands, your familiar setup will be back — no more hours lost hunting down old tweaks or rebuilding configs from memory.

Managing dotfiles this way is simple, portable, and future-proof. Whether you’re setting up a brand-new laptop, spinning up a cloud server, or just experimenting on a VM, you’ll always have your environment ready at your fingertips. Think of it as your developer “save file” — one you can load anywhere, anytime.