org-runbook.el

Library for looking up and executing commands from org files corresponding to the current buffer.

Installation

Org-runbook is available on MELPA

M-x package-install [RET] org-runbook [RET]

Usage

Example

org-runbook lets you take org files structured like

MAJOR-MODE.org

* Build
#+BEGIN_SRC shell
cd {{project_root}}
#+END_SRC

** Quick
#+BEGIN_SRC shell
make quick
#+END_SRC

** Clean
#+BEGIN_SRC shell
make clean
#+END_SRC

** Prod
#+BEGIN_SRC shell
make prod
#+END_SRC

and exposes them for easy access in buffers with corresponding major mode. So, the function org-runbook-execute has the following completions when the current buffer's major mode is MAJOR-MODE:

Build >> Quick
Build >> Clean
Build >> Prod

Each of these commands is the concatenation of the path of the tree. So for example, Build >> Quick would resolve to:

cd {{project_root}}
make quick

If projectile-mode is installed, org-runbook also pulls the file named PROJECTILE-PROJECT-NAME.org.

All files in [org-runbook-files] are also pulled.

runbook org file search order

org-runbook search the org files for runbook in the following order.

Current File if the file is an org file.
org-runbook-project-directory/<project_name>.org
<project_root>/runbook.org
org-runbook-modes-directory/<major_mode>.org
org-runbook-files

The current search list can be seen by calling org-runbook-org-file-list

Eshell Support

Calling org-runbook from eshell with no args outputs the available commands

~ $ org-runbook

Any of the command names can be passed as an argument to org-runbook, and it will evaluate the corresponding command in eshell.

~ $ org-runbook 'Build >> Quick'

The view flag generates portable output for exporting from org-runbook to bash.

~ $ org-runbook --view 'Build >> Quick'

Placeholders

Commands will resolve placeholders before evaluating.

{{project_root}} - the projectile-project-root of the buffer that called `org-runbook-execute'
{{current_file}} - the file that the buffer that called org-runbook-execute was visiting. If the the buffer is a non file buffer, current_file is default-directory

Interactive Commands

org-runbook exposes a few commands meant to be example entry points using completing read.

org-runbook-ivy Prompt for command completion and execute the selected command. The rest of the interactive commands are accesible through this via the extra actions.
org-runbook-execute Prompt for command completion and execute the selected command.
org-runbook-view Prompt for command completion and view the selected command fully resolved.
org-runbook-goto Prompt for command completion and goto where the selected command is defined.

API

Commands

org-runbook-targets Return the runbook commands corresponding to the current buffer. Intended to provide completions for completing-read functions
org-runbook-execute-target-action Execute the command. Expects the command to be one of the elements of (org-runbook-targets)
org-runbook-view-target-action View the command. Expects the command to be one of the elements of (org-runbook-targets)
org-runbook-goto-target-action Switch to the file where the command is defined. Expects the command to be one of the elements of (org-runbook-targets)

Org Files

org-runbook-switch-to-projectile-file Switch current buffer to the file corresponding to the current buffer's projectile mode.
org-runbook-switch-to-major-mode-file Switch current buffer to the file corresponding to the current buffer's major mode mode.

Customization

org-runbook-files Global file list used by org runbook. When resolving commands for the current buffer, org-runbook appends org-runbook-files with the major mode org file and the projectile org file.
org-runbook-project-directory Directory used to lookup the org file corresponding to the current project. org-runbook-projectile-file joins org-runbook-project-directory with the projectile-project-name for the current buffer.
org-runbook-modes-directory Directory used to lookup the org file for the current major mode. org-runbook-major-mode-file joins org-runbook-modes-directory with the symbol-name of the major-mode for the current buffer.
org-runbook-view-mode-buffer Buffer used for org-runbook-view-command-action to display the resolved command.
org-runbook-execute-command-action Function called to handle executing the given runbook. It is provided as a single argument the plist output of org-runbook--shell-command-for-candidate.

Contributing

Contributions welcome, but forking preferred. I plan to actively maintain this, but I will be prioritizing features that impact me first.

I'll look at most pull requests eventually, but there is no SLA on those being accepted.

Also, I will only respond to pull requests on a case by case basis. I have no obligation to comment on, justify not accepting, or accept any given pull request. Feel free to start a fork that has more support in that area.

If there's a great pull request that I'm slow on accepting, feel free to fork and rename the project.

zkry / org-runbook