What is the Unix command to create a hardlink to a directory in OS X?

How do you create a hardlink (as opposed to a symlink or a Mac OS alias) in OS X that points to a directory? I already know the command "ln target destination" but that only works when the target is a file. I know that Mac OS, unlike other Unix environments, does allow hardlinking to folders (this is used for Time Machine, for example) but I don't know how to do it myself.

I agree that hard-linking folders/directories can cause problems if not careful, but they have a very definite advantage - Time Machine is a perfect example. Without them it simply would not be practical as the duplication of redundant versions of files would very quickly consume even the largest of disks.

Snow Leopard can create hard links to directories as long as you follow Amit Singh's six rules:

1. The file system must be journaled HFS+.
2. The parent directories of the source and destination must be different.
3. The source’s parent must not be the root directory.
4. The destination must not be in the root directory.
5. The destination must not be a descendent of the source.
6. The destination must not have any ancestor that’s a directory hard link.

So it's not correct at all that Snow Leopard has lost the ability to create hard links to folders.

I just verified that link/unlink do work on Snow Leopard - as long as you follow the six rules. I just tried it and it works fine on my Snow Leopard 10.6.6 system - tried it on the boot volume and on a separate USB external volume and it worked fine in both cases.

Here is the "hunlink.c" program:

#include <stdio.h>
#include <unistd.h>
int
main(int argc, char *argv[])
{
   if (argc != 2)
      return 1;
   int ret = unlink(argv[1]);
   if (ret != 0)
      perror("unlink");
   return ret;
}

gcc -o hunlink hunlink.c

So, be careful if you try it - remember to follow the rules and use hlink to create these hard links and use hunlink to remove the hard link afterwards. And don't forget to document what you've done for later on or for someone else who might need to know this.

One other "gotcha" that I just learned about these "hard links" to folders. When you create them there is really a lot that happens "behind the curtain" of Mac OS X. One really important issue is that the folder you create the link to is really moved to a super-magical super-hidden folder called /.HFS+ Private Directory Data%000d/dir_xxx where xxx is the inode number of the "source_folder" - remember the format of the command is

hlink source_folder target_folder

So because of this, you have to be careful of not having any files open in the "source_folder" because if you do, they just got moved to the super-magical folder and you will likely have a problem if you try and save any changes to those files that were open in the "source_folder". This happened to me a couple of times until it dawned on me what was happening and the solution is pretty simple. I noticed that you couldn't do a "ls -la" command any longer without getting funny errors for all the folders/directories that were in the original "source_folder" but you could do a "ls" command and all looked well.

If you run "Verify disk" in the "Disk Utility" program, you will notice that it probably complains and gives a "Volume bitmap needs minor repair for orphaned blocks" which is what just happened with the creation of the super-magical folder and the movement of the "source_folder" to it.

If you do find yourself in this situation with "orphaned blocks", first save the changed files to some other temporary location not in the volume containing the "source_folder" tree, then use "Disk Utility" to unmount and remount the volume that contains the "source_folder" or just restart the computer. Then copy the files you saved to the temporary locations back to their original locations and you should be back in business. This is what worked for me, so can't guarantee this will work for you too. So it might be a good idea to try this out on a volume you have a good backup of just in case.

It seems so very weird that all this overhead occurs just for the simple task of creating a hard link to a folder. Does anyone have any idea why Mac OS X goes to all this effort for this hard link creation to folders? Does it have something to do with the fact that this is a "journaled" file system?

I discovered the info about the super-magical, super-hidden location by reading Amit Singh's explanation of his "hfsdebug" utility. If you want more details see his web site at Amit Singh's hfsdebug utility. It's a very interesting piece of software and will tell you lots of details about HFS+ file systems. It's free and I encourage you to download it and try it out. It's no longer supported but it still works on both Snow Leopard and Leopard - basically any HFS+ supported system. You can't really do any harm with it as it's a "read-only" tool - so it's great to use to look at some details of the filesystem.

