1ACK(1)                User Contributed Perl Documentation               ACK(1)
2
3
4

NAME

6       ack - grep-like text finder
7

SYNOPSIS

9           ack [options] PATTERN [FILE...]
10           ack -f [options] [DIRECTORY...]
11

DESCRIPTION

13       ack is designed as an alternative to grep for programmers.
14
15       ack searches the named input FILEs or DIRECTORYs for lines containing a
16       match to the given PATTERN.  By default, ack prints the matching lines.
17       If no FILE or DIRECTORY is given, the current directory will be
18       searched.
19
20       PATTERN is a Perl regular expression.  Perl regular expressions are
21       commonly found in other programming languages, but for the particulars
22       of their behavior, please consult perlreref
23       <https://perldoc.perl.org/perlreref.html>.  If you don't know how to
24       use regular expression but are interested in learning, you may consult
25       perlretut <https://perldoc.perl.org/perlretut.html>.  If you do not
26       need or want ack to use regular expressions, please see the
27       "-Q"/"--literal" option.
28
29       Ack can also list files that would be searched, without actually
30       searching them, to let you take advantage of ack's file-type filtering
31       capabilities.
32

FILE SELECTION

34       If files are not specified for searching, either on the command line or
35       piped in with the "-x" option, ack delves into subdirectories selecting
36       files for searching.
37
38       ack is intelligent about the files it searches.  It knows about certain
39       file types, based on both the extension on the file and, in some cases,
40       the contents of the file.  These selections can be made with the --type
41       option.
42
43       With no file selection, ack searches through regular files that are not
44       explicitly excluded by --ignore-dir and --ignore-file options, either
45       present in ackrc files or on the command line.
46
47       The default options for ack ignore certain files and directories.
48       These include:
49
50       ·   Backup files: Files matching #*# or ending with ~.
51
52       ·   Coredumps: Files matching core.\d+
53
54       ·   Version control directories like .svn and .git.
55
56       Run ack with the "--dump" option to see what settings are set.
57
58       However, ack always searches the files given on the command line, no
59       matter what type.  If you tell ack to search in a coredump, it will
60       search in a coredump.
61

DIRECTORY SELECTION

63       ack descends through the directory tree of the starting directories
64       specified.  If no directories are specified, the current working
65       directory is used.  However, it will ignore the shadow directories used
66       by many version control systems, and the build directories used by the
67       Perl MakeMaker system.  You may add or remove a directory from this
68       list with the --[no]ignore-dir option. The option may be repeated to
69       add/remove multiple directories from the ignore list.
70
71       For a complete list of directories that do not get searched, run "ack
72       --dump".
73

MATCHING IN A RANGE OF LINES

75       The "--range-start" and "--range-end" options let you specify ranges of
76       lines to search within each file.
77
78       Say you had the following file, called testfile:
79
80           # This function calls print on "foo".
81           sub foo {
82               print 'foo';
83           }
84           my $print = 1;
85           sub bar {
86               print 'bar';
87           }
88           my $task = 'print';
89
90       Calling "ack print" will give us five matches:
91
92           $ ack print testfile
93           # This function calls print on "foo".
94               print 'foo';
95           my $print = 1;
96               print 'bar';
97           my $task = 'print';
98
99       What if we only want to search for "print" within the subroutines?  We
100       can specify ranges of lines that we want ack to search.  The range
101       starts with any line that matches the pattern "^sub \w+", and stops
102       with any line that matches "^}".
103
104           $ ack --range-start='^sub \w+' --range-end='^}' print testfile
105               print 'foo';
106               print 'bar';
107
108       Note that ack searched two ranges of lines.  The listing below shows
109       which lines were in a range and which were out of the range.
110
111           Out # This function calls print on "foo".
112           In  sub foo {
113           In      print 'foo';
114           In  }
115           Out my $print = 1;
116           In  sub bar {
117           In      print 'bar';
118           In  }
119           Out my $task = 'print';
120
121       You don't have to specify both "--range-start" and "--range-end".  IF
122       "--range-start" is omitted, then the range runs from the first line in
123       the file unitl the first line that matches "--range-end".  Similarly,
124       if "--range-end" is omitted, the range runs from the first line
125       matching "--range-start" to the end of the file.
126
127       For example, if you wanted to search all HTML files up until the first
128       instance of the "<body>", you could do
129
130           ack foo --range-end='<body>'
131
132       Or to search after Perl's `__DATA__` or `__END__` markers, you would do
133
134           ack pattern --range-end='^__(END|DATA)__'
135
136       It's possible for a range to start and stop on the same line.  For
137       example
138
139           --range-start='<title>' --range-end='</title>'
140
141       would match this line as both the start and end of the range, making a
142       one-line range.
143
144           <title>Page title</title>
145
146       Note that the patterns in "--range-start" and "--range-end" are not
147       affected by options like "-i", "-w" and "-Q" that modify the behavior
148       of the main pattern being matched.
149
150       Again, ranges only affect where matches are looked for.  Everything
151       else in ack works the same way.  Using "-c" option with a range will
152       give a count of all the matches that appear within those ranges.  The
153       "-l" shows those files that have a match within a range, and the "-L"
154       option shows files that do not have a match within a range.
155
156       The "-v" option for negating a match works inside the range, too.  To
157       see lines that don't match "google" within the "<head>" section of your
158       HTML files, you could do:
159
160           ack google -v --html --range-start='<head' --range-end='</head>'
161
162       Specifying a range to search does not affect how matches are displayed.
163       The context for a match will still be the same, and
164
165       Using the context options work the same way, and will show context
166       lines for matches even if the context lines fall outside the range.
167       Similarly, "--passthru" will show all lines in the file, but only show
168       matches for lines within the range.
169

