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".
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.
