14.8.2.5 :dir and remote execution

While the :file header argument can be used to specify the path to the output file, :dir specifies the default directory during code block execution. If it is absent, then the directory associated with the current buffer is used. In other words, supplying :dir path temporarily has the same effect as changing the current directory with M-x cd path RET, and then not supplying :dir. Under the surface, :dir simply sets the value of the Emacs variable default-directory.

When using :dir, you should supply a relative path for file output (e.g., :file myfile.jpg or :file results/myfile.jpg) in which case that path will be interpreted relative to the default directory.

In other words, if you want your plot to go into a folder called Work in your home directory, you could use

#+BEGIN_SRC R :file myplot.png :dir ~/Work
matplot(matrix(rnorm(100), 10), type="l")
#+END_SRC

Remote execution

A directory on a remote machine can be specified using tramp file syntax, in which case the code will be evaluated on the remote machine. An example is

#+BEGIN_SRC R :file plot.png :dir /[email protected]:
plot(1:10, main=system("hostname", intern=TRUE))
#+END_SRC

Text results will be returned to the local Org mode buffer as usual, and file output will be created on the remote machine with relative paths interpreted relative to the remote directory. An Org mode link to the remote file will be created.

So, in the above example a plot will be created on the remote machine, and a link of the following form will be inserted in the org buffer:

[[file:/scp:[email protected]:/home/dand/plot.png][plot.png]]

Most of this functionality follows immediately from the fact that :dir sets the value of the Emacs variable default-directory, thanks to tramp. Those using XEmacs, or GNU Emacs prior to version 23 may need to install tramp separately in order for these features to work correctly.

Further points

• If :dir is used in conjunction with :session, although it will determine the starting directory for a new session as expected, no attempt is currently made to alter the directory associated with an existing session.
• :dir should typically not be used to create files during export with :exports results or :exports both. The reason is that, in order to retain portability of exported material between machines, during export links inserted into the buffer will not be expanded against default directory. Therefore, if default-directory is altered using :dir, it is probable that the file will be created in a location to which the link does not point.