Intro to Org Babel Tangle

April 21, 2019

I recently started making regular use of a feature in org-babel called org-babel-tangle, to create literate dotfiles. It's easy to use, and can make for very readable code.

For this blog, I'll use my exports.sh bash script as an example. I use this file to make sure my $PATH, $EDITOR, and $TERM environment variables are set correctly.

Everything below the break is copied over (with some minor editorialization) from my actual exports.org file. And since you can author gatsby content withorg markdown, I was able to just copy over the contents whole cloth.

To see the exact file I used for this post, see the raw text for this file, but don't forget that viewing org files from emacs is more pleasant experience than looking at the raw file.

Exports

To tangle this file, open it with spacemacs with the org layer enabled, then enter

,bt

This file should be sourced as soon as possible, since we want all child processes to have access to these exported variables.

  # This is effectively a compiled file. The source can be found in
  # ~/programming/dotfiles/dotfiles/exports.org

Since we symlink all of our scripts to ~/.local/bin, we want to make sure that they are visible.

  export PATH="$PATH":~/.local/bin

We also want to make sure that cargo bin is on our path since many of our executables end up there.

  export PATH="$HOME/.cargo/bin:$PATH"

In order for emacs to have 24-bit color in terminal mode, we need a combination of our terminfo entry and to set our term to be xterm-24bits

  export TERM=xterm-24bits

And speaking of editor, we want our editor to be emacsclient. The t flag opens a new Emacs frame on the current terminal. and the =-a ""= opens emacs in daemon mode, then connects to it.

  export EDITOR='emacsclient -t -a ""'

We want to have pretty dircolors as well. This will make sure that happens.

  eval "$(dircolors ~/programming/dotfiles/dotfiles/.dircolors)"

Result

After tangling the above source block, we're left with the following.

  #!/bin/bash
  # This is effectively a compiled file. The source can be found in
  # ~/programming/dotfiles/dotfiles/exports.org

  export PATH="$PATH":~/.local/bin

  export PATH="$HOME/.cargo/bin:$PATH"

  export TERM=xterm-24bits

  export EDITOR='emacsclient -t -a ""'

  eval "$(dircolors ~/programming/dotfiles/dotfiles/.dircolors)"

Takeaways

This is a simple example, but it shows the expressive power of org-bable-tangle. By creating files this way, I feel more encouraged to add in prose, explanations, and links to explain why I'm doing something. This is especially useful for dotfiles since I often go months or years without making changes to them. By having explanations of why I'm doing something, it's much easier for me to come back later and understand what's going on.