Recursive search

This chapter will cover recursive search options and ways to filter the files to be searched. Shell globs and find command are also discussed to show alternate methods. Finally, there is a section to show how to pass file list output from grep to other commands.

For sample files and directories used in this chapter, go to example_files directory and follow the steps given below:

$ # create directory for this chapter and cd into it
$ mkdir recursive_matching && cd $_

$ # create a text file and a hidden file
$ printf 'hide\nobscure\nconceal\ncover\nblot\nshield' > patterns.txt
$ grep -Ff patterns.txt ../bre_ere/words.txt > .hidden
$ # create another text file
$ grep -E '([as]([b-g]|po)[r-t]){2}' ../bre_ere/words.txt > nested_group.txt

$ # create sub-directory, two scripts and another hidden file
$ mkdir scripts
$ echo 'yrneaolrknzcyr 86960' > scripts/.key
$ echo "tr 'a-z0-9' 'n-za-m5-90-4' < .key" > scripts/
$ printf "import math\n\nprint(math.pi)\n" > scripts/

$ # create link to a directory
$ ln -s ../context_matching/

$ # final directory structure including hidden files and links
$ tree -al
├── context_matching -> ../context_matching/
│   └── context.txt
├── .hidden
├── nested_group.txt
├── patterns.txt
└── scripts
    ├── .key

2 directories, 7 files

-r and -R

From man grep

-r, --recursive
      Read all files under each directory, recursively,  following
      symbolic  links  only if they are on the command line.  Note
      that if no file operand is given, grep searches the  working
      directory.  This is equivalent to the -d recurse option.

-R, --dereference-recursive
      Read  all  files  under each directory, recursively.  Follow
      all symbolic links, unlike -r.

info -r and -R will work as if -H option was specified as well, even if there is only one file found during recursive search. Hidden files are included by default.

$ # no need to specify path(s) if searching CWD
$ # show all matching lines with digit characters
$ grep -r '[0-9]'
scripts/.key:yrneaolrknzcyr 86960
scripts/ 'a-z0-9' 'n-za-m5-90-4' < .key

$ # without filename prefix
$ grep -rh '[0-9]'
yrneaolrknzcyr 86960
tr 'a-z0-9' 'n-za-m5-90-4' < .key

$ # list of files containing 'in'
$ grep -rl 'in'

$ # list of files in 'scripts' directory NOT containing 'in'
$ grep -rL 'in' scripts

Difference between -r and -R

$ # -r will not follow links
$ # files containing empty lines
$ grep -rlx ''

$ # explicitly specify directories, files or links to be searched
$ grep -rlx '' . context_matching

$ # -R will automatically follow links
$ grep -Rlx ''

Customize search path

By default, recursive search options -r and -R will include hidden files as well. There are situations, for example a directory under version control, where specific directories should be ignored or all the files mentioned in a specific file should be ignored. To aid in such custom searches, four options are available:

--include=GLOBsearch only files that match GLOB (a file pattern)
--exclude=GLOBskip files that match GLOB
--exclude-from=FILEskip files that match any file pattern from FILE
--exclude-dir=GLOBskip directories that match GLOB

info GLOB here refers to glob/wildcard patterns used by shell to expand filenames (not the same as regular expressions, see wooledge: glob for more details). The GLOB applies only to basename of file or directory, not the pathname. Which implies that you cannot use / in the globs specified in conjunction with recursive options.

Each of these options can be used multiple times to precisely specify the search paths.

$ # without customizing
$ grep -Rl 'in'

$ # excluding 'scripts' directory and all hidden files
$ grep -Rl --exclude-dir='scripts' --exclude='.*' 'in'

$ # allow only filenames ending with '.txt' (will match hidden files too)
$ grep -Rl --include='*.txt' 'in'
$ # allow only filenames ending with '.txt' or '.py'
$ grep -Rl --include='*.txt' --include='*.py' 'in'

$ # exclude all filenames ending with 'en' or '.txt'
$ printf '*en\n*.txt' | grep -Rl --exclude-from=- 'in'

If you mix --include and --exclude options, their order of declaration matters.

$ # no match
$ grep -Rl --include='*on*' --exclude='*.txt' 'in'
$ # this gives expected result
$ # all files ending with '.txt' are ignored unless the name contains 'on'
$ grep -Rl --exclude='*.txt' --include='*on*' 'in'

info These options can be used without -r or -R too.

