It is often useful to associate reference material with an outline node/task. Small chunks of plain text can simply be stored in the subtree of a project. Hyperlinks (see Hyperlinks) can establish associations with files that live elsewhere on your computer or in the cloud, like emails or source code files belonging to a project. Another method is attachments, which are files located in a directory belonging to an outline node. Org uses directories named by the unique ID of each entry. These directories are located in the ‘data/’ directory which lives in the same directory where your Org file lives89. If you initialize this directory with ‘git init’, Org automatically commits changes when it sees them. The attachment system has been contributed to Org by John Wiegley.
In cases where it seems better to do so, you can attach a directory of your choice to an entry. You can also make children inherit the attachment directory from a parent, so that an entire subtree uses the same attached directory.
The following commands deal with attachments:
The dispatcher for commands related to the attachment system. After these keys, a list of commands is displayed and you must press an additional key to select a command:
Select a file and move it into the task’s attachment
directory. The file is copied, moved, or linked, depending
org-attach-method. Note that hard links are not
supported on all systems.
Attach a file using the copy/move/link method. Note that hard links are not supported on all systems.
Create a new attachment as an Emacs buffer.
Synchronize the current task with its attachment directory, in case you added attachments yourself.
Open current task’s attachment. If there is more than one,
prompt for a file name first. Opening follows the rules set
org-file-apps. For more details, see the information
on following hyperlinks (see Handling Links).
Also open the attachment, but force opening the file in Emacs.
Open the current task’s attachment directory.
Also open the directory, but force using Dired in Emacs.
Select and delete a single attachment.
Delete all of a task’s attachments. A safer way is to open the directory in Dired and delete from there.
Set a specific directory as the entry’s attachment directory. This works by putting the directory path into the ‘ATTACH_DIR’ property.
Set the ‘ATTACH_DIR_INHERIT’ property, so that children use the same directory for attachments as the parent does.
It is possible to attach files to a subtree from a Dired buffer. To
use this feature, have one window in Dired mode containing the file(s)
to be attached and another window with point in the subtree that shall
get the attachments. In the Dired window, with point on a file,
M-x org-attach-dired-to-subtree attaches the file to the
subtree using the attachment method set by variable
org-attach-method. When files are marked in the Dired window then
all marked files get attached.
Add the following lines to the Emacs init file to have C-c C-x a attach files in Dired buffers.
(add-hook 'dired-mode-hook (lambda () (define-key dired-mode-map (kbd "C-c C-x a") #'org-attach-dired-to-subtree)))
The following code shows how to bind the previous command with a specific attachment method.
(add-hook 'dired-mode-hook (lambda () (define-key dired-mode-map (kbd "C-c C-x c") (lambda () (interactive) (let ((org-attach-method 'cp)) (call-interactively #'org-attach-dired-to-subtree))))))
If you move entries or Org files from one directory to
another, you may want to configure
org-attach-directory to contain
an absolute path.