OPTIONS

171       --ackrc
172           Specifies an ackrc file to load after all others; see "ACKRC
173           LOCATION SEMANTICS".
174
175       -A NUM, --after-context=NUM
176           Print NUM lines of trailing context after matching lines.
177
178       -B NUM, --before-context=NUM
179           Print NUM lines of leading context before matching lines.
180
181       --[no]break
182           Print a break between results from different files. On by default
183           when used interactively.
184
185       -C [NUM], --context[=NUM]
186           Print NUM lines (default 2) of context around matching lines.  You
187           can specify zero lines of context to override another context
188           specified in an ackrc.
189
190       -c, --count
191           Suppress normal output; instead print a count of matching lines for
192           each input file.  If -l is in effect, it will only show the number
193           of lines for each file that has lines matching.  Without -l, some
194           line counts may be zeroes.
195
196           If combined with -h (--no-filename) ack outputs only one total
197           count.
198
199       --[no]color, --[no]colour
200           --color highlights the matching text.  --nocolor suppresses the
201           color.  This is on by default unless the output is redirected.
202
203           On Windows, this option is off by default unless the
204           Win32::Console::ANSI module is installed or the "ACK_PAGER_COLOR"
205           environment variable is used.
206
207       --color-filename=color
208           Sets the color to be used for filenames.
209
210       --color-match=color
211           Sets the color to be used for matches.
212
213       --color-colno=color
214           Sets the color to be used for column numbers.
215
216       --color-lineno=color
217           Sets the color to be used for line numbers.
218
219       --[no]column
220           Show the column number of the first match.  This is helpful for
221           editors that can place your cursor at a given position.
222
223       --create-ackrc
224           Dumps the default ack options to standard output.  This is useful
225           for when you want to customize the defaults.
226
227       --dump
228           Writes the list of options loaded and where they came from to
229           standard output.  Handy for debugging.
230
231       --[no]env
232           --noenv disables all environment processing. No .ackrc is read and
233           all environment variables are ignored. By default, ack considers
234           .ackrc and settings in the environment.
235
236       --flush
237           --flush flushes output immediately.  This is off by default unless
238           ack is running interactively (when output goes to a pipe or file).
239
240       -f  Only print the files that would be searched, without actually doing
241           any searching.  PATTERN must not be specified, or it will be taken
242           as a path to search.
243
244       --files-from=FILE
245           The list of files to be searched is specified in FILE.  The list of
246           files are separated by newlines.  If FILE is "-", the list is
247           loaded from standard input.
248
249           Note that the list of files is not filtered in any way.  If you add
250           "--type=html" in addition to "--files-from", the "--type" will be
251           ignored.
252
253       --[no]filter
254           Forces ack to act as if it were receiving input via a pipe.
255
256       --[no]follow
257           Follow or don't follow symlinks, other than whatever starting files
258           or directories were specified on the command line.
259
260           This is off by default.
261
262       -g PATTERN
263           Print searchable files where the relative path + filename matches
264           PATTERN.
265
266           Note that
267
268               ack -g foo
269
270           is exactly the same as
271
272               ack -f | ack foo
273
274           This means that just as ack will not search, for example, .jpg
275           files, "-g" will not list .jpg files either.  ack is not intended
276           to be a general-purpose file finder.
277
278           Note also that if you have "-i" in your .ackrc that the filenames
279           to be matched will be case-insensitive as well.
280
281           This option can be combined with --color to make it easier to spot
282           the match.
283
284       --[no]group
285           --group groups matches by file name.  This is the default when used
286           interactively.
287
288           --nogroup prints one result per line, like grep.  This is the
289           default when output is redirected.
290
291       -H, --with-filename
292           Print the filename for each match. This is the default unless
293           searching a single explicitly specified file.
294
295       -h, --no-filename
296           Suppress the prefixing of filenames on output when multiple files
297           are searched.
298
299       --[no]heading
300           Print a filename heading above each file's results.  This is the
301           default when used interactively.
302
303       --help
304           Print a short help statement.
305
306       --help-types
307           Print all known types.
308
309       --help-colors
310           Print a chart of various color combinations.
311
312       --help-rgb-colors
313           Like --help-colors but with more precise RGB colors.
314
315       -i, --ignore-case
316           Ignore case distinctions in PATTERN.  Overrides --smart-case and
317           -I.
318
319       -I, --no-ignore-case
320           Turns on case distinctions in PATTERN.  Overrides --smart-case and
321           -i.
322
323       --ignore-ack-defaults
324           Tells ack to completely ignore the default definitions provided
325           with ack.  This is useful in combination with --create-ackrc if you
326           really want to customize ack.
327
328       --[no]ignore-dir=DIRNAME, --[no]ignore-directory=DIRNAME
329           Ignore directory (as CVS, .svn, etc are ignored). May be used
330           multiple times to ignore multiple directories. For example, mason
331           users may wish to include --ignore-dir=data. The --noignore-dir
332           option allows users to search directories which would normally be
333           ignored (perhaps to research the contents of .svn/props
334           directories).
335
336           The DIRNAME must always be a simple directory name. Nested
337           directories like foo/bar are NOT supported. You would need to
338           specify --ignore-dir=foo and then no files from any foo directory
339           are taken into account by ack unless given explicitly on the
340           command line.
341
342       --ignore-file=FILTER:ARGS
343           Ignore files matching FILTER:ARGS.  The filters are specified
344           identically to file type filters as seen in "Defining your own
345           types".
346
347       -k, --known-types
348           Limit selected files to those with types that ack knows about.
349
350       -l, --files-with-matches
351           Only print the filenames of matching files, instead of the matching
352           text.
353
354       -L, --files-without-matches
355           Only print the filenames of files that do NOT match.
356
357       --match PATTERN
358           Specify the PATTERN explicitly. This is helpful if you don't want
359           to put the regex as your first argument, e.g. when executing
360           multiple searches over the same set of files.
361
362               # search for foo and bar in given files
363               ack file1 t/file* --match foo
364               ack file1 t/file* --match bar
365
366       -m=NUM, --max-count=NUM
367           Print only NUM matches out of each file.  If you want to stop ack
368           after printing the first match of any kind, use the -1 options.
369
370       --man
371           Print this manual page.
372
373       -n, --no-recurse
374           No descending into subdirectories.
375
376       -o  Show only the part of each line matching PATTERN (turns off text
377           highlighting).  This is exactly the same as "--output=$&".
378
379       --output=expr
380           Output the evaluation of expr for each line (turns off text
381           highlighting). If PATTERN matches more than once then a line is
382           output for each non-overlapping match.
383
384           expr may contain the strings "\n", "\r" and "\t", which will be
385           expanded to their corresponding characters line feed, carriage
386           return and tab, respectively.
387
388           expr may also contain the following Perl special variables:
389
390           $1 through $9
391               The subpattern from the corresponding set of capturing
392               parentheses.  If your pattern is "(.+) and (.+)", and the
393               string is "this and that', then $1 is "this" and $2 is "that".
394
395           $_  The contents of the line in the file.
396
397           $.  The number of the line in the file.
398
399           $&, "$`" and "$'"
400               $& is the the string matched by the pattern, "$`" is what
401               precedes the match, and "$'" is what follows it.  If the
402               pattern is "gra(ph|nd)" and the string is "lexicographic", then
403               $& is "graph", "$`" is "lexico" and "$'" is "ic".
404
405               Use of these variables in your output will slow down the
406               pattern matching.
407
408           $+  The match made by the last parentheses that matched in the
409               pattern.  For example, if your pattern is "Version:
410               (.+)|Revision: (.+)", then $+ will contain whichever set of
411               parentheses matched.
412
413           $f  $f is available, in "--output" only, to insert the filename.
414               This is a stand-in for the discovered $filename usage in old
415               "ack2 --output", which is disallowed with "ack3" improved
416               security.
417
418               The intended usage is to provide the grep or compile-error
419               syntax needed for editor/IDE go-to-line integration, e.g.
420               "--output=$f:$.:$_" or "--output=$f\t$.\t$&"
421
422       --pager=program, --nopager
423           --pager directs ack's output through program.  This can also be
424           specified via the "ACK_PAGER" and "ACK_PAGER_COLOR" environment
425           variables.
426
427           Using --pager does not suppress grouping and coloring like piping
428           output on the command-line does.
429
430           --nopager cancels any setting in ~/.ackrc, "ACK_PAGER" or
431           "ACK_PAGER_COLOR".  No output will be sent through a pager.
432
433       --passthru
434           Prints all lines, whether or not they match the expression.
435           Highlighting will still work, though, so it can be used to
436           highlight matches while still seeing the entire file, as in:
437
438               # Watch a log file, and highlight a certain IP address.
439               $ tail -f ~/access.log | ack --passthru 123.45.67.89
440
441       --print0
442           Only works in conjunction with -f, -g, -l or -c, options that only
443           list filenames.  The filenames are output separated with a null
444           byte instead of the usual newline. This is helpful when dealing
445           with filenames that contain whitespace, e.g.
446
447               # Remove all files of type HTML.
448               ack -f --html --print0 | xargs -0 rm -f
449
450       -p[N], --proximate[=N]
451           Groups together match lines that are within N lines of each other.
452           This is useful for visually picking out matches that appear close
453           to other matches.
454
455           For example, if you got these results without the "--proximate"
456           option,
457
458               15: First match
459               18: Second match
460               19: Third match
461               37: Fourth match
462
463           they would look like this with "--proximate=1"
464
465               15: First match
466
467               18: Second match
468               19: Third match
469
470               37: Fourth match
471
472           and this with "--proximate=3".
473
474               15: First match
475               18: Second match
476               19: Third match
477
478               37: Fourth match
479
480           If N is omitted, N is set to 1.
481
482       -P  Negates the effect of the --proximate option.  Shortcut for
483           --proximate=0.
484
485       -Q, --literal
486           Quote all metacharacters in PATTERN, it is treated as a literal.
487
488       -r, -R, --recurse
489           Recurse into sub-directories. This is the default and just here for
490           compatibility with grep. You can also use it for turning
491           --no-recurse off.
492
493       --range-start=PATTERN, --range-end=PATTERN
494           Specifies patterns that mark the start and end of a range.  See
495           "MATCHING IN A RANGE OF LINES" for details.
496
497       -s  Suppress error messages about nonexistent or unreadable files.
498           This is taken from fgrep.
499
500       -S, --[no]smart-case, --no-smart-case
501           Ignore case in the search strings if PATTERN contains no uppercase
502           characters. This is similar to "smartcase" in the vim text editor.
503           The options overrides -i and -I.
504
505           -S is a synonym for --smart-case.
506
507           -i always overrides this option.
508
509       --sort-files
510           Sorts the found files lexicographically.  Use this if you want your
511           file listings to be deterministic between runs of ack.
512
513       --show-types
514           Outputs the filetypes that ack associates with each file.
515
516           Works with -f and -g options.
517
518       -t TYPE, --type=TYPE, --TYPE
519           Specify the types of files to include in the search.  TYPE is a
520           filetype, like perl or xml.  --type=perl can also be specified as
521           --perl, although this is deprecated.
522
523           Type inclusions can be repeated and are ORed together.
524
525           See ack --help-types for a list of valid types.
526
527       -T TYPE, --type=noTYPE, --noTYPE
528           Specifies the type of files to exclude from the search.
529           --type=noperl can be done as --noperl, although this is deprecated.
530
531           If a file is of both type "foo" and "bar", specifying both
532           --type=foo and --type=nobar will exclude the file, because an
533           exclusion takes precedence over an inclusion.
534
535       --type-add TYPE:FILTER:ARGS
536           Files with the given ARGS applied to the given FILTER are
537           recognized as being of (the existing) type TYPE.  See also
538           "Defining your own types".
539
540       --type-set TYPE:FILTER:ARGS
541           Files with the given ARGS applied to the given FILTER are
542           recognized as being of type TYPE. This replaces an existing
543           definition for type TYPE.  See also "Defining your own types".
544
545       --type-del TYPE
546           The filters associated with TYPE are removed from Ack, and are no
547           longer considered for searches.
548
549       --[no]underline
550           Turns on underlining of matches, where "underlining" is printing a
551           line of carets under the match.
552
553               $ ack -u foo
554               peanuts.txt
555               17: Come kick the football you fool
556                                 ^^^          ^^^
557               623: Price per square foot
558                                     ^^^
559
560           This is useful if you're dumping the results of an ack run into a
561           text file or printer that doesn't support ANSI color codes.
562
563           The setting of underline does not affect highlighting of matches.
564
565       -v, --invert-match
566           Invert match: select non-matching lines.
567
568       --version
569           Display version and copyright information.
570
571       -w, --word-regexp
572           Force PATTERN to match only whole words.
573
574       -x  An abbreviation for --files-from=-. The list of files to search are
575           read from standard input, with one line per file.
576
577           Note that the list of files is not filtered in any way.  If you add
578           "--type=html" in addition to "-x", the "--type" will be ignored.
579
580       -1  Stops after reporting first match of any kind.  This is different
581           from --max-count=1 or -m1, where only one match per file is shown.
582           Also, -1 works with -f and -g, where -m does not.
583
584       --thpppt
585           Display the all-important Bill The Cat logo.  Note that the exact
586           spelling of --thpppppt is not important.  It's checked against a
587           regular expression.
588
589       --bar
590           Check with the admiral for traps.
591
592       --cathy
593           Chocolate, Chocolate, Chocolate!
594