One more issue about these "hard links to folders" - once you create one and the super-magical super-secret-hidden folder gets created, it's there for good. Even if you unlink the folder that caused it to be created in the first place, this magic folder stays around. Not sure why, but it definitely does. You can use "hfsdebug" to find this out if you wish to try it out. You can also use "hfsdebug" to find out how many of these "hard links to folders" exist on a drive. For these details refer to Amit's article on the "hfsdebug" utility.

He also has another newer utility that's supported but costs. It's called fileXray and costs $79 for one person on any number of computers in the same household for a personal non-business type license. It has an extensive 173-page User Guide that you can download to see what it can do before you purchase. Unfortunately there is no trial version, so read the manual and check out the web site for more details to see if it can help you out of a jam. Learn all the details about it at their web site - see fileXray web site for more info.

There are a couple of issues you should be aware of when using these hard links to folders. If the volume that they are created on is mounted to a remote client, there can be significant problems, depending on how they are mounted. If you use AFP to mount the volume to a remote client, there are big problems as any folder that currently has a hard link to it or has ever had one but later removed, will be unable to be used as all the lower level folders (but not files) will be inaccessible from either the Finder or a Terminal window. If you try to do a simple "ls -lR" command, it will fail and give you "ls: xxx: No such file or directory" error messages for all lower level folders. If you use a Finder window to traverse the directory tree of the remote volume, the folders that are in the folder that had or has a hard link to it will simply disappear without any error when you first click on the folder name.

These problems don't appear to occur (except for the error message) if you use NFS to mount the remote client (and assuming you had a NFS server on the system that has the volume as a local HFS+ filesystem). Details on how to use NFS to mount volumes are not provided here. I used a nice program from Dr. Marcel Bresink called "NFS Manager" to help with the NFS mounts on the server and client. You can get it from his web site - just search for "Bresink NFS Manager" in your favorite search engine, but he has a free trial version so you can try before you buy. It's not that big a deal if you want to learn how to do the NFS mounts, but the "NFS Manager" makes it pretty easy to set things up and to tweak all the different settings to help optimize it. He has several other neat Mac OS X utilities too that are very reasonably priced - one called "Hardware Monitor" that lets you monitor and graph all kinds of things like power usage, temperature of CPU, speed of fans and many many other variables for both the local and remote Mac systems over extended periods of time (from minutes to days). Definitely worth checking out if you are into handy utilities.

One thing I did notice is that NFS file transfers were about 20% slower than doing them via AFP, but your "mileage may vary", so no guarantees one way or the other, but I would rather have something that works even if I have to pay a 20% performance hit as compared to having nothing work at all.

Apple is aware of the problems with hard links and remote AFP filesystems, and they refer to it as an "implentation limitation" of the AFP client - I prefer to call it what it really appears to me to be - A BUG!!! I can only hope the next release of Mac OS X fixes the problem, as I really like having the ability to use hard links to folders when it makes sense.

These notes are my own personal opinion and I don't make any warranty about their correctness so use them at your own risk. Have a good backup before you play around with these "hard links to folders" just in case something unforeseen happens. But I hope you have fun if you do decide to look a bit more into this interesting aspect of Mac OS X.

You can't do it directly in BASH then. However... I found an article here that discusses how to do it indirectly: http://www.mactech.com/articles/mactech/Vol.23/23.11/ExploringLeopardwithDTrace/index.html by compiling a simple little C program:

#include <unistd.h>
#include <stdio.h>

int main(int argc, char *argv[])
{
   if (argc != 3) return 1;

   int ret = link(argv[1], argv[2]);

   if (ret != 0) perror("link");

   return ret;
}

...and build in Terminal.app with:

$ gcc -o hlink hlink.c -Wall

Piffle. On 10.5, it tells you in the man page for ln:

   -d, -F, --directory
          allow the superuser to attempt to hard link  directories  (note:
          will  probably  fail  due  to  system restrictions, even for the
          superuser)

