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.
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
~/.emacs.d/data/, where org-attach creates
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.
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
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
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
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,
Retrieving an attached file
C-c C-a f opens a listing of attached files for this node (org-attach-reveal).
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.
C-c C-a z synchronizes the current node and its
attachments. This is useful when you have manually added files to the
Links to the attachment
I have only added one single line to my
~/.emacs for working
(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
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.:
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
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.
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.