THE .ackrc FILE

596       The .ackrc file contains command-line options that are prepended to the
597       command line before processing.  Multiple options may live on multiple
598       lines.  Lines beginning with a # are ignored.  A .ackrc might look like
599       this:
600
601           # Always sort the files
602           --sort-files
603
604           # Always color, even if piping to another program
605           --color
606
607           # Use "less -r" as my pager
608           --pager=less -r
609
610       Note that arguments with spaces in them do not need to be quoted, as
611       they are not interpreted by the shell. Basically, each line in the
612       .ackrc file is interpreted as one element of @ARGV.
613
614       ack looks in several locations for .ackrc files; the searching process
615       is detailed in "ACKRC LOCATION SEMANTICS".  These files are not
616       considered if --noenv is specified on the command line.
617

Defining your own types

619       ack allows you to define your own types in addition to the predefined
620       types. This is done with command line options that are best put into an
621       .ackrc file - then you do not have to define your types over and over
622       again. In the following examples the options will always be shown on
623       one command line so that they can be easily copy & pasted.
624
625       File types can be specified both with the the --type=xxx option, or the
626       file type as an option itself.  For example, if you create a filetype
627       of "cobol", you can specify --type=cobol or simply --cobol.  File types
628       must be at least two characters long.  This is why the C language is
629       --cc and the R language is --rr.
630
631       ack --perl foo searches for foo in all perl files. ack --help-types
632       tells you, that perl files are files ending in .pl, .pm, .pod or .t. So
633       what if you would like to include .xs files as well when searching for
634       --perl files? ack --type-add perl:ext:xs --perl foo does this for you.
635       --type-add appends additional extensions to an existing type.
636
637       If you want to define a new type, or completely redefine an existing
638       type, then use --type-set. ack --type-set eiffel:ext:e,eiffel defines
639       the type eiffel to include files with the extensions .e or .eiffel. So
640       to search for all eiffel files containing the word Bertrand use ack
641       --type-set eiffel:ext:e,eiffel --eiffel Bertrand.  As usual, you can
642       also write --type=eiffel instead of --eiffel. Negation also works, so
643       --noeiffel excludes all eiffel files from a search. Redefining also
644       works: ack --type-set cc:ext:c,h and .xs files no longer belong to the
645       type cc.
646
647       When defining your own types in the .ackrc file you have to use the
648       following:
649
650         --type-set=eiffel:ext:e,eiffel
651
652       or writing on separate lines
653
654         --type-set
655         eiffel:ext:e,eiffel
656
657       The following does NOT work in the .ackrc file:
658
659         --type-set eiffel:ext:e,eiffel
660
661       In order to see all currently defined types, use --help-types, e.g.
662       ack --type-set backup:ext:bak --type-add perl:ext:perl --help-types
663
664       In addition to filtering based on extension, ack offers additional
665       filter types.  The generic syntax is --type-set TYPE:FILTER:ARGS; ARGS
666       depends on the value of FILTER.
667
668       is:FILENAME
669           is filters match the target filename exactly.  It takes exactly one
670           argument, which is the name of the file to match.
671
672           Example:
673
674               --type-set make:is:Makefile
675
676       ext:EXTENSION[,EXTENSION2[,...]]
677           ext filters match the extension of the target file against a list
678           of extensions.  No leading dot is needed for the extensions.
679
680           Example:
681
682               --type-set perl:ext:pl,pm,t
683
684       match:PATTERN
685           match filters match the target filename against a regular
686           expression.  The regular expression is made case-insensitive for
687           the search.
688
689           Example:
690
691               --type-set make:match:/(gnu)?makefile/
692
693       firstlinematch:PATTERN
694           firstlinematch matches the first line of the target file against a
695           regular expression.  Like match, the regular expression is made
696           case insensitive.
697
698           Example:
699
700               --type-add perl:firstlinematch:/perl/
701

