What is it?

"spigot" is like a tap for a text file. You can turn it on and off to control the flow (what gets printed) of the file.

The tool merely interprets the (unlimited number of) controls specified on the command line as it goes through the file. The controls turn the "tap" on and off.

You could think of "spigot" as a simple version of expect and cat and head, all rolled into one.


This software is essentially free, but please read my payment spiel
Please read the full license


The usage shows the controls and some of the examples shown here:

% spigot -h

The controls are:


The default "tap" setting is on, so all lines are printed. Without any controls, we'll see the whole file, so:

% spigot somefile

It's just a very silly way to do a 'cat'

-show and -skip allow us to process the file by numbers of lines. So we can show just the first 15 lines of a file (similar to 'head') with:

% spigot somefile -show 15

In this case, spigot set our initial state was 'off' because we started with a -show. If you wanted to, you could be redundant with:

% spigot somefile -OFF -show 15

Once the first 15 lines are shown, spigot is smart enough to realize that it can stop reading the file because nothing else is going to be printed.

spigot is smart enough to figure out the start state. It's generally on, except for the controls that presume that it starts as off, specifically '-show' and '-on'

We can also skip lines. To only show the third and fourth lines of a file:

% spigot somefile -skip 2 -show 2 -OFF

We needed to remember to turn off the 'tap' after the last -show, because there's nothing turning it off here. -skip and -show don't actually change the permanent state of the 'tap,' they just change it temporarily.

We can also turn the "tap" on and off based on file contents. If we want to show everything in a file except for the footer, and we know the footer has started when we see a line that starts with "Copyright" then we can:

% spigot file -off '^Copyright'

If we want to do the same, but we still want to see the copyright line, then just add in a control to show that line:

% spigot file -off '^Copyright' -show 1

The "tap" will turn off when it sees '^Copyright' - but then temporarily turn back on for one line (the Copyright line) and then go back off again.

We can do the reverse, and skip a header of a file, for example, only showing everything including and after we see a line with 'START'

% spigot file -on START

And again, if we don't want to see the 'START' line we can add in a skip:

% spigot file -on START -skip 1

As a more complicated example, lets show the first four lines of a file, then everything from when we find 'ERROR MSG' until the first blank line is found:

% spigot log -show 4 -on "ERROR MSG" -off '^$'

Finally, we have the ability to insert text into the file using -echo and -do. Here we simply echo borders around a specific line we're looking for:

% spigot log -off WARNING -echo ======== -show 1 -echo ======== -ON

Note that we are only using -off to find the line, because we are using -show 1 and -ON we actually don't ever turn off the spigot.

We can also run a command. As a simple example, replace the line "DATE" with the actual date:

% spigot log -off DATE -skip 1 -do "date" -ON

Or replace "INCLUDE-HERE" with contents of file "include.txt"

% spigot log -off INCLUDE-HERE -skip 1 -do "cat include.txt" -ON

One thing to note is that "-ON" will turn on the spigot and continue to process, so something like this won't work:

% spigot file -ON -echo "END OF FILE"

What you really want is:

% spigot file -ON -show all -echo "END OF FILE"

Future Plans:

I suppose it would be neat to be able to save the last 'n' lines so we could show everything before a match, like 'egrep -B ', maybe something like:

% spigot log -show -10 -on ERROR -show 10 -OFF

Which could show the 10 lines before and after matching "ERROR"

I've also considered the possibility of adding looping to spigot controls, but I'd only want to do that if it could be done in a general sense.

Suggestions appreciated.

Plus, I'd love to know if anyone is using spigot. Do tell.


It's a single perl script


  1. Perl, which kicks ass


It's just a perl script. No install required.

Revision History:




Don't forget to shut the water off, or else you'll flood the whole place!


Not yet.

Does anyone use spigot? Please let me know.