Variable: org-file-apps
org-file-apps is a customizable variable defined in org.el.gz.
Value
((auto-mode . emacs) (directory . emacs) ("\\.mm\\'" . default)
("\\.x?html?\\'" . default) ("\\.pdf\\'" . default))
Documentation
Applications for opening file:path items in a document.
Org mode uses system defaults for different file types, but you can use this variable to set the application for a given file extension. The entries in this list are cons cells where the car identifies files and the cdr the corresponding command.
Possible values for the file identifier are:
"string" A string as a file identifier can be interpreted in different
ways, depending on its contents:
- Alphanumeric characters only:
Match links with this file extension.
Example: ("pdf" . "evince %s")
to open PDFs with evince.
- Regular expression: Match links where the
filename matches the regexp. If you want to
use groups here, use shy groups.
Example: ("\\\\.x?html\\\\\\='" . "firefox %s")
("\\\\(?:xhtml\\\\|html\\\\)\\\\\\='" . "firefox %s")
to open *.html and *.xhtml with firefox.
- Regular expression which contains (non-shy) groups:
Match links where the whole link, including "::", and
anything after that, matches the regexp.
In a custom command string, %1, %2, etc. are replaced with
the parts of the link that were matched by the groups.
For backwards compatibility, if a command string is given
that does not use any of the group matches, this case is
handled identically to the second one (i.e. match against
file name only).
In a custom function, you can access the group matches with
(match-string n link).
Example: ("\\\\.pdf::\\\\([0-9]+\\\\)\\\\\\='" . "evince -p %1 %s")
to open [[file:document.pdf::5]] with evince at page 5.
Likely, you will need more entries: without page
number; with search pattern; with
cross-reference anchor; some combination of
options. Consider simple pattern here and a
Lisp function to determine command line
arguments instead. Passing an argument list to
call-process or make-process directly avoids
treating some character in peculiar file names
as shell specials that prompt parts of said file
names to be executed as subcommands.
directory Matches a directory
remote Matches a remote file, accessible through tramp.
Remote files most likely should be visited through Emacs
because external applications cannot handle such paths.
auto-mode Matches files that are matched by any entry in auto-mode-alist,
so all files Emacs knows how to handle. Using this with
command emacs will open most files in Emacs. Beware that this
will also open html files inside Emacs, unless you add
("html" . default) to the list as well.
system The system command to open files, like open on Windows
and macOS, and mailcap under GNU/Linux. This is the command
that will be selected if you call org-open-at-point with a
double prefix argument (C-u C-u C-c C-o).
t Default for files not matched by any of the other options.
Possible values for the command are:
emacs The file will be visited by the current Emacs process.
default Use the default application for this file type, which is the
association for t in the list, most likely in the system-specific
part. This can be used to overrule an unwanted setting in the
system-specific variable.
system Use the system command for opening files, like "open".
This command is specified by the entry whose car is system.
Most likely, the system-specific version of this variable
does define this command, but you can overrule/replace it
here.
mailcap Use command specified in the mailcaps.
string A command to be executed by a shell; %s will be replaced
by the path to the file.
function A Lisp function, which will be called with two arguments:
the file path and the original link string, without the
"file:" prefix.
For more examples, see the system specific constants
org-file-apps-macos
org-file-apps-windowsnt
org-file-apps-gnu.
This variable was added, or its default value changed, in Org version
9.4.
Source Code
;; Defined in /usr/src/emacs/lisp/org/org.el.gz
(defcustom org-file-apps
'((auto-mode . emacs)
(directory . emacs)
("\\.mm\\'" . default)
("\\.x?html?\\'" . default)
("\\.pdf\\'" . default))
"Applications for opening `file:path' items in a document.
\\<org-mode-map>
Org mode uses system defaults for different file types, but you
can use this variable to set the application for a given file
extension. The entries in this list are cons cells where the car
identifies files and the cdr the corresponding command.
Possible values for the file identifier are:
\"string\" A string as a file identifier can be interpreted in different
ways, depending on its contents:
- Alphanumeric characters only:
Match links with this file extension.
Example: (\"pdf\" . \"evince %s\")
to open PDFs with evince.
- Regular expression: Match links where the
filename matches the regexp. If you want to
use groups here, use shy groups.
Example: (\"\\\\.x?html\\\\\\='\" . \"firefox %s\")
(\"\\\\(?:xhtml\\\\|html\\\\)\\\\\\='\" . \"firefox %s\")
to open *.html and *.xhtml with firefox.
- Regular expression which contains (non-shy) groups:
Match links where the whole link, including \"::\", and
anything after that, matches the regexp.
In a custom command string, %1, %2, etc. are replaced with
the parts of the link that were matched by the groups.
For backwards compatibility, if a command string is given
that does not use any of the group matches, this case is
handled identically to the second one (i.e. match against
file name only).
In a custom function, you can access the group matches with
(match-string n link).
Example: (\"\\\\.pdf::\\\\([0-9]+\\\\)\\\\\\='\" . \
\"evince -p %1 %s\")
to open [[file:document.pdf::5]] with evince at page 5.
Likely, you will need more entries: without page
number; with search pattern; with
cross-reference anchor; some combination of
options. Consider simple pattern here and a
Lisp function to determine command line
arguments instead. Passing an argument list to
`call-process' or `make-process' directly avoids
treating some character in peculiar file names
as shell specials that prompt parts of said file
names to be executed as subcommands.
`directory' Matches a directory
`remote' Matches a remote file, accessible through tramp.
Remote files most likely should be visited through Emacs
because external applications cannot handle such paths.
`auto-mode' Matches files that are matched by any entry in `auto-mode-alist',
so all files Emacs knows how to handle. Using this with
command `emacs' will open most files in Emacs. Beware that this
will also open html files inside Emacs, unless you add
(\"html\" . default) to the list as well.
`system' The system command to open files, like `open' on Windows
and macOS, and mailcap under GNU/Linux. This is the command
that will be selected if you call `org-open-at-point' with a
double prefix argument (`\\[universal-argument] \
\\[universal-argument] \\[org-open-at-point]').
t Default for files not matched by any of the other options.
Possible values for the command are:
`emacs' The file will be visited by the current Emacs process.
`default' Use the default application for this file type, which is the
association for t in the list, most likely in the system-specific
part. This can be used to overrule an unwanted setting in the
system-specific variable.
`system' Use the system command for opening files, like \"open\".
This command is specified by the entry whose car is `system'.
Most likely, the system-specific version of this variable
does define this command, but you can overrule/replace it
here.
`mailcap' Use command specified in the mailcaps.
string A command to be executed by a shell; %s will be replaced
by the path to the file.
function A Lisp function, which will be called with two arguments:
the file path and the original link string, without the
\"file:\" prefix.
For more examples, see the system specific constants
`org-file-apps-macos'
`org-file-apps-windowsnt'
`org-file-apps-gnu'."
:group 'org
:package-version '(Org . "9.4")
:type '(repeat
(cons (choice :value ""
(string :tag "Extension")
(const :tag "System command to open files" system)
(const :tag "Default for unrecognized files" t)
(const :tag "Remote file" remote)
(const :tag "Links to a directory" directory)
(const :tag "Any files that have Emacs modes"
auto-mode))
(choice :value ""
(const :tag "Visit with Emacs" emacs)
(const :tag "Use default" default)
(const :tag "Use the system command" system)
(string :tag "Command")
(function :tag "Function")))))