ACK COLORS

703       ack allows customization of the colors it uses when presenting matches
704       onscreen.  It uses the colors available in Perl's Term::ANSIColor
705       module, which provides the following listed values. Note that case does
706       not matter when using these values.
707
708       There are four different colors ack uses:
709
710           Aspect      Option              Env. variable       Default
711           --------    -----------------   ------------------  ---------------
712           filename    --color-filename    ACK_COLOR_FILENAME  black on_yellow
713           match       --color-match       ACK_COLOR_MATCH     bold green
714           line no.    --color-lineno      ACK COLOR_LINENO    bold yellow
715           column no.  --color-colno       ACK COLOR_COLNO     bold yellow
716
717       The column number column is only used if the column number is shown
718       because of the --column option.
719
720       Colors may be specified by command-line option, such as "ack
721       --color-filename='red on_white'", or by setting an environment
722       variable, such as "ACK_COLOR_FILENAME='red on_white'".  Options for
723       colors can be set in your ACKRC file (See "THE .ackrc FILE").
724
725       ack can understand the following colors for the foreground:
726
727           black red green yellow blue magenta cyan white
728
729       The optional background color is specified by prepending "on_" to one
730       of the foreground colors:
731
732           on_black on_red on_green on_yellow on_blue on_magenta on_cyan on_white
733
734       Each of the foreground colors can be modified with the following
735       attributes, which may or may not be supported by your terminal:
736
737           bold faint italic underline blink reverse concealed
738
739       Any combinations of modifiers can be added to the foreground color. If
740       your terminal supports it, and you enjoy visual punishment, you can
741       specify:
742
743           ack --color-filename="blink italic underline bold red on_yellow"
744
745       For charts of the colors and what they look like, run "ack
746       --help-colors" and "ack --help-rgb-colors".
747
748       If the eight standard colors, in their bold, faint and unmodified
749       states, aren't enough for you to choose from, you can also specify
750       colors by their RGB values.  They are specified as "rgbXYZ" where X, Y,
751       and Z are values between 0 and 5 giving the intensity of red, green and
752       blue, respectively.  Therefore, "rgb500" is pure red, "rgb505" is
753       purple, and so on.
754
755       Background colors can be specified with the "on_" prefix prepended on
756       an RGB color, so that "on_rgb505" would be a purple background.
757
758       The modifier attributes of blink, italic, underscore and so on may or
759       may not work on the RGB colors.
760
761       For a chart of the 216 possible RGB colors, run "ack
762       --help-rgb-colors".
763

