Findstr - DOS/Command Prompt Reference
[Windows 2000 or later] Searches for strings matching the specified pattern from files or the standard input. More options or search patterns than Find command are available.
* Files are treated as being in a format of system codepage (system locale). However, if specifying other charset text file to /G option, and the charset of the target file is the same, the search may be performed correctly.
Syntax
findstr[.exe] [/B] [/E] [/L | /R] [/S] [/I] [/X] [/V] [/N] [/M] [/O] [/P] [/OFF[LINE]] [/A:<color-attr>] [/C:<pattern>] [/D:<directories>] [/F:<list-file>] [/G:<pattern-file>] <pattern> [[<drive>:][<path>]<file-name> ...]
Options
| /B | Treats as ‘match’ only when strings that match the specified pattern are at the beginning of the line. Leading spaces in the line are not ignored; the line including leading spaces is compared. |
| /E | Treats as ‘match’ only when strings that match the specified pattern are at the end of the line. Trailing spaces in the line are not ignored. When /B is also used, Findstr will treated as ‘match’ only when the line is consisted with the specified pattern (this behavior is the same for /X). |
| /L | Searches <pattern> as a normal string (string literal). The comparison is simply performed as comparing to strings specified in <pattern>. |
| /R | Searches <pattern> as a regular expression. For more information about regular expressions, please see details below. (there are a limited number of patterns available.) |
| /S | Searches for files, specified in <file-name> or described in the file specified by /F, not only in the directory ‘[<drive>:][<path>]’ (or the current directory if not specified), but also in the all subdirectories. |
| /I | Ignores cases for the string to search. |
| /X | Searches for lines that exactly match the specified pattern. |
| /V | Outputs lines that do NOT contain the string matching the specified pattern. With /X specified, outputs lines that do not exactly match the pattern. |
| /N | Prints the line numbers of matching lines. This option has no effect if /M is specified. |
| /M | Prints file names which contain matching lines. If /V is not specified, files which contain strings matching the specified pattern will be printed. If /V is specified, files which do not contain strings matching the specified pattern will be printed. |
| /O | Prints offsets (the byte index from the head of the file) of lines which match. If /N is specified, both the line numbers and offsets are printed. This option has no effect if /M is specified. |
| /P | Excludes files, which contain non-printable characters (such as binary files), from search targets. |
| /OFF[LINE] | Searches files having ‘offline attribute’ too (does not exclude). |
| /A:<color-attr> | Specifies the text color of the file names (if multiple files are to be searched), line numbers (/N), and offsets (/O) printed as search results. <color-attr> will be the same format for Color command. This option has no effect if /M is specified. |
| /C:<pattern> |
Specifies the pattern to search for. When not using /C, the pattern will be divided by the space characters, and Findstr will search for files that match one of divided pattern. If using /C, the pattern will not be divided, and Findstr will search for files that match entire pattern. (Note that surrounding the pattern with ‘" "’ is necessary when <pattern> includes the space character(s).) /C can be specified multiple times; Findstr searches for files that match either of patterns. If /C is used, specifying ‘<pattern>’ without /C will not be allowed. |
| /D:<directories> |
Specifies the search target directory. Multiple directories can be specified with ‘;’ delimiters. This parameter lets the specified directory ‘the current directory’ (including the drive). If ‘[<drive>:][<path>]’ is also specified, this parameter is used based on the changed current directory as followings:
|
| /F:<list-file> |
Reads the file specified in <list-file>, and uses each lines as search target files instead of the command line (<file-name>). If specifying the character ‘/’ only to <list-file>, Findstr reads standard input (STDIN) for the file list. This is usually used with the combination of pipe operator. |
| /G:<pattern-file> |
Uses the search pattern written in the file <pattern-file> rather than from the command line (<pattern> or /C option). Each line in <pattern-file> will be the search pattern (Findstr searches for the line(s) that matches either of patterns). If specifying the character ‘/’ only to <pattern-file>, Findstr reads standard input (STDIN) for the search pattern list. If /G is used, /C option can still be used, but specifying ‘<pattern>’ without /C will not be allowed. |
| <pattern> |
Specifies the search pattern. ‘"’ is not necessary, but when specifying multiple patterns, the patterns must be splitted with space characters and surrounded with " " such as "<pattern1> <pattern2> ...". To use space characters in the search pattern, use /C option. |
| <drive>:, <path>, <file-name> |
Specifies the file name to search. If omitting the drive or the directory path, the file in the current drive/path will be searched. Multiple file names can be specified. Wildcards can be used for the file name. |
Details
This command is similar to Find command, which searches for strings in files, but Findstr allows you to perform more advanced searches than Find.
/R and available Regular Expressions
The following Regular Expressions are available for ‘/R’ option.
| Patterns | Meanings | Pattern samples | Matching samples |
|---|---|---|---|
| . | Any one character (one byte) | te.t | ‘test’, ‘text’, etc. |
| * | Zero or more patterns (Checks for matching the character or the pattern set just before ‘*’ character zero or more times. Not same for the wildcard ‘*’.) | A *B | ‘AB’, ‘A B’, ‘A B’, etc. |
| ^ | Head of line (Matches when the pattern just after ‘^’ is in the head of the line.) | ^rem | Lines starting with ‘rem’ (e.g. ‘rem foo’, ‘remove’) |
| $ | End of line (Matches when the pattern just before ‘$’ is in the end of the line.) | ed$ | Lines ending with ‘ed’ (e.g. ‘finished’, ‘gf ed’) |
| [class] | Any one character in class | h[aio]t | Lines including one or more ‘hat’, ‘hit’, or ‘hot’ strings |
| [^class] | Any one character not in class | h[^aio]t | Lines including one or more strings (‘"h" + one character + "t"’) other than ‘hat’, ‘hit’, and ‘hot’ (e.g. ‘het’, ‘hut’) |
| [x-y] | Any one of the characters between x and y | [0-9][0-9] | Lines including two digits such as ‘04’ and ‘53’ |
| \x | Escape (Treats x character as a regular character, not a pattern character) | \[[a-z][a-z]*\] | Lines containing the string beginning with ‘[’, ending with ‘]’, and including at least one lower-case character between brackets (such as ‘[test]’ and ‘[y]’) |
| \<word | Head of word (Not match when any alphabet or number immediately precedes word) | \<set | Lines including ‘set’, ‘setting’, or etc. (not including ‘reset’) |
| word\> | End of word (Not match when any alphabet or number immediately follows word) | use\> | Lines including ‘use’, ‘excuse’, or etc. (not including ‘useless’) |
* The characters are treated in bytes. If including non-ASCII characters such in [class], the search would not work properly.
Exit codes
Findstr generally returns the following exit codes. You can write conditional processings in batch files by using If and Erorlevel.
* There might be a case that Findstr returns exit codes other than the followings (not confirmed).
| Codes | Meanings |
|---|---|
| 0 | The search performed successfully, and one or more files/lines were matched. |
| 1 | No files were matched. This value is returned either or both when the search target file cannot be opened or when no files have lines that match the pattern. |
| 2 | An error occurred during searching. (Unknown if the string was found) |
Samples
Sample 1
findstr /n the document.txt
Searches document.txt for the string ‘the’. This result will be as followings.
5:and he got the best prize.
Sample 2
findstr /c:"the more" document.txt
Searches document.txt for the string ‘the more’. Specifies with ‘/c’ when searching for the pattern including spaces. If simply specifying as followings:
findstr "the more" document.txt
... Findstr searches for ‘the’ or ‘more’.
Sample 3
findstr /i /s "TODO:" *.c *.cpp
Searches files ‘*.c’ and ‘*.cpp’ in the current directory and its subdirectories for the string ‘TODO:’ in case insensitive, and outputs the search result. (Using wildcards)
MyApp1\Main.cpp: // TODO: fix width MyApp2\Sample.c: // TODO: insert your code here
* If ‘/N’ is specified, ‘line-number:’ follows ‘file-name:’.
Sample 4
findstr /r /c:"^ *echo" *.bat
Searches for ‘*.bat’ files containing the line beginning with ‘echo’ ignoring preceding spaces.
Sample 5
dir /a:a /s /b *.txt | findstr /f:/ fox
Searches for ‘*.txt’ files, containing ‘fox’, with ‘Archive attribute’ in the current directory and its subdirectories. This sample makes the file list to search by using Dir command and passes its list as Findstr's input.
Sample 6
findstr /g:Y:\checklist.txt /s *.xml
Reads the search patterns from each line in ‘Y:\checklist.txt’, and searches for ‘*.xml’, containing either of the patterns, in the current directory and its subdirectories.
Sample 7
for /f "delims=" %1 in ('findstr /m /v /i stub *.txt') do copy /y "%~f1" E:\Documents\
[Extensions] Copies ‘*.txt’ files not containing ‘stub’ string (in case insensitive) in the current directory into ‘E:\Documents’ directory. This sample parses the file list, made by the part ‘findstr /m /v /i stub *.txt’, by using For command, and executes Copy command for each lines (files).
Sample 8
chcp 65001 echo あいうえお| findstr /g:/ doc-utf8.txt
Searches the UTF-8 text file for the string ‘あいうえお’. Usually non-ASCII characters cannot be searched by Findstr because system codepage is used, but the combination of ‘/G:/’ (passing patterns indirectly), Chcp (changing codepage to UTF-8), and Echo (passing text) enables to search for UTF-8 text.
* In the above case the search will not work properly if using /R option.