← All commands
THE COMMAND REFERENCE

ptx

Make a permuted index, listing each word with the text around it.

Last updated

Portable / common

Implementation-level reference; examples are not certified for every installed version.

Overview

ptx builds a permuted index, also called a keyword-in-context index. For each word of the input, it prints a line with that word lined up in a column and the words that came before and after it. It is a way to look up where a word is used. It is an old tool, mostly of interest for text indexing.

Background

ptx is part of GNU coreutils; the GNU manual documents it as producing a permuted index of file contents. macOS does not ship it, and the BusyBox 1.37.0 build used for this page has no such applet, so this page has only a GNU view.

Examples

Make an index of one short line, with an output width of 40 characters; the keyword column is in the middle, and the spacing is compared with blanks collapsed:

printf 'the quick fox\n' | ptx -w 40

Count the lines: there is one for each word in the input:

printf 'the quick fox\n' | ptx -w 40 | grep -c .

Options

-w
Set the width of the output in characters, as in -w 40.

Common mistakes

The output is made of columns padded with spaces, so it is meant to be read on a screen, not parsed. Common words such as the get an entry too, unless you give a list of words to ignore with -i. The width defaults to 72 and has to be wide enough for the context, or the context is cut. Other tools, such as grep -n, are simpler when you only need the places where a word is used.

Portability

This page covers GNU only. The Common examples were executed on GNU coreutils 9.11 (see the development guide for the exact check).

References

Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.