ENVIRONMENT VARIABLES

765       For commonly-used ack options, environment variables can make life much
766       easier.  These variables are ignored if --noenv is specified on the
767       command line.
768
769       ACKRC
770           Specifies the location of the user's .ackrc file.  If this file
771           doesn't exist, ack looks in the default location.
772
773       ACK_COLOR_COLNO
774           Color specification for the column number in ack's output.  By
775           default, the column number is not shown.  You have to enable it
776           with the --column option.  See the section "ack Colors" above.
777
778       ACK_COLOR_FILENAME
779           Color specification for the filename in ack's output.  See the
780           section "ack Colors" above.
781
782       ACK_COLOR_LINENO
783           Color specification for the line number in ack's output.  See the
784           section "ack Colors" above.
785
786       ACK_COLOR_MATCH
787           Color specification for the matched text in ack's output.  See the
788           section "ack Colors" above.
789
790       ACK_PAGER
791           Specifies a pager program, such as "more", "less" or "most", to
792           which ack will send its output.
793
794           Using "ACK_PAGER" does not suppress grouping and coloring like
795           piping output on the command-line does, except that on Windows ack
796           will assume that "ACK_PAGER" does not support color.
797
798           "ACK_PAGER_COLOR" overrides "ACK_PAGER" if both are specified.
799
800       ACK_PAGER_COLOR
801           Specifies a pager program that understands ANSI color sequences.
802           Using "ACK_PAGER_COLOR" does not suppress grouping and coloring
803           like piping output on the command-line does.
804
805           If you are not on Windows, you never need to use "ACK_PAGER_COLOR".
806

