This document provides some of the functional details about Hookmark’s links to files.
Hookmark enables you to create links to files. Hookmark’s links to files look like this: hook://file/<id><?p=<encodedpath>?n=<encodedfilename>. Hookmark is capable of tracking the file to which its links point. This is a bit like how a Finder alias can track the location of a file. In fact, you can think of Hookmark’s file links as a link to an alias (though Hookmark’s file links have more functionality than aliases have). So (like an alias) if you move or rename the target file, Hookmark’s link will still work. This makes Hookmark’s file links different from standard file:// URLs, which point to an absolute or relative location, and which break if the target file moves.
How to create Hookmark file links (hook://file/… URLs)
Hookmark file links can be created via the following commands when they are applied to files:
Copy Link,Copy As Markdown Link,Hook to Copied Link,Hook to Copied Link, andHook to New
For each of these commands, when applied to files, Hookmark creates in its database corresponding bookmarks containing hook://file/ links.
When Hookmark creates a file link for you (typically by using the Copy Link command) Hookmark creates a link with the hook://file URL scheme. The URL encodes part of the path (i.e., location) of the file. This means that if you invoke Copy Link on a file, move the file around, and then Copy Link on it again, you’ll get two different URLs pointing to the same file.
After moving a file to which you have created a hook://file/ link, you can continue to use the link. Hookmark will track the target file.
The expression “Hookmark file links” and “hook://file/… links” are synonymous.
Activating Hookmark’s file links
Like other links, hook://file/ links can be stored inside Hookmark’s database, or they may have been pasted somewhere (by you or someone else), or both.
If you activate a hook://file/ that is stored outside of Hookmark (e.g., in a mail message or TextEdit document), then Hookmark will either open the target file or reveal it, depending on this General checkmark setting:
[ ]: Reveal hook://file link targets in Finder (rather than opening them)
Sometimes, Hookmark is uncertain to which particular file a hook://file/ link points. This can happen if the file is shared and has been moved on a different computer and if there is more than one file that has the same name as encoded in the hook://file/ URL. It can also happen after you switch to a new Mac or export and then import your hookmark database. In such a case, when you activate the hook://file/ link, Hookmark might present you with a dialog box with several potential matches, and ask you to choose which file to open.
If Hookmark believes it can resolve the URL to match a specific file,
and is confident about what the link points to, Hookmark will try to use that information to open the file.
Because file systems are very complex, and Hookmark’s file linking is even more complex than Finder aliases (using heuristics), sometimes the file that Hookmark opens or reveals may be different from what you expect.
However, as noted, if Hookmark finds multiple potential matches for a file, Hookmark may present you with a dialog box so that you can choose which file you want to open.
Sharing Hookmark’s file links
You can share Hookmark’s file links with others! Typical sharing scenarios are if you both (or all) have access to the same file which is stored in a cloud-sync folder (such as Dropbox or iCloud), on a network drive, or in a version control system like git.
If you send someone a hook://file/ link, when the user activates that link, their Hookmark will try to decode the link as described above (using name and path information encoded in the link), except that there will not be any corresponding tracking information in the user’s database.
Because the information encoded in the link is incomplete, and files can be moved or renamed in the cloud, when someone opens the hook://file/ link they could open a file that is not the same as intended (or the intention may not be completely clear). That is a consequence of the mechanism being heuristic. See the next section on further ways to mitigate this.
Better than aliases
Hookmark links are more robust than aliases. With Hookmark, for instance, one can on a different computer move an entire shared folder tree containing files to which hook://file/ links point. Hookmark will heuristically try to resolve the links.
An example use case for this is if you should move from one cloud storage solution to another (such as Dropbox or Sync.com). That would break your aliases, and of course your dropbox URLs would be useless.
Excluding directories from Hookmark’s hook://file/ resolving mechanisms
If you move to a new computer in a way that changes the macOS ID’s of files, or if you export as an archive and then import your Hookmark archive, Hookmark will need to rebuild its hook://file/ indexes. In the process , for each hook://file/ in the exported file (or in the database), Hookmark will search for a matching file. This can potentially lead Hookmark to associate some hook://file/ links to files other than what you prefer or intend. This is possible if you have files with the same name and matching directory structure.
To reduce the likelihood of this happening, before you import your Hookmark archive, you can exclude some files from Hookmark’s search algorithm. For instance, if you have a backup folder that duplicates your core working folder, you might want to exclude the backup folder from Hookmark’s reindexing process. You do this through the Prevent Hookmark from searching these locations: field of Hookmark’s Advanced Settings tab. Finder folders listed on the right will be ignored when Hookmark initially tries to resolve file links (hook://file/) at this point. That panel is not consulted once Hookmark has a resolved a hook://file/ URL. For more information, see the help page on the subject.
Hookmark links vs. Hookmark files
Not to be confused with the concept of Hookmark file links is the concept of Hookmark files.. A Hookmark file (i.e., a file ending with .hookmark) is a file that can contain any type of link, including hook://file/ URL. A hook://file/ URL is a URL that references any file.
Other hook:// URL schemes
Hookmark defines several other URL schemes, most notably the hook://email/ scheme discussed in How to Get and Use Links to Email Messages.
More generally, one of the objectives of Hookmark is to link the previously unlinkable; thus the slogan:
Hookmark supplies the missing links to your workflows.