levovix
/
Nim
zrkadlo https://github.com/nim-lang/Nim


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229
							<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--  This file is generated by Nim. -->
<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en" data-theme="auto">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>nimgrep User's manual</title>

<!-- Google fonts -->
<link href='https://fonts.googleapis.com/css?family=Lato:400,600,900' rel='stylesheet' type='text/css'/>
<link href='https://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>

<!-- Favicon -->
<link rel="shortcut icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAUAAAAF////AP///wD///8A////AP///wD///8A////AP///wD///8A////AAAAAAIAAABbAAAAlQAAAKIAAACbAAAAmwAAAKIAAACVAAAAWwAAAAL///8A////AP///wD///8A////AAAAABQAAADAAAAAYwAAAA3///8A////AP///wD///8AAAAADQAAAGMAAADAAAAAFP///wD///8A////AP///wAAAACdAAAAOv///wD///8A////AP///wD///8A////AP///wD///8AAAAAOgAAAJ3///8A////AP///wAAAAAnAAAAcP///wAAAAAoAAAASv///wD///8A////AP///wAAAABKAAAAKP///wAAAABwAAAAJ////wD///8AAAAAgQAAABwAAACIAAAAkAAAAJMAAACtAAAAFQAAABUAAACtAAAAkwAAAJAAAACIAAAAHAAAAIH///8A////AAAAAKQAAACrAAAAaP///wD///8AAAAARQAAANIAAADSAAAARf///wD///8AAAAAaAAAAKsAAACk////AAAAADMAAACcAAAAnQAAABj///8A////AP///wAAAAAYAAAAGP///wD///8A////AAAAABgAAACdAAAAnAAAADMAAAB1AAAAwwAAAP8AAADpAAAAsQAAAE4AAAAb////AP///wAAAAAbAAAATgAAALEAAADpAAAA/wAAAMMAAAB1AAAAtwAAAOkAAAD/AAAA/wAAAP8AAADvAAAA3gAAAN4AAADeAAAA3gAAAO8AAAD/AAAA/wAAAP8AAADpAAAAtwAAAGUAAAA/AAAA3wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAADfAAAAPwAAAGX///8A////AAAAAEgAAADtAAAAvwAAAL0AAADGAAAA7wAAAO8AAADGAAAAvQAAAL8AAADtAAAASP///wD///8A////AP///wD///8AAAAAO////wD///8A////AAAAAIcAAACH////AP///wD///8AAAAAO////wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A////AP///wD///8A//8AAP//AAD4HwAA7/cAAN/7AAD//wAAoYUAAJ55AACf+QAAh+EAAAAAAADAAwAA4AcAAP5/AAD//wAA//8AAA=="/>
<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAA3XAAAN1wFCKJt4AAAAB3RJTUUH4QQQEwksSS9ZWwAAAk1JREFUWMPtll2ITVEUx39nn/O7Y5qR8f05wtCUUr6ZIS++8pEnkZInPImneaCQ5METNdOkeFBKUhMPRIkHKfEuUZSUlGlKPN2TrgfncpvmnntnmlEyq1Z7t89/rf9a6+y99oZxGZf/XeIq61EdtgKXgdXA0xrYAvBjOIF1AI9zvjcC74BSpndrJPkBWDScTF8Aa4E3wDlgHbASaANmVqlcCnwHvgDvgVfAJ+AikAAvgfVZwLnSVZHZaOuKoQi3ZOMi4NkYkpe1p4J7A8BpYAD49hfIy/oqG0+hLomiKP2L5L+1ubn5115S+3OAn4EnwBlgMzCjyt6ZAnQCJ4A7wOs88iRJHvw50HoujuPBoCKwHWiosy8MdfZnAdcHk8dxXFJ3VQbQlCTJvRBCGdRbD4M6uc5glpY3eAihpN5S5w12diSEcCCEcKUO4ljdr15T76ur1FDDLIQQ3qv71EdDOe3Kxj3leRXyk+pxdWnFWod6Wt2bY3de3aSuUHcPBVimHs7mK9WrmeOF6lR1o9qnzskh2ar2qm1qizpfXaPeVGdlmGN5pb09qMxz1Xb1kLqgzn1RyH7JUXW52lr5e/Kqi9qpto7V1atuUzfnARrV7jEib1T76gG2qxdGmXyiekkt1GswPTtek0aBfJp6YySGBfWg2tPQ0FAYgf1stUfdmdcjarbYJEniKIq6gY/Aw+zWHAC+p2labGpqiorFYgGYCEzN7oQdQClN07O1/EfDyGgC0ALMBdYAi4FyK+4H3gLPsxfR1zRNi+NP7nH5J+QntnXe5B5mpfQAAAAASUVORK5CYII=">