$ # without customizing
$ grep -l 'a' scripts/*

$ # exclude files ending with '.sh'
$ grep -l --exclude='*.sh' 'a' scripts/*

$ # include only files ending with '.sh'
$ grep -l --include='*.sh' 'a' scripts/*

Extended globs

Modern versions of shells like bash and zsh provide feature rich extensions to glob. These can be used instead of -r and -R options for some cases. See my tutorial on glob for details on extended globs.

info Use -d skip to prevent grep from treating directories (matched as part of glob expansion) as input file to be searched.

$ # same as: grep -Rl --include='*.txt' --include='*.py' 'in'
$ # to include hidden files, dotglob should be set as well 
$ shopt -s extglob globstar 
$ grep -l 'in' **/*.@(txt|py)

$ # if directory name can match the glob, use '-d skip'
$ printf '%s\n' **/*context*
$ grep -l 'in' **/*context*
grep: context_matching: Is a directory
$ grep -d skip -l 'in' **/*context*

Using find command

The find command is more versatile than recursive options and extended globs. Apart from searching based on filename, it has provisions to match based on file characteristics like size and time. See my tutorial on find for more details.

$ # files (including hidden ones) with size less than 50 bytes
$ # '-type f' to match only files (not directories) and '-L' to follow links
$ find -L -type f -size -50c

$ # apply 'grep' command to matched files
$ find -L -type f -size -50c -exec grep 'e$' {} +

Piping filenames

File systems like ext3 and ext4 allows filenames with any bytes other than / and ASCII NUL. This can cause all sorts of problems if list of filenames from one command is passed to another as is. Space, newline, semicolon, etc are special to shell, so filenames containing these characters have to be properly quoted. Or, where applicable, separate the list of filenames with NUL character. For example, grep -Z will generate NUL separated list and xargs -0 will interpret the list as NUL separated.

$ # note the \0 characters after filenames
$ grep -rlZ '[0-9]' | od -c
0000000   s   c   r   i   p   t   s   /   .   k   e   y  \0   s   c   r
0000020   i   p   t   s   /   d   e   c   o   d   e   .   s   h  \0

$ # print last column from all lines of all input files
$ grep -rlZ '[0-9]' | xargs -0 awk '{print $NF}'

Example to show filenames with problematic characters like space causing issue if -Z is not used.

$ echo 'how are you?' > normal.txt
$ echo 'how dare you!' > 'filename with spaces.txt'
$ grep -r 'are'
filename with spaces.txt:how dare you!
normal.txt:how are you?

$ # problem when -Z is not used
$ grep -rl 'are' | xargs wc
wc: filename: No such file or directory
wc: with: No such file or directory
wc: spaces.txt: No such file or directory
 1  3 13 normal.txt
 1  3 13 total

$ # -Z to the rescue
$ grep -rlZ 'are' | xargs -0 wc
 1  3 14 filename with spaces.txt
 1  3 13 normal.txt
 2  6 27 total

Example for matching more than one search string anywhere in file:

$ # files containing 'in'
$ grep -rl 'in'

$ # files containing 'in' and 'or'
$ grep -rlZ 'in' | xargs -0 grep -l 'or'

$ # files containing 'in' but NOT 'at'
$ grep -rlZ 'in' | xargs -0 grep -L 'at'

$ # files containing 'in' and 'or' and 'at'
$ # note the use of -Z for the middle command
$ grep -rlZ 'in' | xargs -0 grep -lZ 'or' | xargs -0 grep -l 'at'


Having recursive options when there is already find command seems unnecessary, but in my opinion, these options are highly convenient. Some cases may require falling back to shell globs or find or even a combination of these methods. Tools like ack, ag and ripgrep provide a default recursive search behavior, with out-of-box features like ignoring hidden files, respecting .gitignore rules, etc.


For sample directory, a particular version of one of my GitHub repo is used. All the exercises will assume recursive searching, unless otherwise specified. There are no symbolic links.

$ # assumes 'exercises' as CWD
$ mkdir recursive_searching && cd $_
$ repo=''
$ git clone -b apr19 "$repo"
$ cd Command-line-text-processing

a) List all files containing xargs or python3

$ grep ##### add your solution here

b) List all files containing grep but do not list if they are from .git or exercises directories.

$ grep ##### add your solution here

c) List all files containing baz if the filename ends with .txt but do not search hidden directories.

$ grep ##### add your solution here

d) Search files ending with .md only in current directory (i.e. no recursive searching) and count the total number of occurrences of whole words grep or sed or awk.

$ grep ##### add your solution here

e) List all files containing Hello unless the filename ends with .txt or .sh

$ grep ##### add your solution here

f) List all files containing whole words awk and perl but not basename. Although not the case here, assume that filenames can contain shell special characters like space, semicolon, newline, etc.

$ grep ##### add your solution here