Basics

What is a symlink — and how one slash wipes the real folder

Illustration: a sign with an arrow points at a real box while someone sweeps everything out of the box

Look at this trick. There's a link called ld pointing at a folder called realdir. You want to delete the link, so you type:

rm -r ld/

The terminal complains: cannot remove 'ld/': Not a directory. Looks like nothing happened. You open realdir — it's empty. The link is still there, and your files aren't.

I tested this on Linux. A trailing slash means "go inside." That's why three things about links are worth knowing before you delete one.

What a symbolic link is

A symbolic link (symlink) is a tiny file that contains the path to another file or folder. That's all that's in it.

Picture a sign that says "Warehouse → that way." The sign stores nothing. But anyone who reaches it gets sent to the warehouse. A program opens the link and lands wherever the path leads.

You create one like this:

ln -s AGENTS.md CLAUDE.md

The order is like cp: first what already exists, then the new name. Read it as "let CLAUDE.md lead to AGENTS.md." Now it's one file with two names, and your agents don't need three copies of the same text. We covered that story in the piece on AGENTS.md.

ls -l shows you the link:

lrwxrwxrwx 1 me me 9 CLAUDE.md -> AGENTS.md

The l at the start and the arrow give it away. If terminal commands are still new, start with the ones you'll need most.

Where you already meet them

Links are working around you every day, even if you never made one.

  • pnpm. In node_modules, a package isn't there itself — it's an arrow: lodash → .pnpm/[email protected]/node_modules/lodash. That's why ten projects don't hold ten copies. More in the npm, pnpm and Yarn comparison.
  • Program versions. python3 on a system is often an arrow to python3.12. Move the arrow and the version changes.
  • Configs. People keep settings in one folder under Git and drop links into their home directory.

A hard link is a different animal

There's also a hard link (ln without -s). One experiment shows the difference:

echo data > orig
ln -s orig sym    # symbolic
ln orig hard      # hard
rm orig
cat sym           # No such file or directory
cat hard          # data

A symbolic link stores a path. Delete the original and the path leads nowhere. That's called a broken link.

A hard link is a second name for the same data. The data lives as long as at least one name does. That's how pnpm lays out the package files themselves. The catch: a hard link can't point at a folder and can't cross to another disk.

Three traps everyone hits

A relative path counts from the link, not from you. This looks right and creates a broken link:

ln -s d1/f.txt d2/bad
cat d2/bad   # No such file or directory

The link stores d1/f.txt, and the system looks for it next to the link, in d2. It isn't there. The fix is to write the path from where the link lives: ln -s ../d1/f.txt d2/good.

The trailing slash when deleting. Back to the opening. Delete like this, no slash and no -r:

rm ld        # removes only the sign

rm -r ld/ goes inside and clears the real folder.

Some commands replace the link with a file. Try it: sed -i on a link doesn't change the original. It writes a regular file and puts it where the link was. The original stays old and the link is gone. If an edit "didn't apply," check ls -l.

A similar trap lives in tools: Prettier, for example, doesn't follow links when expanding file paths. A folder attached through a link simply won't get formatted.

Two short commands find broken links in a project and show where an arrow really leads:

find . -xtype l        # broken links
readlink -f CLAUDE.md  # the target's real path

How is a symlink different from a Windows shortcut?

A .lnk shortcut is mostly understood by Explorer. To programs it's an ordinary file. A symlink works at the file system level, so a program doesn't even notice it. Windows has symlinks too, but they need Developer Mode or admin rights.

How does Git store symbolic links?

Git saves the path itself, not the target's contents. Clone on Linux or Mac and you get a link. On Windows without the right permissions, you get a text file with the path inside.

How much space does a symlink take?

Practically none: it only stores a short path. The size in ls -l is the length of the path in bytes. For CLAUDE.md -> AGENTS.md that's 9.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →