"Fossies" - the Fresh Open Source Software Archive

Member "ripgrep-11.0.1/doc/rg.1.txt.tpl" (16 Apr 2019, 7611 Bytes) of package /linux/privat/ripgrep-11.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "rg.1.txt.tpl": 0.10.0_vs_11.0.0.

    1 rg(1)
    2 =====
    3 
    4 Name
    5 ----
    6 rg - recursively search current directory for lines matching a pattern
    7 
    8 
    9 Synopsis
   10 --------
   11 *rg* [_OPTIONS_] _PATTERN_ [_PATH_...]
   12 
   13 *rg* [_OPTIONS_] *-e* _PATTERN_... [_PATH_...]
   14 
   15 *rg* [_OPTIONS_] *-f* _PATTERNFILE_... [_PATH_...]
   16 
   17 *rg* [_OPTIONS_] *--files* [_PATH_...]
   18 
   19 *rg* [_OPTIONS_] *--type-list*
   20 
   21 *command* | *rg* [_OPTIONS_] _PATTERN_
   22 
   23 *rg* [_OPTIONS_] *--help*
   24 
   25 *rg* [_OPTIONS_] *--version*
   26 
   27 
   28 DESCRIPTION
   29 -----------
   30 ripgrep (rg) recursively searches your current directory for a regex pattern.
   31 By default, ripgrep will respect your .gitignore and automatically skip hidden
   32 files/directories and binary files.
   33 
   34 ripgrep's default regex engine uses finite automata and guarantees linear
   35 time searching. Because of this, features like backreferences and arbitrary
   36 look-around are not supported. However, if ripgrep is built with PCRE2, then
   37 the *--pcre2* flag can be used to enable backreferences and look-around.
   38 
   39 ripgrep supports configuration files. Set *RIPGREP_CONFIG_PATH* to a
   40 configuration file. The file can specify one shell argument per line. Lines
   41 starting with *#* are ignored. For more details, see the man page or the
   42 *README*.
   43 
   44 Tip: to disable all smart filtering and make ripgrep behave a bit more like
   45 classical grep, use *rg -uuu*.
   46 
   47 
   48 REGEX SYNTAX
   49 ------------
   50 ripgrep uses Rust's regex engine by default, which documents its syntax:
   51 https://docs.rs/regex/*/regex/#syntax
   52 
   53 ripgrep uses byte-oriented regexes, which has some additional documentation:
   54 https://docs.rs/regex/*/regex/bytes/index.html#syntax
   55 
   56 To a first approximation, ripgrep uses Perl-like regexes without look-around or
   57 backreferences. This makes them very similar to the "extended" (ERE) regular
   58 expressions supported by *egrep*, but with a few additional features like
   59 Unicode character classes.
   60 
   61 If you're using ripgrep with the *--pcre2* flag, then please consult
   62 https://www.pcre.org or the PCRE2 man pages for documentation on the supported
   63 syntax.
   64 
   65 
   66 POSITIONAL ARGUMENTS
   67 --------------------
   68 _PATTERN_::
   69   A regular expression used for searching. To match a pattern beginning with a
   70   dash, use the -e/--regexp option.
   71 
   72 _PATH_::
   73   A file or directory to search. Directories are searched recursively. Paths
   74   specified explicitly on the command line override glob and ignore rules.
   75 
   76 
   77 OPTIONS
   78 -------
   79 Note that for many options, there exist flags to disable them. In some cases,
   80 those flags are not listed in a first class way below. For example, the
   81 *--column* flag (listed below) enables column numbers in ripgrep's output, but
   82 the *--no-column* flag (not listed below) disables them. The reverse can also
   83 exist. For example, the *--no-ignore* flag (listed below) disables ripgrep's
   84 *gitignore* logic, but the *--ignore* flag (not listed below) enables it. These
   85 flags are useful for overriding a ripgrep configuration file on the command
   86 line. Each flag's documentation notes whether an inverted flag exists. In all
   87 cases, the flag specified last takes precedence.
   88 
   89 {OPTIONS}
   90 
   91 
   92 EXIT STATUS
   93 -----------
   94 If ripgrep finds a match, then the exit status of the program is 0. If no match
   95 could be found, then the exit status is 1. If an error occurred, then the exit
   96 status is always 2 unless ripgrep was run with the *--quiet* flag and a match
   97 was found. In summary:
   98 
   99 * `0` exit status occurs only when at least one match was found, and if
  100   no error occurred, unless *--quiet* was given.
  101 * `1` exit status occurs only when no match was found and no error occurred.
  102 * `2` exit status occurs when an error occurred. This is true for both
  103   catastrophic errors (e.g., a regex syntax error) and for soft errors (e.g.,
  104   unable to read a file).
  105 
  106 
  107 CONFIGURATION FILES
  108 -------------------
  109 ripgrep supports reading configuration files that change ripgrep's default
  110 behavior. The format of the configuration file is an "rc" style and is very
  111 simple. It is defined by two rules:
  112 
  113     1. Every line is a shell argument, after trimming whitespace.
  114     2. Lines starting with *#* (optionally preceded by any amount of
  115        whitespace) are ignored.
  116 
  117 ripgrep will look for a single configuration file if and only if the
  118 *RIPGREP_CONFIG_PATH* environment variable is set and is non-empty.
  119 ripgrep will parse shell arguments from this file on startup and will
  120 behave as if the arguments in this file were prepended to any explicit
  121 arguments given to ripgrep on the command line.
  122 
  123 For example, if your ripgreprc file contained a single line:
  124 
  125     --smart-case
  126 
  127 then the following command
  128 
  129     RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo
  130 
  131 would behave identically to the following command
  132 
  133     rg --smart-case foo
  134 
  135 another example is adding types
  136 
  137     --type-add
  138     web:*.{html,css,js}*
  139 
  140 would behave identically to the following command
  141 
  142     rg --type-add 'web:*.{html,css,js}*' foo
  143 
  144 same with using globs
  145 
  146     --glob=!git/*
  147 
  148 or
  149 
  150     --glob
  151     !git/*
  152 
  153 would behave identically to the following command
  154 
  155     rg --glob '!git/*' foo
  156 
  157 ripgrep also provides a flag, *--no-config*, that when present will suppress
  158 any and all support for configuration. This includes any future support
  159 for auto-loading configuration files from pre-determined paths.
  160 
  161 Conflicts between configuration files and explicit arguments are handled
  162 exactly like conflicts in the same command line invocation. That is,
  163 this command:
  164 
  165     RIPGREP_CONFIG_PATH=wherever/.ripgreprc rg foo --case-sensitive
  166 
  167 is exactly equivalent to
  168 
  169     rg --smart-case foo --case-sensitive
  170 
  171 in which case, the *--case-sensitive* flag would override the *--smart-case*
  172 flag.
  173 
  174 
  175 SHELL COMPLETION
  176 ----------------
  177 Shell completion files are included in the release tarball for Bash, Fish, Zsh
  178 and PowerShell.
  179 
  180 For *bash*, move *rg.bash* to *$XDG_CONFIG_HOME/bash_completion*
  181 or */etc/bash_completion.d/*.
  182 
  183 For *fish*, move *rg.fish* to *$HOME/.config/fish/completions*.
  184 
  185 For *zsh*, move *_rg* to one of your *$fpath* directories.
  186 
  187 
  188 CAVEATS
  189 -------
  190 ripgrep may abort unexpectedly when using default settings if it searches a
  191 file that is simultaneously truncated. This behavior can be avoided by passing
  192 the *--no-mmap* flag which will forcefully disable the use of memory maps in
  193 all cases.
  194 
  195 ripgrep may use a large amount of memory depending on a few factors. Firstly,
  196 if ripgrep uses parallelism for search (the default), then the entire output
  197 for each individual file is buffered into memory in order to prevent
  198 interleaving matches in the output. To avoid this, you can disable parallelism
  199 with the *-j1* flag. Secondly, ripgrep always needs to have at least a single
  200 line in memory in order to execute a search. A file with a very long line can
  201 thus cause ripgrep to use a lot of memory. Generally, this only occurs when
  202 searching binary data with the *-a* flag enabled. (When the *-a* flag isn't
  203 enabled, ripgrep will replace all NUL bytes with line terminators, which
  204 typically prevents exorbitant memory usage.) Thirdly, when ripgrep searches
  205 a large file using a memory map, the process will report its resident memory
  206 usage as the size of the file. However, this does not mean ripgrep actually
  207 needed to use that much memory; the operating system will generally handle this
  208 for you.
  209 
  210 
  211 VERSION
  212 -------
  213 {VERSION}
  214 
  215 
  216 HOMEPAGE
  217 --------
  218 https://github.com/BurntSushi/ripgrep
  219 
  220 Please report bugs and feature requests in the issue tracker. Please do your
  221 best to provide a reproducible test case for bugs. This should include the
  222 corpus being searched, the *rg* command, the actual output and the expected
  223 output. Please also include the output of running the same *rg* command but
  224 with the *--debug* flag.
  225 
  226 
  227 AUTHORS
  228 -------
  229 Andrew Gallant <jamslam@gmail.com>