<!-- CSS -->
<link rel="stylesheet" type="text/css" href="nimdoc.out.css?v=2.3.1">

<!-- JS -->
<script type="text/javascript" src="dochack.js?v=2.3.1"></script>
</head>
<body>
  <div class="document" id="documentId">
    <div class="container">
      <h1 class="title">nimgrep User's manual</h1>
      <div class="row">
  <div class="three columns">
    <div class="theme-select-wrapper">
      <label for="theme-select">Theme:&nbsp;</label>
      <select id="theme-select" onchange="setTheme(this.value)">
        <option value="auto">🌗 Match OS</option>
        <option value="dark">🌑 Dark</option>
        <option value="light">🌕 Light</option>
      </select>
    </div>
    <div id="global-links">
      <ul class="simple-boot">
        <li><a href="manual.html">Manual</a></li>
        <li><a href="lib.html">Standard library</a></li>
        <li> <a id="indexLink" href="theindex.html">Index</a></li>
        <li><a href="compiler/theindex.html">Compiler docs</a></li>
        <li><a href="https://nim-lang.github.io/fusion/theindex.html">Fusion docs</a></li>
        <li><a href="https://nim-lang.github.io/Nim/">devel</a>, <a href="https://nim-lang.org/documentation.html">stable</a></li>
      </ul>
    </div>
    <div id="searchInputDiv">
      Search: <input type="search" id="searchInput"
        oninput="search()" />
    </div>
    <div class="search-groupby">
  Group by:
  <select onchange="groupBy(this.value)">
    <option value="section">Section</option>
    <option value="type">Type</option>
  </select>
</div>

    <ul class="simple simple-toc" id="toc-list">
  <li><a class="reference" id="installation_toc" href="#installation">Installation</a></li>
<li><a class="reference" id="command-line-switches_toc" href="#command-line-switches">Command line switches</a></li>
<ul class="simple"><li><a class="reference" id="command-line-switches-path-filter-options_toc" href="#command-line-switches-path-filter-options">Path filter options</a></li>
<li><a class="reference" id="command-line-switches-combining-multiple-filter-options-together-and-negating-them_toc" href="#command-line-switches-combining-multiple-filter-options-together-and-negating-them">Combining multiple filter options together and negating them</a></li>
</ul><li><a class="reference" id="meaning-of-roof-and-dollar_toc" href="#meaning-of-roof-and-dollar">Meaning of <tt class="docutils literal"><span class="pre">^</span></tt> and <tt class="docutils literal"><span class="pre">$</span></tt></a></li>
<li><a class="reference" id="examples_toc" href="#examples">Examples</a></li>

</ul>

  </div>
  <div class="nine columns" id="content">
    <a href="https://github.com/nim-lang/Nim/tree/devel/doc/nimgrep.md#L1" class="link-seesrc" target="_blank">Source</a>&nbsp;&nbsp;