So yes:

    sudo  ln  -d  existing_dir  new_hard_link

Give it your password, and you're not done yet. You didn't document it, did you? You must document hard linked directories; even if it's a single user machine.

Deleting is a different story: if you go about it the usual way to delete directories, you'll delete the contents. So you must "unlink" the directory:

    unlink  new_hard_link

There. Hope you don't wreck your filesystem!

Cross-posting this great tool which neatly solves the problem, originally posted by Sam:

---

To install Hardlink, ensure you've installed homebrew, then run:

brew install hardlink-osx

Once installed, create a hard link with:

hln [source] [destination]

I also noticed that unlink command does not work on snow leopard, so I added an option to unlink:

hln -u destination

---

Code is available on Github for those who are interested: https://github.com/selkhateeb/hardlink

Yes it's supported by the kernel and the filesystem, but since it's not intended for general usage it's not exposed to the shell.

You could probably work out which APIs Time Machine uses and wrap them in a commandline tool, but it'd be better to take the hint and steer well-clear.

The OSX version of ln cannot do it, but, as mentioned in the other answer by rich, it is possible with the GNU version of ln which is available in homebrew as gln as part of the coreutils formula. man gln lists the -d option with the OSX-specific warning provided in rich's answer. In other words, it does not work in all cases. What exactly determines whether it works or not does not seem to be documented anywhere.

As a prerequisite, install coreutils:

    brew install coreutils

Now you can do:

    sudo gln -d /original_folder /mirror_folder

IMPORTANT: To remove the hard link you must use gunlink:

    sudo gunlink /mirror_folder

> ❗️❗️❗️ Using rm or Finder will also delete the original folder.

FYI: The coreutils homebrew formula provides the GNU-compatible versions of generic unix tools. Use brew list coreutils to see the full list.

As of 2018 no longer possible. APFS (introduced in MacOS High Sierra 10.13) is not compatible with directory hardlinks. See https://github.com/selkhateeb/hardlink/issues/31

My case was that I found out that from a windows virtual machine, I cannot follow symlinks. (i wanted to test some HTML pages in Internet Explorer). And my directory structure had symlinks for CSS and images folders.

My workaround to solve the problem was a different approach than the other answers implied. I used rsync to create a copy of the folder. Rsync can resolve the symlinks and copy the linked files in stead.

This solved my problem without using hard links to directories. And it's actually an easy solution if you're just working on a small set of files.

rsync -av --copy-dirlinks --delete ../htmlguide ~/src/

From the article linked to, you'll get that error if you try to create the hard link in the same directory as the original. You have to create it somewhere else.

In Linux you can use bind mount to simulate hard linking directories. Not sure about OSX

sudo mount --bind /some/existing_real_contents /else/dummy_but_existing_directory
sudo umount /else/dummy_but_existing_directory

This can also be done with built-in Perl (from Terminal) without compiling anything. My specific use case is for Google Drive (which doesn't support symbolic links), so the examples below reflect the use case.

To link your "Documents" folder to Google Drive so it's synced:

perl -e 'link "/Users/me/Documents", "/Users/me/Google Drive/Documents"'

To remove the link to your "Documents" folder from Google Drive:

sudo perl -U -e 'unlink "/Users/me/Google Drive/Documents"'

You need "root" to unlink (see "unlink" perldoc).

Another solution is to use bindfs https://code.google.com/p/bindfs/ which is installable via port:

sudo port install bindfs
sudo bindfs ~/source_dir ~/target_dir

The short answer is you can't. :) (except possibly as root, when it would be more accurate to say you shouldn't.)

Unixes only allow a set number of links to directories - ".." from within all its children and "." from within itself. Anything else is potentially a recipe for a very confused directory tree. This is/was apparently a design decision by Ken Thompson.

(Having said that, apparently Apple's Time Machine does do this :) )

in case there is no sub folder, you can try

ln folder_path/. target_folder

it worked for me on OSX 10.9