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.
Links to the attachment
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.
Made with ♥ by a human - Proud member of the 250kb.club.
Most recent pages
All tags
Sitemap
RSS
RSS of Gophersite