Author: | Andreas Rumpf |
---|---|
Version: | 1.6.0 |
Nimgrep is a command line tool for search and replace tasks. It can search for regex or peg patterns and can search whole directories at once. User confirmation for every single replace operation can be requested.
Nimgrep has particularly good support for Nim's eccentric style insensitivity (see option -y below). Apart from that it is a generic text manipulation tool.
Installation
Compile nimgrep with the command:
nim c -d:release tools/nimgrep.nim
And copy the executable somewhere in your $PATH.
Command line switches
Usage:- To search:
nimgrep [options] PATTERN [(FILE/DIRECTORY)*/-]
- To replace:
nimgrep [options] PATTERN --replace REPLACEMENT (FILE/DIRECTORY)*/-
- To list file names:
nimgrep [options] --filenames [PATTERN] [(FILE/DIRECTORY)*]
Positional arguments, from left to right:
- PATTERN is either Regex (default) or Peg if --peg is specified. PATTERN and REPLACEMENT should be skipped when --stdin is specified.
- REPLACEMENT supports $1, $# notations for captured groups in PATTERN.Danger: --replace mode DOES NOT ask confirmation unless --confirm is specified!
- Final arguments are a list of paths (FILE/DIRECTORY) or a standalone minus - or not specified (empty):
- empty, current directory . is assumed (not with --replace)Note: so when no FILE/DIRECTORY/- is specified nimgrep does not read the pipe, but searches files in the current dir instead!
- -, read buffer once from stdin: pipe or terminal input; in --replace mode the result is directed to stdout; it's not compatible with --stdin, --filenames, or --confirm
For any given DIRECTORY nimgrep searches only its immediate files without traversing sub-directories unless --recursive is specified.
- empty, current directory . is assumed (not with --replace)
In replacement mode we require all 3 positional arguments to avoid damaging.
Options:
- Mode of operation:--find, -ffind the PATTERN (default)--replace, -!replace the PATTERN to REPLACEMENT, rewriting the files--confirmconfirm each occurrence/replacement; there is a chance to abort any time without touching the file--filenamesjust list filenames. Provide a PATTERN to find it in the filenames (not in the contents of a file) or run with empty pattern to just list all files:
nimgrep --filenames # In current dir nimgrep --filenames "" DIRECTORY # Note empty pattern "", lists all files in DIRECTORY
- Interprete patterns:--pegPATTERN and PAT are Peg--rePATTERN and PAT are regular expressions (default)--rex, -xuse the "extended" syntax for the regular expression so that whitespace is not significant--word, -wmatches should have word boundaries (buggy for pegs!)--ignoreCase, -ibe case insensitive in PATTERN and PAT--ignoreStyle, -ybe style insensitive in PATTERN and PATNote: PATERN and patterns PAT (see below in other options) are all either Regex or Peg simultaneously and options --rex, --word, --ignoreCase, and --ignoreStyle are applied to all of them.
- File system walk:--recursive, -rprocess directories recursively--followfollow all symlinks when processing recursively--ext:EX1|EX2|...only search the files with the given extension(s), empty one ("--ext") means files with missing extension--noExt:EX1|...exclude files having given extension(s), use empty one to skip files with no extension (like some binary files are)--includeFile:PATsearch only files whose names contain pattern PAT--excludeFile:PATskip files whose names contain pattern PAT--includeDir:PATsearch only files with their whole directory path containing PAT--excludeDir:PATskip directories whose name (not path) contain pattern PAT--if,--ef,--id,--edabbreviations of the 4 options above--sortTime, -s[:asc|desc]order files by the last modification time (default: off): ascending (recent files go last) or descending
- Filter file content:--match:PATselect files containing a (not displayed) match of PAT--noMatch:PATselect files not containing any match of PAT--bin:on|off|onlyprocess binary files? (detected by 0 in first 1K bytes) (default: on - binary and text files treated the same way)--text, -tprocess only text files, the same as --bin:off
- Represent results:--nocoloroutput will be given without any colors--color[:on]force color even if output is redirected (default: auto)--colorTheme:THEMEselect color THEME from simple (default), bnw (black and white), ack, or gnu (GNU grep)--countonly print counts of matches for files that matched--context:N, -c:Nprint N lines of leading context before every match and N lines of trailing context after it (default N: 0)--afterContext:N, -a:Nprint N lines of trailing context after every match--beforeContext:N, -b:Nprint N lines of leading context before every match--group, -ggroup matches by file--newLine, -ldisplay every matching line starting from a new line--cols[:N]limit max displayed columns/width of output lines from files by N characters, cropping overflows (default: off)--cols:auto, -%calculate columns from terminal width for every line--onlyAscii, -@display only printable ASCII Latin characters 0x20-0x7E
- substitutions: 0 -> ^@, 1 -> ^A, ... 0x1F -> ^_,
- 0x7F -> '7F, ..., 0xFF -> 'FF
- Miscellaneous:--threads:N, -j:Nspeed up search by N additional workers (default: 0, off)--stdinread PATTERN from stdin (to avoid the shell's confusing quoting rules) and, if --replace given, REPLACEMENT--verbosebe verbose: list every processed file--help, -hshows this help--version, -vshows the version
Examples
All examples below use default PCRE Regex patterns:
- To search recursively in Nim files using style-insensitive identifiers:
nimgrep --recursive --ext:'nim|nims' --ignoreStyle # short: -r --ext:'nim|nims' -y
Note: we used ' quotes to avoid special treatment of | symbol for shells like Bash - To exclude version control directories (Git, Mercurial=hg, Subversion=svn) from the search:
nimgrep --excludeDir:'^\.git$' --excludeDir:'^\.hg$' --excludeDir:'^\.svn$' # short: --ed:'^\.git$' --ed:'^\.hg$' --ed:'^\.svn$'
- To search only in paths containing the tests sub-directory recursively::
nimgrep --recursive --includeDir:'(^|/)tests($|/)' # short: -r --id:'(^|/)tests($|/)'
Attention: note the subtle difference between --excludeDir and --includeDir: the former is applied to relative directory entries and the latter is applied to the whole paths - Nimgrep can search multi-line, e.g. to find files containing import and then strutils use pattern 'import(.|\n)*?strutils'.