This page is a simple list of usage samples (a.k.a. recipes) for pss. Its purpose is to demonstrate some examples of what pss is capable of. For a more comprehensive guide, you'll have to consult the usage string printed by pss when it's run without arguments.

By default (unless the --no-recurse option is specified), pss searches the given directory or directories recursively. If no files/directories are specified, the only directory (recursively) searched is the current working directory.

Here's how to find all occurrences of the string foo in all Python files located in the current directory or below it:

> pss --py foo

This will similarly search Python files for foo, but in directory ~/mydir:

> pss --py foo ~/mydir

The search string can be a full fledged (Python-compatible) regular expression. Here is a search for all calls to some function/method starting with iter:

> pss --py "\biter[^(]*\("

pss knows about many source file types. The full list can be seen by running with --help-types. By default, all known file types are searched:

# Search in all known file types
> pss foo

But some types can be excluded:

# Search in all known file types, except PHP files
> pss --nophp foo

pss ignores some directories in which we don't usually want to search by default, for example .hg and .svn (the full list is printed in the usage description). This can be controlled from the command-line to add and remove ignored directories. For example, here's how to ask pss to also ignore the dist directory:

> pss foo --py --ignore-dir=dist

Showing context lines is supported in a manner similar to grep (-A, -B and -C options):

# Make sure that at least 5 context lines are shown before each matching line
> pss -A 5 foo

pss can also be used to just display the files it finds, without looking for matches inside them. Think of this as find on steroids - you still get pss's ability to recognize source code files and ignore certain directories. For example, the following will find and display the names of all C (source and header) files recursively under ~/mylib, as usual ignoring source control and other unimportant directories:

> pss -f --cc ~/mylib

The output of pss -f can be combined with other command-line tools in typical Unix-y way. For example, to count the lines of all C files found recursively under ~/mylib:

> pss -f --cc ~/mylib | xargs wc -l

The -t option of pss restricts the search to textual files. It acts as a filter on all the found files. For each file pss finds when run with -t, it will try to figure out if it's a text or a binary file, and will only search the text files. For example, here's how to combine it with other options to find all the textual files and display their names:

> pss -aft