1. Introduction

Symbolic links, or symlinks, are useful for organizing configuration files. They provide access to a file or directory from another location, allowing you to keep your actual configuration files together in one place.

As the number of symlinks grows, you may want to keep track of:

• Where you created them
• What each one points to
• Whether their targets still exist
• How to restore symlinks you have deleted

slink is a macOS CLI that records each symlink's location and target in a registry file when you create it.

You can list your symlinks, check their status, and restore them from the command line. You can also register existing symlinks. It works for symlinks to files and directories beyond just dotfiles.

2. Installation

Install slink with Homebrew:

brew install kkensuke/tap/slink

If the following command displays a version number, the installation is complete.

slink --version

3. Getting Started

You do not need to prepare a configuration file in advance. Let's start with a sample file.

3.1. Create a Symlink

Create a directory and a text file to try it out:

mkdir -p ~/slink-demo
cd ~/slink-demo
printf 'Hello, slink!\n' > hello.txt

Create a symlink pointing to hello.txt:

slink hello.txt hello-link.txt

The basic syntax is:

slink <target> <link>

In this example, hello.txt is the actual file, and hello-link.txt provides another way to access it.

Read the file through the symlink:

cat hello-link.txt

Output:

Hello, slink!

The contents of the original file are displayed. If you edit hello.txt, the contents you read through the symlink will change as well.

You can create symlinks to directories using the same syntax.

3.2. List Registered Symlinks

Symlinks created with slink are automatically registered.

slink list

This displays the locations and targets of your registered symlinks.

3.3. Check Symlink Status

Check that a symlink matches its registration and that its target is accessible:

slink check ~/slink-demo/hello-link.txt

If there are no problems, you will see:

OK 1 links

To check all registered symlinks, omit the path:

slink check

Use list to view registrations and check to inspect the actual state of your symlinks.

4. The Registry File

4.1. Find Its Location

Symlink registrations are normally saved in the following TOML file:

~/.config/slink/links.toml

To find the registry file slink is currently using, run:

slink --config

The registry file is created automatically when you create a symlink or register one with adopt.

4.2. Open the Registry File

To open it with the default macOS application, run:

open "$(slink --config)"

If the VS Code code command is available, you can also open it with:

code "$(slink --config)"

4.3. Registry File Contents

If your home directory is /Users/you, the symlink from our example is recorded as follows:

[[link]]
link   = "/Users/you/slink-demo/hello-link.txt"
target = "/Users/you/slink-demo/hello.txt"

A [[link]] block is added for each registration. Paths are stored as absolute paths, even if you use relative paths in a command.

You can handle everyday operations with slink commands, or open the registry file to view and edit the relationships between symlinks and their targets directly.

5. Command Reference

Arguments in square brackets, such as [link ...], are optional. ... indicates that you can provide multiple paths.

• check and fix operate on all registered symlinks when no paths are specified.
• unregister and remove require paths to registered symlinks.
• adopt takes paths to existing symlinks and adds or updates their registrations.
• scan searches the current directory when no directory is specified.

6. Option Reference

Short options can be combined, as in -np.

Use --config, --help, and --version on their own. --config displays the location of the current registry file; it does not specify an alternative configuration file.

slink --help

7. Common Tasks

7.1. Link Configuration Files from Your Dotfiles

Suppose you keep your Neovim configuration in ~/dotfiles/nvim and want to access it from ~/.config/nvim, where Neovim looks for its configuration.

Once you have placed your configuration in ~/dotfiles/nvim, run:

slink -p ~/dotfiles/nvim ~/.config/nvim

The -p option creates the parent directory ~/.config if needed. It does not create the target directory ~/dotfiles/nvim itself.

Your configuration in ~/dotfiles/nvim is now accessible through ~/.config/nvim.

To preview the changes before applying them, add -n:

slink -np ~/dotfiles/nvim ~/.config/nvim

After reviewing the planned changes, run the command again without -n.

7.2. Restore a Deleted Symlink

You can recreate registered symlinks with fix.

Let's try this with the sample symlink. First, delete only the symlink:

rm ~/slink-demo/hello-link.txt

The target file, hello.txt, remains in place.

Next, restore the symlink from its registration:

slink fix ~/slink-demo/hello-link.txt

Check that you can read the file through the symlink again:

cat ~/slink-demo/hello-link.txt

Hello, slink!

To restore multiple symlinks at once, omit the path. Add -n to see what would happen without making any changes:

slink fix -n

After reviewing the preview, apply the changes:

slink fix

7.3. Find and Register Existing Symlinks

You can also bring symlinks previously created with tools such as ln -s under slink's management.

For example, to find symlinks directly inside ~/.config, run:

slink scan ~/.config

To include subdirectories, add -R:

slink scan -R ~/.config

scan can also find symlinks that have not been registered.

Use adopt to register a symlink you find. For example, if ~/.config/nvim is already a symlink, register it with:

slink adopt ~/.config/nvim

This records its location and current target without changing the symlink itself.

Once registered, you can view and check it alongside your other symlinks with list and check.

slink check ~/.config/nvim

7.4. Delete or Unregister a Symlink

When you no longer need the sample symlink, choose one of the following operations.

To delete both the symlink and its registration, use remove:

slink remove ~/slink-demo/hello-link.txt

The target file, hello.txt, is not deleted.

To keep the symlink and stop managing it with slink, use unregister:

slink unregister ~/slink-demo/hello-link.txt

This leaves the symlink in place and removes it from the symlinks included in list, check, and fix.

For detailed usage and updates, see the English README.