Demystifying `hook://file/` links

Discussion & Help
1

We’ve published a web page that explains Hookmark’s file links ( hook://file/ links).

Why this matters

Robust file linking isn’t just a technical nicety—it fundamentally changes how you work. When links don’t break, you stop worrying about where files live and start focusing on what they mean and how they relate to each other. That’s the difference between managing files and managing knowledge.

Hookmark’s hook://file/ links are designed for real-world workflows: evolving projects, refactored folders, shared repositories, cloud sync, collaboration, and long-lived archives. They let you confidently connect files to emails, tasks, notes, research papers, and web resources—knowing those connections will still work weeks, months, or years later.

This is why Hookmark isn’t just a bookmarking tool or a convenience utility. It’s infrastructure for ubiquitous linking on macOS: a reliable foundation for building, revisiting, and sharing meaningful context across your work.

2

Great! The page does tell us that if we rename or move a file for which we created a hook file link, Hookmark will know how to find it despite the changes. And true enough, if I rename the file very differently and move it in another folder, Hookmark still knows how to resolve the link.

How does that work? Does Hookmark attach some hidden metadata to the file to help Spotlight find it even after a rename? I think I already read a technical explanation a few years ago. I remember I never was sufficiently convinced that Hookmark wouldn’t fail me someday for hook file links.

What would it take for it to fail me, what are the limits, what should I never do?

Answers to these questions might put to rest some fears. Thanks!

3

No. In early (2015-2016) internal implementations of Hookmark (then known internally as “myMeta”, a name we still use internally) we used that method but it had many drawbacks (e.g., duplicating files; xattributes not being kept in version control systems and Dropbox, etc).

We don’t want to discuss implemation details. We we want to say is that this functions like an alias but better. The logic is complex. The help page and this post of mine provide enough info to understand what is happening functionally.

What would it take for it to fail me, what are the limits, what should I never do?

There’s this case, which is not really failure but user misunderstanding. If you “move” a file from one Volume to another it might fail. But that is not really a move, it’s a copy and (possible) delete operation. In macOS you can’t move files across volumes. You can just copy and delete. But Hookmark has tricks even for that.

You also want to make sure that Spotlight is indexing volumes where Hookmark is supposed to track files. (That’s relevant to import/export, and recovering from backups.)

Also in

Be sure you’re not excluding volumes containing files you want Hookmark to track.

I remember I never was sufficiently convinced that Hookmark wouldn’t fail me someday for hook file links.

This has been working flawlessly since Hookmark was released in 2019 ; so I hope we have gained the trust of the market :wink:.

1 Like
4

Thanks for the detailed response, Luc.

Ok, I’ve been thinking about it and I realize I’m typically more comfortable when I can evaluate such details for myself to make an informed decision and to know the constraints implied by it, whereas you seem to be calling to make a faith decision based on Hookmark’s good reputation and the absence of complaints about this e.g. in the forums.

Fair enough, it’s really true that Hookmark didn’t generate complaints about hook://file/ links stopping to work, so it’s been enough years now to establish that these links are remarkably resilient.

Now, please forgive me for harping on this some more… Following your response, I still felt the need to sharpen my intuitions of what could break and could very potentially happen to me, to see if I’m really fine with going ahead full stop with hook file links. And so I tried one more simple test. It confirmed (at least this specific time) that if the ID part of the link differs and the path or name part of the link also differ, then Hookmark loses the ability to resolve the correct file. And since I’m someone who quite often renames folders and files, I posit that I can be described as someone for whom those ID parts of the links are very, very important for the future of my hook file links.

But what if I do something that also breaks the ID part of my links?… I expect to migrate my stuff to a new mac soon. Will my migration preserve their ID, or not? I might be at risk (for the files that I migrate that have been renamed or re-path’ed since their hook://file URLs were saved somewhere). Is there a better and a worse way to migrate my stuff with regard to this? I was actually thinking about using the Migration Assistant for the first time (instead of setting the new mac from scratch and letting files sync in through iCloud).

5

Well, Apple doesn’t give much info about its aliases or symlinks.

if the ID part of the link differs

differs from what?

But what if I do something that also breaks the ID part of my links?…

what do you mean breaking the ID?

Will my migration preserve their ID, or not

that is an implementation detail. What that means is that it is not part of the functional spec that we publish. Implementation may change from time to time. So we speak abstractly. Hookmark has the permission to use all kinds of heuristics apart from the ID to map links to files.

If you go to a new Mac without using a clone (e.g., with Migration Assistant or Carbon Copy Cloner), then whenever Hookmark encounters a hook://file URL, it will need to use the path information to map the link to a particular file. It will try its best to do this based on the path and name of the file as encoded in the hook://file/ URL.

We have stated a few relevant facts in Hookmark’s documentation regarding Hookmark’s process for resolving hook://file/ URLs.

there is: in Advanced Preferences – Hookmark a section named “Prevent Hookmark from searching specified locations”. that is relevant to your question.

We also state that for the resolution to work for a given hook://file/ URL in the case of migration or when one person sends a hook://file/ link to another, spotlight must index the folder in which the target file resides.

We have also always stated in the forum and the documentation that this is a heuristic process. You can search for “heuristic” and “file” on https://hookproductivity.com to see our claims re this. That is because what the user in his head considers to be the file that this hook://file/ links points to is a virtual concept that is open to interpretation. What same means is up to the software to determine based on what we have published. However, if there are two files with nearly identical names and path in reach and Hookmark can’t decide which the URL should refer to it, under some conditions Hookmark will ask the user to resolve the file for it. That works for hook://file/ URLs that are encountered one off. If Hookmark is processing thousands of files, it is not practical to to popup a dialog box for each. In these cases, Hookmark goes the best effort route.

That is why Hookmark has that advanced preference pane, to give the user the control over how hook://file/ URLs are resolved.

This is extremely more robust and open than Finder aliases and symlinks are. I hope this helps. There’s not much more to add than this.

1 Like
6

I now have migrated to the new Mac, using Migration Assistant.

My test file link still works. And since it does, knowing that the path and filename are different (remember my test to move the file in another folder and rename it), it implies that the ID of the file didn’t differ due to the migration. Nice!

Obviously, since the file link is made of 3 component parts (ID, path and filename), if I test a different ID (simulating it by altering its value in the link!!), Hookmark has no real information anymore about the file’s coordinates, and opens up another file.

So this is why I wanted to know and understand the circumstances under which this ID can change, since I often move and rename files (I expect especially the path to change over the lifetime of each file); I need to be cautious about what happens to my files so that their ID doesn’t change. Given this, the best, in my mind, would be if somehow, magically, all my text-based hook file links could be updated wherever they have been written to, and whenever I move or rename a file - a ludicrous proposition, an intractable requirement for a heterogeneous system of tools which Hookmark is merely tasked to integrate.

Now, thinking about this famous ID… is it just some kind of UUID created by e.g. Spotlight (a single point of failure), or is it itself created by Hookmark and made of several component parts to dynamically guide Hookmark’s heuristic capabilities? I don’t expect you to answer this question in details, but if it was the latter, and I now guess it is, then I’d feel better. I could say that these file links are not made of 3 atomic components, but in reality, of 3 components, of which the first one is itself composed of parts of which some of them can break, but some of them can be more resilient to changes, and even sometimes evolve compatibly over time as Hookmark needs and finds ways to improve its heuristic capabilities. So if I can think of this ID as a bitmap of sorts about the file, I become quite happier about Hook file links.

Whew, sorry for the ride. :sweat_smile: Some of us are probably thinking like me about this, so it might help to put it out there like I did.

7

If the internal reference to the file fails for some reason, a new bookmark may be created for it. We can tell you that it is at least as reliable as an alias, and I’ve already told you in which way it is more reliable. That’s it. You have as much information as the QA, product management and customer documentation team have about this feature. Pretty much end of story.