Extracting source code from code blocks is a basic task in literate programming. Org has features to make this easy. In literate programming parlance, documents on creation are woven with code and documentation, and on export, the code is tangled for execution by a computer. Org facilitates weaving and tangling for producing, maintaining, sharing, and exporting literate programming documents. Org provides extensive customization options for extracting source code.
When Org tangles code blocks, it expands, merges, and transforms them. Then Org recomposes them into one or more separate files, as configured through the options. During this tangling process, Org expands variables in the source code, and resolves any noweb style references (see Noweb Reference Syntax).
The ‘tangle’ header argument specifies if the code block is exported to source file(s).
Export the code block to source file. The file name for the source file is derived from the name of the Org file, and the file extension is derived from the source code language identifier. Example: ‘:tangle yes’.
The default. Do not extract the code in a source code file. Example: ‘:tangle no’.
Export the code block to source file whose file name is derived from any string passed to the ‘tangle’ header argument. Org derives the file name as being relative to the directory of the Org file’s location. Example: ‘:tangle FILENAME’.
The ‘mkdirp’ header argument creates parent directories for tangled files if the directory does not exist. A ‘yes’ value enables directory creation whereas ‘no’ inhibits it.
The ‘comments’ header argument controls inserting comments into tangled files. These are above and beyond whatever comments may already exist in the code block.
The default. Do not insert any extra comments during tangling.
Wrap the code block in comments. Include links pointing back to the place in the Org file from where the code was tangled.
Kept for backward compatibility; same as ‘link’.
Nearest headline text from Org file is inserted as comment. The exact text that is inserted is picked from the leading context of the source block.
Includes both ‘link’ and ‘org’ options.
Includes ‘link’ option, expands noweb references (see Noweb Reference Syntax), and wraps them in link comments inside the body of the code block.
The ‘padline’ header argument controls insertion of newlines to pad source code in the tangled file.
Default. Insert a newline before and after each code block in the tangled file.
Do not insert newlines to pad the tangled code blocks.
The ‘shebang’ header argument can turn results into executable script files. By setting it to a string value—for example, ‘:shebang "#!/bin/bash"’—Org inserts that string as the first line of the tangled file that the code block is extracted to. Org then turns on the tangled file’s executable permission.
The ‘tangle-mode’ header argument specifies what permissions to set
for tangled files by set-file-modes. Permissions are given by an
octal value, which can be provided calling the identity function on
an elisp octal value. For instance, to create a read-only file one may
use ‘:tangle-mode (identity #o444)’. To reduce the verbosity required,
a octal shorthand is defined, ‘oXXX’ (‘o’ for octal). Using this, our
read-only example is ‘:tangle-mode o444’. Omitting the ‘o’ prefix will
cause the argument to be interpreted as an integer, which can lead to
unexpected results (‘444’ is the same as ‘o674’).
Two other shorthands are recognized, ls-style strings like
‘rw-r--r--’, and chmod-style permissions like ‘g+w’.
Note that chmod-style permissions are based on
org-babel-tangle-default-file-mode, which is ‘#o544’ by default.
When ‘:tangle-mode’ and ‘:shebang’ are both specified, the give ‘:tangle-mode’ will override the permissions from ‘:shebang’. When multiple source code blocks tangle to a single file with conflicting ‘:tangle-mode’ header arguments, Org’s behavior is undefined.
By default Org expands code blocks during tangling. The ‘no-expand’
header argument turns off such expansions. Note that one side-effect
of expansion by org-babel-expand-src-block also assigns values (see
Environment of a Code Block) to variables. Expansions also replace
noweb references with their targets (see Noweb Reference Syntax).
Some of these expansions may cause premature assignment, hence this
option. This option makes a difference only for tangling. It has no
effect when exporting since code blocks for execution have to be
expanded anyway.
org-babel-tangle ¶Tangle the current file. Bound to C-c C-v t.
With prefix argument only tangle the current code block.
org-babel-tangle-file ¶Choose a file to tangle. Bound to C-c C-v f.
org-babel-pre-tangle-hook ¶This hook is run before the tangle process begins. The active buffer is buffer to be tangled.
org-babel-tangle-body-hook ¶This hook is run from a temporary buffer containing expanded code of every tangled code block. The hook can modify the expanded code as needed. The contents of the current buffer will be used as actual code block expansion.
org-babel-post-tangle-hook ¶This hook is run from within code files tangled by
org-babel-tangle, making it suitable for post-processing,
compilation, and evaluation of code in the tangled files.
org-babel-tangle-finished-hook ¶This hook is run after post-tangle hooks, in the original buffer.
Debuggers normally link errors and messages back to the source code.
But for tangled files, we want to link back to the Org file, not to
the tangled source file. To make this extra jump, Org uses
org-babel-tangle-jump-to-org function with two additional source
code block header arguments: