box.matto.nl
Enjoying Open Source Software

Posted:

Using org-attach in Emacs org-mode

Use org-attach to create an independent structure for your notes and files

org-attach is a great method to link files to your org-mode notes, and org-mode todos.

These attachments can be of any type, f.e., a PDF, an image, a text file, or even another org file.

The attachments are linked to headers in your org-file. You can link any attachment to any header.

org-attach links the file to the header of the current node. It offers several different ways to create a connection between your org-file and the file to attach, like copying the file, moving the file, creating a symlink, or a hard link, and others.

The most robust way is to copy or to move the file. The location where the attachment is copied to, or moved to, depends on the configuration of the org-attach attachment directory.

Attachment directory

The default way to store the copy of the file is in a directory-tree under the sub-directory data, which is created in the directory where the org-file is located.

Another option is to create a specific directory for all your attachments, f.e. ~/.emacs.d/data/, where org-attach creates its directory-tree.

Node ID

org-attach uses an ID to establish the link between the node and the attachment. The first time you create an attachment for a node, org-attach creates a property-drawer for the heading of the node, and places an ID in it, using an UUID.

Here is an example:

** Example header
:PROPERTIES:
:ID:       1B02325F-2989-45CC-AEDF-0B2C942DC1D1
:END:

Directory-tree within in the attachment directory

org-attach creates a directory-tree within the attachment directory.

First, it creates a directory with the name of the first two characters of the UUID, in the above example "1B".

Next, it creates a sub-directory within this directory, with the name of the remainder of the UUID, in the above example "02325F-2989-45CC-AEDF-0B2C942DC1D1".

It places the attachment in this sub-directory.

The end result is something like this:

.
|-- data
|   |-- 1B
|   |   `-- 02325F-2989-45CC-AEDF-0B2C942DC1D1
|   |       |-- my-first-attachment.pdf
|   |       `-- my-second-attachment.pdf
|   |-- 52
|   |   `-- 245B02-4459-4CE4-81B6-D84DF86B0D33
...

org-attach adds a tag to your headline

org-attach adds a tag :ATTACH: to headline of the node, so you know there are one or more attachments for this node.

Default configuration

org-attach works right out of the box, without any configuration. As usual, the default configuration is already fine, and hardly needs any tinkering.

As mentioned above, in the default configuration org-mode creates a sub-directory data in the directory of your current org-mode file. The advantage of this is that you can sync the complete directory-tree to another computer, and everything keeps working.

In the default configuration, org-attach copies the file to the tree under the data directory. So, the original file is not touched.

This way, your org notes, together with the attachments, becomes independent from the rest of your system. Nothing breaks when you later move or delete the original file, your org note and the attachments are still fine.

Workflow in the default configuration

All the org-attach key bindings start with C-c C-a.

Attaching a file to node

Attach a file to your current node with C-c C-a a (org-attach-attach).

This will open a directory listing where you can choose a file. Select a file, org-attach will create a properties drawer and an UUID if needed, create the directory tree under the attachment directory if needed, and copy the file to this tree. It adds a tag :ATTACH: to the header of your current node..

Attach from Dired

Another option to attach files is to mark one or more files in Dired, followed by M-x org-attach-dired-to-subtree.

Retrieving an attached file

The command C-c C-a f opens a listing of attached files for this node (org-attach-reveal).

The command C-c C-a F (upper case F) opens the listing in Dired (org-attach-reveal-in-emacs).

Choose one of the files to open it.

Synchronize

The command C-c C-a z synchronizes the current node and its attachments. This is useful when you have manually added files to the directory-tree.

I have only added one single line to my ~/.emacs for working with org-attach:

(setq org-attach-store-link-p 'attached)

With this, you can add links to the attachment in the text of your node.

After adding a attachment with C-c C-a a you can use C-c C-l to insert a link to the attachment into to the text of your org file. This will become a link to the file in the directory-tree, f.e.:

[[attachment:myattachment.pdf][myattachment.pdf]]

As usual, edit the second part if you want to change the text that is shown.

When reading your org-note, hit Ret on the link to open the attachment, or C-u Ret to open the link in Emacs.

You don't need to add these links in the text of your org file, org-attach works perfectly fine without it. But I like the extra visibility.

When you have added several attachments to the same node, individual links makes retrieving an attachment faster.

More options

Of course, org-attach has a lot more to offer than described here. However, this is already a solid, workable system.

I have the complete tree, starting with the top directory with the org-files, in a git repository. Because of the default set up with the data directory within this tree, it has become an independent system.

A clone of this repository on another computer will work, with all the links between the org notes and the attachments in working order. It might need a synchronize command (C-c C-a z) the first time you use it.

Another option is to sync the directory with Syncthing, or use Nextcloud, Dropbox, or alternative, and use that to distribute it to other computers.

Tags:

⇽ New PGP key Use ERC and ZNC to chat on IRC with Emacs ⇾