diff --git a/doc/rg.1 b/doc/rg.1 index e36ed8a1..7bcccd4f 100644 --- a/doc/rg.1 +++ b/doc/rg.1 @@ -7,12 +7,12 @@ rg \- recursively search current directory for lines matching a pattern .SH SYNOPSIS .PP -rg [\f[I]options\f[]] <\f[I]pattern\f[]> [\f[I]<\f[]path\f[I]> ...\f[]] +rg [\f[I]options\f[]] \f[I]PATTERN\f[] [\f[I]path\f[] ...] .PP -rg [\f[I]options\f[]] (\-e PATTERN | \-f FILE) ... -[\f[I]<\f[]path\f[I]> ...\f[]] +rg [\f[I]options\f[]] [\-e \f[I]pattern\f[] ...] [\-f \f[I]file\f[] ...] +[\f[I]path\f[] ...] .PP -rg [\f[I]options\f[]] \-\-files [\f[I]<\f[]path\f[I]> ...\f[]] +rg [\f[I]options\f[]] \-\-files [\f[I]path\f[] ...] .PP rg [\f[I]options\f[]] \-\-type\-list .PP @@ -71,22 +71,23 @@ Multiple glob flags may be used. Globbing rules match .gitignore globs. Precede a glob with a \[aq]!\[aq] to exclude it. .RS -.RE .PP The \-\-glob flag subsumes the functionality of both the \-\-include and \-\-exclude flags commonly found in other tools. +.PP +Values given to \-g must be quoted or your shell will expand them and +result in unexpected behavior. +.PP +Combine with the \-\-files flag to return matched filenames (i.e., to +replicate ack/ag\[aq]s \-g flag). +For example: .IP .nf \f[C] -Values\ given\ to\ \-g\ must\ be\ quoted\ or\ your\ shell\ will\ expand\ them\ and\ result -in\ unexpected\ behavior. - -Combine\ with\ the\ \-\-files\ flag\ to\ return\ matched\ filenames -(i.e.,\ to\ replicate\ ack/ag\[aq]s\ \-g\ flag). - -For\ example:\ rg\ \-g\ \[aq]\\\[aq]\ \-\-files +rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files \f[] .fi +.RE .TP .B \-h, \-\-help Show this usage message. @@ -134,14 +135,15 @@ Reduce the level of \[aq]smart\[aq] searching. A single \-u doesn\[aq]t respect .gitignore (etc.) files. Two \-u flags will search hidden files and directories. Three \-u flags will search binary files. -\-uu is equivalent to grep \-r, and \-uuu is equivalent to grep \-a \-r. +\-uu is equivalent to \f[C]grep\ \-r\f[], and \-uuu is equivalent to +\f[C]grep\ \-a\ \-r\f[]. .RS .PP Note that the \-u flags are convenient aliases for other combinations of flags. -\-u aliases \[aq]\-\-no\-ignore\[aq]. -\-uu aliases \[aq]\-\-no\-ignore \-\-hidden\[aq]. -\-uuu aliases \[aq]\-\-no\-ignore \-\-hidden \-\-text\[aq]. +\-u aliases \-\-no\-ignore. +\-uu aliases \-\-no\-ignore \-\-hidden. +\-uuu aliases \-\-no\-ignore \-\-hidden \-\-text. .RE .TP .B \-v, \-\-invert\-match @@ -188,9 +190,12 @@ A special format, {type}:none, will clear all color settings for {type}. .PP For example, the following command will change the match color to magenta and the background color for line numbers to yellow: -.PP -rg \-\-colors \[aq]match:fg:magenta\[aq] \-\-colors -\[aq]line:bg:yellow\[aq] foo. +.IP +.nf +\f[C] +rg\ \-\-colors\ \[aq]match:fg:magenta\[aq]\ \-\-colors\ \[aq]line:bg:yellow\[aq]\ foo. +\f[] +.fi .RE .TP .B \-\-column @@ -223,7 +228,7 @@ https://encoding.spec.whatwg.org/#concept\-encoding\-get .RS .RE .TP -.B \-f, \-\-file FILE ... +.B \-f, \-\-file \f[I]FILE\f[] ... Search for patterns from the given file, with one pattern per line. When this flag is used or multiple times or in combination with the \-e/\-\-regexp flag, then all patterns provided are searched. @@ -237,8 +242,12 @@ Print each file that would be searched (but don\[aq]t search). .RS .PP Combine with the \-g flag to return matched paths, for example: -.PP -rg \-g \[aq]\[aq] \-\-files +.IP +.nf +\f[C] +rg\ \-g\ \[aq]*.foo\[aq]\ \-\-files +\f[] +.fi .RE .TP .B \-l, \-\-files\-with\-matches @@ -284,7 +293,7 @@ Search hidden directories and files. .RS .RE .TP -.B \-\-ignore\-file FILE ... +.B \-\-ignore\-file \f[I]FILE\f[] ... Specify additional ignore files for filtering file paths. Ignore files should be in the gitignore format and are matched relative to the current working directory. @@ -387,7 +396,7 @@ A path separator is limited to a single byte. .RE .TP .B \-p, \-\-pretty -Alias for \-\-color=always \-\-heading \-n. +Alias for \-\-color=always \-\-heading \-\-line\-number. .RS .RE .TP @@ -446,9 +455,21 @@ Show the version number of ripgrep and exit. .B \-\-vimgrep Show results with every match on its own line, including line numbers and column numbers. -(With this option, a line with more than one match of the regex will be -printed more than once.) +With this option, a line with more than one match will be printed more +than once. .RS +.PP +Recommended .vimrc configuration: +.IP +.nf +\f[C] +\ \ set\ grepprg=rg\\\ \-\-vimgrep +\ \ set\ grepformat^=%f:%l:%c:%m +\f[] +.fi +.PP +Use :grep to grep for something, then :cn and :cp to navigate through +the matches. .RE .SH FILE TYPE MANAGEMENT OPTIONS .TP @@ -465,11 +486,12 @@ Unless \-\-type\-clear is used, globs are added to any existing globs inside of ripgrep. Note that this must be passed to every invocation of rg. Type settings are NOT persisted. +Example: .RS .IP .nf \f[C] -\ \ Example:\ `rg\ \-\-type\-add\ \[aq]foo:*.foo\[aq]\ \-tfoo\ PATTERN` +\ \ rg\ \-\-type\-add\ \[aq]foo:*.foo\[aq]\ \-tfoo\ PATTERN \f[] .fi .PP @@ -483,7 +505,7 @@ Markdown files, one can use: .IP .nf \f[C] -\ \ `\-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]` +\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq] \f[] .fi .PP @@ -492,7 +514,7 @@ Additional glob rules can still be added to the src type by using the .IP .nf \f[C] -\ \ `\-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]\ \-\-type\-add\ \[aq]src:*.foo\[aq]` +\ \ \-\-type\-add\ \[aq]src:include:cpp,py,md\[aq]\ \-\-type\-add\ \[aq]src:*.foo\[aq] \f[] .fi .PP diff --git a/doc/rg.1.md b/doc/rg.1.md index 77c41280..99bcc652 100644 --- a/doc/rg.1.md +++ b/doc/rg.1.md @@ -4,11 +4,11 @@ rg - recursively search current directory for lines matching a pattern # SYNOPSIS -rg [*options*] <*pattern*> [*<*path*> ...*] +rg [*options*] *PATTERN* [*path* ...] -rg [*options*] (-e PATTERN | -f FILE) ... [*<*path*> ...*] +rg [*options*] [-e *pattern* ...] [-f *file* ...] [*path* ...] -rg [*options*] --files [*<*path*> ...*] +rg [*options*] --files [*path* ...] rg [*options*] --type-list @@ -54,16 +54,16 @@ Project home page: https://github.com/BurntSushi/ripgrep glob flags may be used. Globbing rules match .gitignore globs. Precede a glob with a '!' to exclude it. - The --glob flag subsumes the functionality of both the --include and - --exclude flags commonly found in other tools. + The --glob flag subsumes the functionality of both the --include and + --exclude flags commonly found in other tools. Values given to -g must be quoted or your shell will expand them and result in unexpected behavior. Combine with the --files flag to return matched filenames - (i.e., to replicate ack/ag's -g flag). + (i.e., to replicate ack/ag's -g flag). For example: - For example: rg -g '\' --files + rg -g '*.foo' --files -h, --help : Show this usage message. @@ -91,12 +91,12 @@ Project home page: https://github.com/BurntSushi/ripgrep -u, --unrestricted ... : Reduce the level of 'smart' searching. A single -u doesn't respect .gitignore (etc.) files. Two -u flags will search hidden files and directories. Three - -u flags will search binary files. -uu is equivalent to grep -r, and -uuu is - equivalent to grep -a -r. + -u flags will search binary files. -uu is equivalent to `grep -r`, and -uuu + is equivalent to `grep -a -r`. Note that the -u flags are convenient aliases for other combinations of - flags. -u aliases '--no-ignore'. -uu aliases '--no-ignore --hidden'. - -uuu aliases '--no-ignore --hidden --text'. + flags. -u aliases --no-ignore. -uu aliases --no-ignore --hidden. + -uuu aliases --no-ignore --hidden --text. -v, --invert-match : Invert matching. @@ -130,7 +130,7 @@ Project home page: https://github.com/BurntSushi/ripgrep For example, the following command will change the match color to magenta and the background color for line numbers to yellow: - rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo. + rg --colors 'match:fg:magenta' --colors 'line:bg:yellow' foo. --column : Show column numbers (1 based) in output. This only shows the column @@ -152,7 +152,7 @@ Project home page: https://github.com/BurntSushi/ripgrep Other supported values can be found in the list of labels here: https://encoding.spec.whatwg.org/#concept-encoding-get --f, --file FILE ... +-f, --file *FILE* ... : Search for patterns from the given file, with one pattern per line. When this flag is used or multiple times or in combination with the -e/--regexp flag, then all patterns provided are searched. Empty pattern lines will match all @@ -163,7 +163,7 @@ Project home page: https://github.com/BurntSushi/ripgrep Combine with the -g flag to return matched paths, for example: - rg -g '\' --files + rg -g '*.foo' --files -l, --files-with-matches : Only show path of each file with matches. @@ -192,7 +192,7 @@ Project home page: https://github.com/BurntSushi/ripgrep : Search hidden directories and files. (Hidden directories and files are skipped by default.) ---ignore-file FILE ... +--ignore-file *FILE* ... : Specify additional ignore files for filtering file paths. Ignore files should be in the gitignore format and are matched relative to the current working directory. These ignore files @@ -260,7 +260,7 @@ Project home page: https://github.com/BurntSushi/ripgrep cygwin). A path separator is limited to a single byte. -p, --pretty -: Alias for --color=always --heading -n. +: Alias for --color=always --heading --line-number. -r, --replace *ARG* : Replace every match with the string given when printing search results. @@ -295,9 +295,17 @@ Project home page: https://github.com/BurntSushi/ripgrep : Show the version number of ripgrep and exit. --vimgrep -: Show results with every match on its own line, including line - numbers and column numbers. (With this option, a line with more - than one match of the regex will be printed more than once.) +: Show results with every match on its own line, including + line numbers and column numbers. With this option, a line with + more than one match will be printed more than once. + + Recommended .vimrc configuration: + + set grepprg=rg\ --vimgrep + set grepformat^=%f:%l:%c:%m + + Use :grep to grep for something, then :cn and :cp to navigate through the + matches. # FILE TYPE MANAGEMENT OPTIONS @@ -309,9 +317,9 @@ Project home page: https://github.com/BurntSushi/ripgrep at a time. Multiple --type-add flags can be provided. Unless --type-clear is used, globs are added to any existing globs inside of ripgrep. Note that this must be passed to every invocation of rg. Type settings are NOT - persisted. + persisted. Example: - Example: `rg --type-add 'foo:*.foo' -tfoo PATTERN` + rg --type-add 'foo:*.foo' -tfoo PATTERN --type-add can also be used to include rules from other types with the special include directive. The include directive @@ -321,12 +329,12 @@ Project home page: https://github.com/BurntSushi/ripgrep type called src that matches C++, Python and Markdown files, one can use: - `--type-add 'src:include:cpp,py,md'` + --type-add 'src:include:cpp,py,md' Additional glob rules can still be added to the src type by using the --type-add flag again: - `--type-add 'src:include:cpp,py,md' --type-add 'src:*.foo'` + --type-add 'src:include:cpp,py,md' --type-add 'src:*.foo' Note that type names must consist only of Unicode letters or numbers. Punctuation characters are not allowed. diff --git a/src/app.rs b/src/app.rs index f14e3a0c..bfdafa0e 100644 --- a/src/app.rs +++ b/src/app.rs @@ -14,10 +14,10 @@ Project home page: https://github.com/BurntSushi/ripgrep Use -h for short descriptions and --help for more details."; const USAGE: &'static str = " - rg [OPTIONS] [ ...] - rg [OPTIONS] [-e PATTERN | -f FILE ]... [ ...] - rg [OPTIONS] --files [ ...] - rg [OPTIONS] --type-list"; + rg [options] PATTERN [path ...] + rg [options] [-e pattern ...] [-f file ...] [path ...] + rg [options] --files [path ...] + rg [options] --type-list"; const TEMPLATE: &'static str = "\ {bin} {version} @@ -203,12 +203,13 @@ lazy_static! { doc!(h, "pattern", "A regular expression used for searching.", - "A regular expression used for searching. Multiple patterns \ - may be given. To match a pattern beginning with a -, use [-]."); + "A regular expression used for searching. To match a pattern \ + beginning with a dash, use the -e/--regexp option."); doc!(h, "regexp", - "A regular expression used for searching.", - "A regular expression used for searching. Multiple patterns \ - may be given. To match a pattern beginning with a -, use [-]."); + "Use pattern to search.", + "Use pattern to search. This option can be provided multiple \ + times, where all patterns given are searched. This is also \ + useful when searching for patterns that start with a dash."); doc!(h, "path", "A file or directory to search.", "A file or directory to search. Directories are searched \ @@ -447,7 +448,7 @@ lazy_static! { default when the environment demands it (e.g., cygwin). A path \ separator is limited to a single byte."); doc!(h, "pretty", - "Alias for --color always --heading -n."); + "Alias for --color always --heading --line-number."); doc!(h, "replace", "Replace matches with string given.", "Replace every match with the string given when printing \