Skip to content

Latest commit

 

History

History
195 lines (119 loc) · 5.45 KB

gogrep_cli.md

File metadata and controls

195 lines (119 loc) · 5.45 KB
Raw

Command line arguments

Query arguments

-exclude argument

If you want to ignore some directories or files, use -exclude argument. The argument accepts a regexp pattern.

Here is an example that ignores everything under the node_modules folder:

$ gogrep -exclude '/node_modules$' . '<pattern>'

-limit argument

By default, gogrep stops when it finds 1000 matches.

This is due to the fact that it's easy to write a too generic pattern and get overwhelming results on the big code bases.

To increase this limit, specify the -limit argument with some big value you're comfortable with.

If you want to set it to the max value, use -limit 0.

There is still a cap at some value (~100k), but it's not the case for the count mode (-c).

Count mode, -c argument

Count mode discards all match data, but prints the total matches count to the stderr. Disabled by default.

Output formatting arguments

-strict-syntax argument

When strict is false, gogrep may consider 0xA and 10 to be identical. By default, strict-syntax is disabled.

-format argument

Sometimes you want to print the result in some specific way.

Suppose that we have this target.go file:

func f() {
    panic("unimplemented") // Should never happen
}
$ gogrep target.go 'panic($_)'
target.go:3:     panic("unimplemented") // Should never happen

As you see, it prints the whole line and the match location, not just the match. If we want gogrep to output only the matched part, we can use the -format flag.

$ gogrep -format '{{.Match}}' target.go 'panic($_)'
panic("unimplemented")

The default format value is {{.Filename}}:{{.Line}}: {{.MatchLine}}.

Several template variables are available:

  {{.Filename}}  match containing file name
  {{.Line}}      line number where the match started
  {{.MatchLine}} a source code line that contains the match
  {{.Match}}     an entire match string
  {{.x}}         $x submatch string (can be any submatch name)

-abs argument

By default, gogrep prints the relative filenames in the output.

Technically speaking, it sets {{.Filename}} variable to the relative file name.

To get an absolute path there, use -abs argument.

$ gogrep target.go 'append($_, $_)'
target.go:3:     append($data, $elem)

$ gogrep -abs target.go 'append($_, $_)'
/home/quasilyte/target.go:3:     append($data, $elem)

Multi-line mode, -m argument

Some patterns may match a code that spans across multiple lines.

By default, gogrep replaces all newlines with \n sequence, so you can treat all matches as strings without newlines.

If you want to avoid that behavior, -m argument can be used.

// target.go
println(
    1,
    2,
)
$ gogrep target.go 'println(${"*"})'
target.go:2: println(\n    1,\n    2\n)

$ gogrep -m target.go 'println(${"*"})'
target.go:2: println(
    1,
    2,
)

-no-color argument

gogrep inserts ANSI color escapes by default.

You can disable this behavior with the -no-color flag.

-color-filename argument

Specify color scheme for {{.Filename}} format variable. By default, dark-magenta color used.

This argument also can be specified by GOGREP_COLOR_FILENAME environment variable.

-color-line argument

Specify color scheme for {{.Line}} format variable. By default, dark-green color used.

This argument also can be specified by GOGREP_COLOR_LINE environment variable.

-color-match argument

Specify color scheme for {{.Match}} format variable. By default, dark-red color used.

This argument also can be specified by GOGREP_COLOR_MATCH environment variable.

Other arguments

-workers argument

Set the number of concurrent workers. By default, equal to the number of logical CPUs usable by the current process.

-progress argument

To work faster, gogrep doesn't print any search results until it finds them all (or reaches the -limit).

If you're searching through a big (several million SLOC) project, it could take a few seconds to complete. As it might look like the program hangs, gogrep prints its progress in this manner:

N matches so far, processed M files

Where N and M are variables that will change over time.

gogrep has 3 progress reporting modes:

  • none which is a silent mode, no progress will be printed
  • append is the simplest mode that just writes one log message after another
  • update is a more user-friendly mode that will use \r to update the message (default)

To override the default mode, use -progress argument.

Logs are written to the stderr while matches are written to the stdout.

-heatmap argument

A CPU profile that will be used to build a heatmap, needed for IsHot() filters. By default, heatmap profile is not collected.

-heatmap-threshold argument

A threshold argument used to create a heatmap, see perf-heatmap docs on it. By default value is equal to 0.5.

Debug/profiling arguments

-memprofile argument

Write memory profile to the specified file. By default,the memory profile is not collected.

Collects GC usage and current runtime heap profile.

-cpuprofile argument

Write cpu profile to the specified file. By default, the cpu profile is not collected.

-v argument

Output additional verbose information about the execution process. Disabled by default.

This is usually useful only for gogrep tool debugging or troubleshooting.