<a href="https://github.com/nim-lang/Nim/edit/devel/doc/nimgrep.md#L1" class="link-seesrc" target="_blank" >Edit</a>&nbsp;&nbsp;

    <div id="tocRoot"></div>
    
    <p class="module-desc"><table class="docinfo" frame="void" rules="none"><col class="docinfo-name" /><col class="docinfo-content" /><tbody valign="top"><tr><th class="docinfo-name">Author:</th><td>Andreas Rumpf</td></tr>
<tr><th class="docinfo-name">Version:</th><td>1.6.0</td></tr>
</tbody></table><p>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.</p>
<p>Nimgrep has particularly good support for Nim's eccentric <em>style insensitivity</em> (see option <tt class="docutils literal"><span class="pre option">-y</span></tt> below). Apart from that it is a generic text manipulation tool.</p>

<h1><a class="toc-backref" id="installation" href="#installation">Installation</a></h1><p>Compile nimgrep with the command:</p>
<p><pre class="listing"><span class="program">nim</span> <span class="option">c</span> <span class="option">-d:release</span> <span class="Identifier">tools/nimgrep.nim</span></pre></p>
<p>And copy the executable somewhere in your <tt class="docutils literal"><span class="pre">$PATH</span></tt>.</p>

<h1><a class="toc-backref" id="command-line-switches" href="#command-line-switches">Command line switches</a></h1>Usage:<ul class="simple"><li>To search:<pre>nimgrep [options] PATTERN [(FILE/DIRECTORY)*/-]</pre>
</li>
<li>To replace:<pre>nimgrep [options] PATTERN --replace REPLACEMENT (FILE/DIRECTORY)*/-</pre>
</li>
<li>To list file names:<pre>nimgrep [options] --filenames [PATTERN] [(FILE/DIRECTORY)*]</pre>
</li>
</ul>
<p>Positional arguments, from left to right:</p>
<ol class="simple"><li>PATTERN is either Regex (default) or Peg if <tt class="docutils literal"><span class="pre option">--peg</span></tt> is specified. PATTERN and REPLACEMENT should be skipped when <tt class="docutils literal"><span class="pre option">--stdin</span></tt> is specified.</li>
<li>REPLACEMENT supports <tt class="docutils literal"><span class="pre option">$1</span></tt>, <tt class="docutils literal"><span class="pre option">$#</span></tt> notations for captured groups in PATTERN.<div class="admonition admonition-error"><span class="admonition-error-text"><b>Danger:</b></span>
<tt class="docutils literal"><span class="pre option">--replace</span></tt> mode <strong>DOES NOT</strong> ask confirmation unless <tt class="docutils literal"><span class="pre option">--confirm</span></tt> is specified!</div>
</li>
<li>Final arguments are a list of paths (FILE/DIRECTORY) or a standalone minus <tt class="docutils literal"><span class="pre option">-</span></tt> or not specified (empty):<ul class="simple"><li>empty, current directory <tt class="docutils literal"><span class="pre option">.</span></tt> is assumed (not with <tt class="docutils literal"><span class="pre option">--replace</span></tt>)<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
so when no FILE/DIRECTORY/<tt class="docutils literal"><span class="pre option">-</span></tt> is specified nimgrep does <strong>not</strong> read the pipe, but searches files in the current dir instead!</div>
</li>
<li><tt class="docutils literal"><span class="pre option">-</span></tt>, read buffer once from stdin: pipe or terminal input; in <tt class="docutils literal"><span class="pre option">--replace</span></tt> mode the result is directed to stdout; it's not compatible with <tt class="docutils literal"><span class="pre option">--stdin</span></tt>, <tt class="docutils literal"><span class="pre option">--filenames</span></tt>, or <tt class="docutils literal"><span class="pre option">--confirm</span></tt></li>
</ul>
<p>For any given DIRECTORY nimgrep searches only its immediate files without traversing subdirectories unless <tt class="docutils literal"><span class="pre option">--recursive</span></tt> is specified.</p>
</li>
</ol>
<p>In replacement mode we require all 3 positional arguments to avoid damaging.</p>
<p>Options:</p>
<ul class="simple"><li>Mode of operation:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--find, -f</span></tt></div><div class="option-list-description">find the PATTERN (default)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--replace, -!</span></tt></div><div class="option-list-description">replace the PATTERN to REPLACEMENT, rewriting the files</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--confirm</span></tt></div><div class="option-list-description">confirm each occurrence/replacement; there is a chance to abort any time without touching the file</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--filenames</span></tt></div><div class="option-list-description">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:<pre>nimgrep --filenames               # In current dir
nimgrep --filenames &quot;&quot; DIRECTORY
 # Note empty pattern &quot;&quot;, lists all files in DIRECTORY</pre>