ACK & OTHER TOOLS

808   Simple vim integration
809       ack integrates easily with the Vim text editor. Set this in your .vimrc
810       to use ack instead of grep:
811
812           set grepprg=ack\ -k
813
814       That example uses "-k" to search through only files of the types ack
815       knows about, but you may use other default flags. Now you can search
816       with ack and easily step through the results in Vim:
817
818         :grep Dumper perllib
819
820   Editor integration
821       Many users have integrated ack into their preferred text editors.  For
822       details and links, see <https://beyondgrep.com/more-tools/>.
823
824   Shell and Return Code
825       For greater compatibility with grep, ack in normal use returns shell
826       return or exit code of 0 only if something is found and 1 if no match
827       is found.
828
829       (Shell exit code 1 is "$?=256" in perl with "system" or backticks.)
830
831       The grep code 2 for errors is not used.
832
833       If "-f" or "-g" are specified, then 0 is returned if at least one file
834       is found.  If no files are found, then 1 is returned.
835

DEBUGGING ACK PROBLEMS

837       If ack gives you output you're not expecting, start with a few simple
838       steps.
839
840   Try it with --noenv
841       Your environment variables and .ackrc may be doing things you're not
842       expecting, or forgotten you specified.  Use --noenv to ignore your
843       environment and .ackrc.
844
845   Use -f to see what files have been selected for searching
846       Ack's -f was originally added as a debugging tool.  If ack is not
847       finding matches you think it should find, run ack -f to see what files
848       have been selected.  You can also add the "--show-types" options to
849       show the type of each file selected.
850
851   Use --dump
852       This lists the ackrc files that are loaded and the options loaded from
853       them.  You may be loading an .ackrc file that you didn't know you were
854       loading.
855

ACKRC LOCATION SEMANTICS

