Nim/doc/nimgrep_cmdline.txt

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:
1) PATTERN is either Regex (default) or Peg if `--peg` is specified.
   PATTERN and REPLACEMENT should be skipped when `--stdin` is specified.
2) REPLACEMENT supports `$1`, `$#` notations for captured groups in PATTERN.

   .. DANGER:: `--replace` mode **DOES NOT** ask confirmation
      unless `--confirm` is specified!

3) 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 subdirectories unless `--recursive` is specified.

In replacement mode we require all 3 positional arguments to avoid damaging.

Options:
* Mode of operation:
  --find, -f          find the PATTERN (default)
  --replace, -!       replace the PATTERN to REPLACEMENT, rewriting the files
  --confirm           confirm each occurrence/replacement; there is a chance
                      to abort any time without touching the file
  --filenames         just 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:
  --peg               PATTERN and PAT are Peg
  --re                PATTERN and PAT are regular expressions (default)
  --rex, -x           use the "extended" syntax for the regular expression
                      so that whitespace is not significant
  --word, -w          matches should have word boundaries (buggy for pegs!)
  --ignoreCase, -i    be case-insensitive in PATTERN and PAT
  --ignoreStyle, -y   be style insensitive in PATTERN and PAT
  .. Note:: PATTERN 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, -r      process directories recursively
  --follow             follow all symlinks when processing recursively
  --sortTime, -s[:asc|desc]
                       order files by the last modification time (default: off):
                       ascending (recent files go last) or descending

* Filter files (based on filesystem paths):

  .. Hint:: Instead of `not` you can type just `n` for negative options below.

  --ex[tensions]:EX1|EX2|...
                       only search the files with the given extension(s),
                       empty one (`--ex`) means files with missing extension
  --notex[tensions]:EX1|EX2|...
                       exclude files having given extension(s), use empty one to
                       skip files with no extension (like some binary files are)
  --fi[lename]:PAT     search only files whose name matches pattern PAT
  --notfi[lename]:PAT  skip files whose name matches pattern PAT
  --di[rname]:PAT      select files that in their path have a directory name
                       that matches pattern PAT
  --notdi[rname]:PAT   do not descend into directories whose name (not path)
                       matches pattern PAT
  --dirp[ath]:PAT      select only files whose whole relative directory path
                       matches pattern PAT
  --notdirp[ath]:PAT   skip files whose whole relative directory path
                       matches pattern PAT

* Filter files (based on file contents):
  --inF[ile]:PAT      select files containing a (not displayed) match of PAT
  --notinF[ile]:PAT   skip files containing a match of PAT
  --bin:on|off|only   process binary files? (detected by \0 in first 1K bytes)
                      (default: on - binary and text files treated the same way)
  --text, -t          process only text files, the same as `--bin:off`

* Filter matches:
  --inC[ontext]:PAT   select only matches containing a match of PAT in their
                      surrounding context (multiline with `-c`, `-a`, `-b`)
  --notinC[ontext]:PAT
                      skip matches not containing a match of PAT
                      in their surrounding context

* Represent results:
  --nocolor           output will be given without any colors
  --color[:on]        force color even if output is redirected (default: auto)
  --colorTheme:THEME  select color THEME from `simple` (default),
                      `bnw` (black and white), `ack`, or `gnu` (GNU grep)
  --count             only print counts of matches for files that matched
  --context:N, -c:N   print N lines of leading context before every match and
                      N lines of trailing context after it (default N: 0)
  --afterContext:N, -a:N
                      print N lines of trailing context after every match
  --beforeContext:N, -b:N
                      print N lines of leading context before every match
  --group, -g         group matches by file
  --newLine, -l       display 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:N   speed up search by N additional workers (default: 0, off)
  --stdin             read PATTERN from stdin (to avoid the shell's confusing
                      quoting rules) and, if `--replace` given, REPLACEMENT
  --verbose           be verbose: list every processed file
  --help, -h          shows this help
  --version, -v       shows the version