</div></div>
</div></li>
<li>Interprete patterns:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--peg</span></tt></div><div class="option-list-description">PATTERN and PAT are Peg</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--re</span></tt></div><div class="option-list-description">PATTERN and PAT are regular expressions (default)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--rex, -x</span></tt></div><div class="option-list-description">use the &quot;extended&quot; syntax for the regular expression so that whitespace is not significant</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--word, -w</span></tt></div><div class="option-list-description">matches should have word boundaries (buggy for pegs!)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--ignoreCase, -i</span></tt></div><div class="option-list-description">be case-insensitive in PATTERN and PAT</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--ignoreStyle, -y</span></tt></div><div class="option-list-description">be style insensitive in PATTERN and PAT</div></div>
</div><div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
PATTERN and patterns PAT (see below in other options) are all either Regex or Peg simultaneously and options <tt class="docutils literal"><span class="pre option">--rex</span></tt>, <tt class="docutils literal"><span class="pre option">--word</span></tt>, <tt class="docutils literal"><span class="pre option">--ignoreCase</span></tt>, and <tt class="docutils literal"><span class="pre option">--ignoreStyle</span></tt> are applied to all of them.</div>
</li>
<li>File system walk:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--recursive, -r</span></tt></div><div class="option-list-description">process directories recursively</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--follow</span></tt></div><div class="option-list-description">follow all symlinks when processing recursively</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--sortTime, -s[:asc|desc]</span></tt></div><div class="option-list-description">order files by the last modification time (default: off): ascending (recent files go last) or descending</div></div>
</div></li>
<li>Filter files (based on filesystem paths):<div class="admonition admonition-info"><span class="admonition-info-text"><b>Hint:</b></span>
Instead of <tt class="docutils literal"><span class="pre option">not</span></tt> you can type just <tt class="docutils literal"><span class="pre option">n</span></tt> for negative options below.</div>
<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--ex[tensions]:EX1|EX2|...</span></tt></div><div class="option-list-description">only search the files with the given extension(s), empty one (<tt class="docutils literal"><span class="pre option">--ex</span></tt>) means files with missing extension</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--notex[tensions]:EX1|EX2|...</span></tt></div><div class="option-list-description">exclude files having given extension(s), use empty one to skip files with no extension (like some binary files are)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--fi[lename]:PAT</span></tt></div><div class="option-list-description">search only files whose name matches pattern PAT</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--notfi[lename]:PAT</span></tt></div><div class="option-list-description">skip files whose name matches pattern PAT</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--di[rname]:PAT</span></tt></div><div class="option-list-description">select files that in their path have a directory name that matches pattern PAT</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--notdi[rname]:PAT</span></tt></div><div class="option-list-description">do not descend into directories whose name (not path) matches pattern PAT</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--dirp[ath]:PAT</span></tt></div><div class="option-list-description">select only files whose whole relative directory path matches pattern PAT</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--notdirp[ath]:PAT</span></tt></div><div class="option-list-description">skip files whose whole relative directory path matches pattern PAT</div></div>
</div></li>
<li>Filter files (based on file contents):<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--inF[ile]:PAT</span></tt></div><div class="option-list-description">select files containing a (not displayed) match of PAT</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--notinF[ile]:PAT</span></tt></div><div class="option-list-description">skip files containing a match of PAT</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--bin:on|off|only</span></tt></div><div class="option-list-description">process binary files? (detected by 0 in first 1K bytes) (default: on - binary and text files treated the same way)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--text, -t</span></tt></div><div class="option-list-description">process only text files, the same as <tt class="docutils literal"><span class="pre option">--bin:off</span></tt></div></div>
</div></li>
<li>Filter matches:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--inC[ontext]:PAT</span></tt></div><div class="option-list-description">select only matches containing a match of PAT in their surrounding context (multiline with <tt class="docutils literal"><span class="pre option">-c</span></tt>, <tt class="docutils literal"><span class="pre option">-a</span></tt>, <tt class="docutils literal"><span class="pre option">-b</span></tt>)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--notinC[ontext]:PAT</span></tt></div><div class="option-list-description">skip matches not containing a match of PAT in their surrounding context</div></div>
</div></li>
<li>Represent results:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--nocolor</span></tt></div><div class="option-list-description">output will be given without any colors</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--color[:on]</span></tt></div><div class="option-list-description">force color even if output is redirected (default: auto)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--colorTheme:THEME</span></tt></div><div class="option-list-description">select color THEME from <tt class="docutils literal"><span class="pre option">simple</span></tt> (default), <tt class="docutils literal"><span class="pre option">bnw</span></tt> (black and white), <tt class="docutils literal"><span class="pre option">ack</span></tt>, or <tt class="docutils literal"><span class="pre option">gnu</span></tt> (GNU grep)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--count</span></tt></div><div class="option-list-description">only print counts of matches for files that matched</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--context:N, -c:N</span></tt></div><div class="option-list-description">print N lines of leading context before every match and N lines of trailing context after it (default N: 0)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--afterContext:N, -a:N</span></tt></div><div class="option-list-description">print N lines of trailing context after every match</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--beforeContext:N, -b:N</span></tt></div><div class="option-list-description">print N lines of leading context before every match</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--group, -g</span></tt></div><div class="option-list-description">group matches by file</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--newLine, -l</span></tt></div><div class="option-list-description">display every matching line starting from a new line</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--cols[:N]</span></tt></div><div class="option-list-description">limit max displayed columns/width of output lines from files by N characters, cropping overflows (default: off)</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--cols:auto, -%</span></tt></div><div class="option-list-description">calculate columns from terminal width for every line</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--onlyAscii, -@</span></tt></div><div class="option-list-description">display only printable ASCII Latin characters 0x20-0x7E substitutions: 0 -&gt; ^@, 1 -&gt; ^A, ... 0x1F -&gt; ^_, 0x7F -&gt; '7F, ..., 0xFF -&gt; 'FF</div></div>
</div></li>
<li>Miscellaneous:<div class="option-list"><div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--threads:N, -j:N</span></tt></div><div class="option-list-description">speed up search by N additional workers (default: 0, off)</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--stdin</span></tt></div><div class="option-list-description">read PATTERN from stdin (to avoid the shell's confusing quoting rules) and, if <tt class="docutils literal"><span class="pre option">--replace</span></tt> given, REPLACEMENT</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--verbose</span></tt></div><div class="option-list-description">be verbose: list every processed file</div></div>
<div class="option-list-item"><div class="option-list-label"><tt><span class="option">--help, -h</span></tt></div><div class="option-list-description">shows this help</div></div>
<div class="option-list-item odd"><div class="option-list-label"><tt><span class="option">--version, -v</span></tt></div><div class="option-list-description">shows the version</div></div>
</div></li>
</ul>

<h2><a class="toc-backref" id="command-line-switches-path-filter-options" href="#command-line-switches-path-filter-options">Path filter options</a></h2><p>Let us assume we have file <tt class="docutils literal"><span class="pre option">dirA/dirB/dirC/file.nim</span></tt>. Filesystem path options will match for these parts of the path:</p>
<table border="1" class="docutils"><tr><th>option</th><th>matches for</th></tr>
<tr><td><tt class="docutils literal"><span class="pre option">--[not]extensions</span></tt></td><td><tt class="docutils literal"><span class="pre">nim</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre option">--[not]filename</span></tt></td><td><tt class="docutils literal"><span class="pre">file.nim</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre option">--[not]dirname</span></tt></td><td><tt class="docutils literal"><span class="pre">dirA</span></tt> and <tt class="docutils literal"><span class="pre">dirB</span></tt> and <tt class="docutils literal"><span class="pre">dirC</span></tt></td></tr>
<tr><td><tt class="docutils literal"><span class="pre option">--[not]dirpath</span></tt></td><td><tt class="docutils literal"><span class="pre">dirA/dirB/dirC</span></tt></td></tr>
</table>
<h2><a class="toc-backref" id="command-line-switches-combining-multiple-filter-options-together-and-negating-them" href="#command-line-switches-combining-multiple-filter-options-together-and-negating-them">Combining multiple filter options together and negating them</a></h2><p>Options for filtering can be provided multiple times so they form a list, which works as:</p>
<ul class="simple"><li>positive filters <tt class="docutils literal"><span class="pre option">--filename</span></tt>, <tt class="docutils literal"><span class="pre option">--dirname</span></tt>, <tt class="docutils literal"><span class="pre option">--dirpath</span></tt>, <tt class="docutils literal"><span class="pre option">--inContext</span></tt>, <tt class="docutils literal"><span class="pre option">--inFile</span></tt> accept files/matches if <em>any</em> pattern from the list is hit</li>
<li>negative filters <tt class="docutils literal"><span class="pre option">--notfilename</span></tt>, <tt class="docutils literal"><span class="pre option">--notdirname</span></tt>, <tt class="docutils literal"><span class="pre option">--notdirpath</span></tt>, <tt class="docutils literal"><span class="pre option">--notinContext</span></tt>, <tt class="docutils literal"><span class="pre option">--notinFile</span></tt> accept files/matches if <em>no</em> pattern from the list is hit.</li>
</ul>
<p>In other words the same filtering option repeated many times means logical OR.</p>
<div class="admonition admonition-warning"><span class="admonition-warning-text"><b>Important:</b></span>
Different filtering options are related by logical AND: they all must be true for a match to be accepted. E.g. <tt class="docutils literal"><span class="pre option">--filename:F --dirname:D1 --notdirname:D2</span></tt> means <tt class="docutils literal"><span class="pre option">filename(F) AND dirname(D1) AND (NOT dirname(D2))</span></tt>.</div>
<p>So negative filtering patterns are effectively related by logical OR also: <tt class="docutils literal"><span class="pre">(NOT PAT1) AND (NOT PAT2) == NOT (PAT1 OR PAT2)</span></tt> in pseudo-code.</p>
<p>That means you can always use only 1 such an option with logical OR, e.g. <tt class="docutils literal"><span class="pre option">--notdirname:PAT1 --notdirname:PAT2</span></tt> is fully equivalent to <tt class="docutils literal"><span class="pre option">--notdirname:'PAT1|PAT2'</span></tt>.</p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
<p>If you want logical AND on patterns you should compose 1 appropriate pattern, possibly combined with multi-line mode <tt class="docutils literal"><span class="pre">(?s)</span></tt>. E.g. to require that multi-line context of matches has occurrences of <strong>both</strong> PAT1 and PAT2 use positive lookaheads (<tt class="docutils literal"><span class="pre">(?=PAT)</span></tt>):</p>
<p><pre class="listing"><span class="program">nimgrep</span> <span class="option">--inContext:</span><span class="option">'(?s)(?=.*PAT1)(?=.*PAT2)'</span></pre></p>
</div>

<h1><a class="toc-backref" id="meaning-of-roof-and-dollar" href="#meaning-of-roof-and-dollar">Meaning of <tt class="docutils literal"><span class="pre">^</span></tt> and <tt class="docutils literal"><span class="pre">$</span></tt></a></h1><p><tt class="docutils literal"><span class="pre"><span class="program">nimgrep</span></span></tt> PCRE engine is run in a single-line mode so <tt class="docutils literal"><span class="pre">^</span></tt> matches the beginning of whole input <em>file</em> and <tt class="docutils literal"><span class="pre">$</span></tt> matches the end of <em>file</em> (or whole input <em>string</em> for options like <tt class="docutils literal"><span class="pre option">--filename</span></tt>).</p>
<p>Add the <tt class="docutils literal"><span class="pre">(?m)</span></tt> modifier to the beginning of your pattern for <tt class="docutils literal"><span class="pre">^</span></tt> and <tt class="docutils literal"><span class="pre">$</span></tt> to match the beginnings and ends of <em>lines</em>.</p>

<h1><a class="toc-backref" id="examples" href="#examples">Examples</a></h1><p>All examples below use default PCRE Regex patterns:</p>
<ul class="simple"><li><p>To search recursively in Nim files using style-insensitive identifiers:</p>
<p><pre class="listing"><span class="program">nimgrep</span> <span class="option">--recursive</span> <span class="option">--ext:</span><span class="option">'nim|nims'</span> <span class="option">--ignoreStyle</span>
<span class="Comment"># short: -r --ext:'nim|nims' -y</span></pre></p>
<div class="admonition admonition-info"><span class="admonition-info-text"><b>Note:</b></span>
we used <tt class="docutils literal"><span class="pre option">'</span></tt> quotes to avoid special treatment of <tt class="docutils literal"><span class="pre option">|</span></tt> symbol for shells like Bash</div>
</li>
<li><p>To exclude version control directories (Git, Mercurial=hg, Subversion=svn) from the search:</p>
<p><pre class="listing"><span class="program">nimgrep</span> <span class="option">--notdirname:</span><span class="option">'^\.git$'</span> <span class="option">--notdirname:</span><span class="option">'^\.hg$'</span> <span class="option">--notdirname:</span><span class="option">'^\.svn$'</span>
<span class="Comment"># short: --ndi:'^\.git$' --ndi:'^\.hg$' --ndi:'^\.svn$'</span></pre></p>
</li>
<li><p>To search only in paths containing the <tt class="docutils literal"><span class="pre">tests</span></tt> sub-directory recursively:</p>
<p><pre class="listing"><span class="program">nimgrep</span> <span class="option">--recursive</span> <span class="option">--dirname:</span><span class="option">'^tests$'</span>
<span class="Comment"># short: -r --di:'^tests$'</span>
<span class="Comment"># or using --dirpath:</span>
<span class="program">nimgrep</span> <span class="option">--recursive</span> <span class="option">--dirpath:</span><span class="option">'(^|/)tests($|/)'</span>
<span class="Comment"># short: -r --pa:'(^|/)tests($|/)'</span></pre></p>
</li>
<li>Nimgrep can search multi-line, e.g. to find files containing <tt class="docutils literal"><span class="pre">import</span></tt> and then <tt class="docutils literal"><span class="pre">strutils</span></tt> use pattern <tt class="docutils literal"><span class="pre">'import(.|\n)*?strutils'</span></tt>.</li>
</ul>
</p>
    
  </div>
</div>

      <div class="twelve-columns footer">
        <span class="nim-sprite"></span>
        <br>
        <small style="color: var(--hint);">Made with Nim. Generated: 2025-02-03 14:56:36 UTC</small>
      </div>
    </div>
  </div>
      <script defer data-domain="nim-lang.org" src="https://plausible.io/js/plausible.js"></script>
    
</body>
</html>