857       Ack can load its configuration from many sources.  The following list
858       specifies the sources Ack looks for configuration files; each one that
859       is found is loaded in the order specified here, and each one overrides
860       options set in any of the sources preceding it.  (For example, if I set
861       --sort-files in my user ackrc, and --nosort-files on the command line,
862       the command line takes precedence)
863
864       ·   Defaults are loaded from App::Ack::ConfigDefaults.  This can be
865           omitted using "--ignore-ack-defaults".
866
867       ·   Global ackrc
868
869           Options are then loaded from the global ackrc.  This is located at
870           "/etc/ackrc" on Unix-like systems.
871
872           Under Windows XP and earlier, the global ackrc is at "C:\Documents
873           and Settings\All Users\Application Data\ackrc"
874
875           Under Windows Vista/7, the global ackrc is at
876           "C:\ProgramData\ackrc"
877
878           The "--noenv" option prevents all ackrc files from being loaded.
879
880       ·   User ackrc
881
882           Options are then loaded from the user's ackrc.  This is located at
883           "$HOME/.ackrc" on Unix-like systems.
884
885           Under Windows XP and earlier, the user's ackrc is at "C:\Documents
886           and Settings\$USER\Application Data\ackrc".
887
888           Under Windows Vista/7, the user's ackrc is at
889           "C:\Users\$USER\AppData\Roaming\ackrc".
890
891           If you want to load a different user-level ackrc, it may be
892           specified with the $ACKRC environment variable.
893
894           The "--noenv" option prevents all ackrc files from being loaded.
895
896       ·   Project ackrc
897
898           Options are then loaded from the project ackrc.  The project ackrc
899           is the first ackrc file with the name ".ackrc" or "_ackrc", first
900           searching in the current directory, then the parent directory, then
901           the grandparent directory, etc.  This can be omitted using
902           "--noenv".
903
904       ·   --ackrc
905
906           The "--ackrc" option may be included on the command line to specify
907           an ackrc file that can override all others.  It is consulted even
908           if "--noenv" is present.
909
910       ·   Command line
911
912           Options are then loaded from the command line.
913

BUGS & ENHANCEMENTS

915       ack is based at GitHub at <https://github.com/beyondgrep/ack3>
916
917       Please report any bugs or feature requests to the issues list at
918       Github: <https://github.com/beyondgrep/ack3/issues>.
919
920       Please include the operating system that you're using; the output of
921       the command "ack --version"; and any customizations in your .ackrc you
922       may have.
923
924       To suggest enhancements, please submit an issue at
925       <https://github.com/beyondgrep/ack3/issues>.  Also read the
926       DEVELOPERS.md file in the ack code repository.
927
928       Also, feel free to discuss your issues on the ack mailing list at
929       <https://groups.google.com/group/ack-users>.
930

SUPPORT

932       Support for and information about ack can be found at:
933
934       ·   The ack homepage
935
936           <https://beyondgrep.com/>
937
938       ·   Source repository
939
940           <https://github.com/beyondgrep/ack3>
941
942       ·   The ack issues list at Github
943
944           <https://github.com/beyondgrep/ack3/issues>
945
946       ·   The ack announcements mailing list
947
948           <https://groups.google.com/group/ack-announcement>
949
950       ·   The ack users' mailing list
951
952           <https://groups.google.com/group/ack-users>
953
954       ·   The ack development mailing list
955
956           <https://groups.google.com/group/ack-users>
957

COMMUNITY

959       There are ack mailing lists and a Slack channel for ack.  See
960       <https://beyondgrep.com/community/> for details.
961

FAQ

963       This is the Frequently Asked Questions list for ack.
964
965   Can I stop using grep now?
966       Many people find ack to be better than grep as an everyday tool 99% of
967       the time, but don't throw grep away, because there are times you'll
968       still need it.  For example, you might be looking through huge log
969       files and not using regular expressions.  In that case, grep will
970       probably perform better.
971
972   Why isn't ack finding a match in (some file)?
973       First, take a look and see if ack is even looking at the file.  ack is
974       intelligent in what files it will search and which ones it won't, but
975       sometimes that can be surprising.
976
977       Use the "-f" switch, with no regex, to see a list of files that ack
978       will search for you.  If your file doesn't show up in the list of files
979       that "ack -f" shows, then ack never looks in it.
980
981   Wouldn't it be great if ack did search & replace?
982       No, ack will always be read-only.  Perl has a perfectly good way to do
983       search & replace in files, using the "-i", "-p" and "-n" switches.
984
985       You can certainly use ack to select your files to update.  For example,
986       to change all "foo" to "bar" in all PHP files, you can do this from the
987       Unix shell:
988
989           $ perl -i -p -e's/foo/bar/g' $(ack -f --php)
990
991   Can I make ack recognize .xyz files?
992       Yes!  Please see "Defining your own types" in the ack manual.
993
994   Will you make ack recognize .xyz files by default?
995       We might, depending on how widely-used the file format is.
996
997       Submit an issue at in the GitHub issue queue at
998       <https://github.com/beyondgrep/ack3/issues>.  Explain what the file
999       format is, where we can find out more about it, and what you have been
1000       using in your .ackrc to support it.
1001
1002       Please do not bother creating a pull request.  The code for filetypes
1003       is trivial compared to the rest of the process we go through.
1004
1005   Why is it called ack if it's called ack-grep?
1006       The name of the program is "ack".  Some packagers have called it "ack-
1007       grep" when creating packages because there's already a package out
1008       there called "ack" that has nothing to do with this ack.
1009
1010       I suggest you make a symlink named ack that points to ack-grep because
1011       one of the crucial benefits of ack is having a name that's so short and
1012       simple to type.
1013
1014       To do that, run this with sudo or as root:
1015
1016          ln -s /usr/bin/ack-grep /usr/bin/ack
1017
1018       Alternatively, you could use a shell alias:
1019
1020           # bash/zsh
1021           alias ack=ack-grep
1022
1023           # csh
1024           alias ack ack-grep
1025
1026   What does ack mean?
1027       Nothing.  I wanted a name that was easy to type and that you could
1028       pronounce as a single syllable.
1029
1030   Can I do multi-line regexes?
1031       No, ack does not support regexes that match multiple lines.  Doing so
1032       would require reading in the entire file at a time.
1033
1034       If you want to see lines near your match, use the "--A", "--B" and
1035       "--C" switches for displaying context.
1036
1037   Why is ack telling me I have an invalid option when searching for "+foo"?
1038       ack treats command line options beginning with "+" or "-" as options;
1039       if you would like to search for these, you may prefix your search term
1040       with "--" or use the "--match" option.  (However, don't forget that "+"
1041       is a regular expression metacharacter!)
1042
1043   Why does "ack '.{40000,}'" fail?  Isn't that a valid regex?
1044       The Perl language limits the repetition quantifier to 32K.  You can
1045       search for ".{32767}" but not ".{32768}".
1046
1047   Ack does "X" and shouldn't, should it?
1048       We try to remain as close to grep's behavior as possible, so when in
1049       doubt, see what grep does!  If there's a mismatch in functionality
1050       there, please submit an issue to GitHub, and/or bring it up on the ack-
1051       users mailing list.
1052

