When are org-mode attachments preferable to file hyperlinks?

Question

As far as I can tell, org-mode attachments solve the same problem as do file hyperlinks but in a clunkier way. In what situations would attachments be the superior solution?

Answer 1

Sometimes a hyperlink might be to something ephemeral like a log file or a file editable by others. Attachments allow you to permanently capture the current state of the file in a way more convenient than you manually copying the file into a good location and linking to it.

This might also extend to Internet accessibility. If you want access to a file without Internet access, you can attach it to your org file.

But conversely, attachments can soft-link to a location whereas hyperlinks can't store a local copy. When attachments soft-link to a document (C-c C-a y), org-mode will create a symbolic link to the file if possible on your operating system (equivalent to ln on a *nix system). The other methods (C-c C-a c/m/l) provide other behaviour. The default (C-c C-a a) is one of these, as set by org-attach-method.

You can also specify the attachment directory and populate that directory. org-attach-sync then synchronizes your attachment metadata so the headline is aware of the new files. You can't do this with hyperlinks without globbing or scripting.

You can get a list of all the attached files via org-attach-file-list, which allows you to iterate over them all and do useful things like copy to a Dropbox folder or store in git. Iterating over hyperlinks in a section is much more difficult and error-prone.

Another reason to consider attachments over hyperlinks is that they associate a link to an org headline, without you having to put it in the text. The attachment metadata is stored in a property drawer which can be hidden with TAB.

Hyperlinks have to exist in the text generally in the form [[file:somefile.pdf][My file]]. You could potentially hide this hyperlink in a property as well, but then you're more-or-less replicating org-attach without the ease-of-use.

In short, while hyperlinks can associate other documents to a heading, org-attach makes this association stronger, more robust and in some ways easier to use.

Edited: Added clarification.

Answer 2

One major advance of using attachements over links is that org-mode can take care of commiting any changes to the attached file if they are under version control, Quote from the Manual:

[...] If you initialize this directory [the one where the attachement resides in] with git init, Org will automatically commit changes when it sees them.

(added italics for explanation).

If used properly, the attachement feature ensures that the attached files are always up to date and accompagny the .org file.

I'd say that using links is a better choice if you

• don't want to commit files with the .org on every change / ever
• have a mixture of files which could be attached and some which should never be attached (hence, for consistency you don't use attachements)
• are already working under version control and / or don't need the auto-commit functionality

To me, attachements are kind of the dwim (do-what-I-mean) approach to files which are to be included or are referenced in an .org file.