Table of Contents

Captured Output

WARNING: This document is for an older version of iTerm2.

iTerm2 has a feature called "Captured Output" which helps you find and track important lines of output from logs, build processes, and such.

What does it do?

Captured Output is a tool that may be added to iTerm2's toolbelt (a view on the right side of terminal windows). It works in conjunction with user-defined Triggers. A Trigger whose action is Capture Output looks for lines of output that match its regular expression. When one is found, the entire line is added to the Captured Output tool. When the user clicks on a line in the Captured Output tool, iTerm2 scrolls to reveal that line. Double-clicking on a line in the Captured Output tools run a user-defined Coprocess.

Shell Integration Required

Shell Integration must be installed because Captured Output ties in to command history.

Example

One way to use Captured Output is to view compiler output. Suppose you run make and get thousands of lines of output, some of which may contain errors or warnings. You'd like to examine each one and take some action on it. Here's how you would use Captured Output to assist with this task:

Step 1: Create Triggers

Create a Trigger that matches your compiler's errors and warnings. Clang's errors look like this:

filename.c:54:9: error: use of undeclared identifier 'foo'

The following regular expression matches errors and warnings from Clang:

^([_a-zA-Z0-9+/.-]+):([0-9]+):[0-9]+: (?:error|warning):

There are two capture groups defined. We'll come back to those later.

Step 2: Open the Toolbelt

Open the Toolbelt by selecting the menu item Toolbelt > Show Toolbelt. Enable the Toolbelt > Captured Output menu item to ensure it is visible.

Step 3: Run make

Kick off the build by running make. It spits out thousands of lines of output.

Step 4: Examine the Captued Output tool

Any errors or warnings that appear in the compiler output will appear in the Captured Output tool.

Select an entry in the tool. iTerm2 scrolls to display the line and briefly highlights it in blue.

Step 5: Open the file containing the error

The Trigger created in step 1 takes an optional parameter. It is a command for iTerm2 to exceute as a Coprocess when you double-click an entry in the Captured Output tool. An example command is:

echo vim \1; sleep 0.5; echo \2G

This coprocess command assumes you are at the command line, and it enters a command to open the offending file to the line number with an error. This is where the capture groups in the regular expression from step 1 become useful. For example, if the filename was "filename.c" and the error was on line 20, as in this error message:

filename:c:20:9 error: use of undeclared identifier 'foo'

The coprocess would:

  • Type "vim filename.c", followed by enter, as though you were typing it at the keyboard.
  • Wait half a second.
  • Type "20G".

Step 6: Check it off the list

You can right-click on an entry in Captured Output to open a menu, which contains a single item: "Toggle Checkmark". This helps you remember which entries have been dealt with as you go through errors and warnings in your compiler output.

Navigation

Captured Output is linked to the Command History tool. If no command is selected in the Command History tool, then the most recent captured output is displayed. Otherwise, the captured output from the selected command is displayed. You can remove a selection from the Command History tool by cmd-clicking on it.