ACKNOWLEDGEMENTS

1054       How appropriate to have acknowledgements!
1055
1056       Thanks to everyone who has contributed to ack in any way, including Dan
1057       Book, Tomasz Konojacki, Salomon Smeke, M. Scott Ford, Anders Eriksson,
1058       H.Merijn Brand, Duke Leto, Gerhard Poul, Ethan Mallove, Marek Kubica,
1059       Ray Donnelly, Nikolaj Schumacher, Ed Avis, Nick Morrott, Austin
1060       Chamberlin, Varadinsky, Sébastien Feugère, Jakub Wilk, Pete Houston,
1061       Stephen Thirlwall, Jonah Bishop, Chris Rebert, Denis Howe, Raúl Gundín,
1062       James McCoy, Daniel Perrett, Steven Lee, Jonathan Perret, Fraser
1063       Tweedale, Raál Gundán, Steffen Jaeckel, Stephan Hohe, Michael Beijen,
1064       Alexandr Ciornii, Christian Walde, Charles Lee, Joe McMahon, John
1065       Warwick, David Steinbrunner, Kara Martens, Volodymyr Medvid, Ron
1066       Savage, Konrad Borowski, Dale Sedivic, Michael McClimon, Andrew Black,
1067       Ralph Bodenner, Shaun Patterson, Ryan Olson, Shlomi Fish, Karen
1068       Etheridge, Olivier Mengue, Matthew Wild, Scott Kyle, Nick Hooey, Bo
1069       Borgerson, Mark Szymanski, Marq Schneider, Packy Anderson, JR Boyens,
1070       Dan Sully, Ryan Niebur, Kent Fredric, Mike Morearty, Ingmar Vanhassel,
1071       Eric Van Dewoestine, Sitaram Chamarty, Adam James, Richard Carlsson,
1072       Pedro Melo, AJ Schuster, Phil Jackson, Michael Schwern, Jan Dubois,
1073       Christopher J. Madsen, Matthew Wickline, David Dyck, Jason Porritt,
1074       Jjgod Jiang, Thomas Klausner, Uri Guttman, Peter Lewis, Kevin Riggle,
1075       Ori Avtalion, Torsten Blix, Nigel Metheringham, Gábor Szabó, Tod Hagan,
1076       Michael Hendricks, Ævar Arnfjörð Bjarmason, Piers Cawley, Stephen
1077       Steneker, Elias Lutfallah, Mark Leighton Fisher, Matt Diephouse,
1078       Christian Jaeger, Bill Sully, Bill Ricker, David Golden, Nilson Santos
1079       F. Jr, Elliot Shank, Merijn Broeren, Uwe Voelker, Rick Scott, Ask Bjørn
1080       Hansen, Jerry Gay, Will Coleda, Mike O'Regan, Slaven Rezić, Mark
1081       Stosberg, David Alan Pisoni, Adriano Ferreira, James Keenan, Leland
1082       Johnson, Ricardo Signes, Pete Krawczyk and Rob Hoelz.
1083

AUTHOR

1085       Andy Lester, "<andy at petdance.com>"
1086
1088       Copyright 2005-2021 Andy Lester.
1089
1090       This program is free software; you can redistribute it and/or modify it
1091       under the terms of the Artistic License v2.0.
1092
1093       See https://www.perlfoundation.org/artistic-license-20.html or the
1094       LICENSE.md file that comes with the ack distribution.
1095
1096
1097
1098perl v5.32.1                      2021-03-13                            ACK(1)
Impressum