1ACK(1) User Contributed Perl Documentation ACK(1)
2
6 ack - grep-like text finder
7
9 ack [options] PATTERN [FILE...]
10 ack -f [options] [DIRECTORY...]
11
13 Ack is designed as a replacement for 99% of the uses of grep.
14 Ack searches the named input FILEs (or standard input if no files are
16 named, or the file name - is given) for lines containing a match to the
17 given PATTERN. By default, ack prints the matching lines.
18 Ack can also list files that would be searched, without actually
20 searching them, to let you take advantage of ack's file-type filtering
21 capabilities.
22
24 ack is intelligent about the files it searches. It knows about certain
25 file types, based on both the extension on the file and, in some cases,
26 the contents of the file. These selections can be made with the --type
27 option.
28 With no file selections, ack only searches files of types that it
30 recognizes. If you have a file called foo.wango, and ack doesn't know
31 what a .wango file is, ack won't search it.
32 The -a option tells ack to select all files, regardless of type.
34 Some files will never be selected by ack, even with -a, including:
36 · Backup files: Files matching #*# or ending with ~.
38 · Coredumps: Files matching core.\d+
40 However, ack always searches the files given on the command line, no
42 matter what type. Furthermore, by specifying the -u option all files
43 will be searched.
44
46 ack descends through the directory tree of the starting directories
47 specified. However, it will ignore the shadow directories used by many
48 version control systems, and the build directories used by the Perl
49 MakeMaker system. You may add or remove a directory from this list
50 with the --[no]ignore-dir option. The option may be repeated to
51 add/remove multiple directories from the ignore list.
52 For a complete list of directories that do not get searched, run ack
54 --help.
55
57 ack trumps grep as an everyday tool 99% of the time, but don't throw
58 grep away, because there are times you'll still need it.
59 E.g., searching through huge files looking for regexes that can be
61 expressed with grep syntax should be quicker with grep.
62 If your script or parent program uses grep "--quiet" or "--silent" or
64 needs exit 2 on IO error, use grep.
65
67 -a, --all
68 Operate on all files, regardless of type (but still skip
69 directories like blib, CVS, etc.)
70 -A NUM, --after-context=NUM
72 Print NUM lines of trailing context after matching lines.
73 -B NUM, --before-context=NUM
75 Print NUM lines of leading context before matching lines.
76 -C [NUM], --context[=NUM]
78 Print NUM lines (default 2) of context around matching lines.
79 -c, --count
81 Suppress normal output; instead print a count of matching lines for
82 each input file. If -l is in effect, it will only show the number
83 of lines for each file that has lines matching. Without -l, some
84 line counts may be zeroes.
85 If combined with -h (--no-filename) ack outputs only one total
87 count.
88 --color, --nocolor
90 --color highlights the matching text. --nocolor supresses the
91 color. This is on by default unless the output is redirected.
92 On Windows, this option is off by default unless the
94 Win32::Console::ANSI module is installed or the "ACK_PAGER_COLOR"
95 environment variable is used.
96 --color-filename=color
98 Sets the color to be used for filenames.
99 --color-match=color
101 Sets the color to be used for matches.
102 --color-lineno=color
104 Sets the color to be used for line numbers.
105 --column
107 Show the column number of the first match. This is helpful for
108 editors that can place your cursor at a given position.
109 --env, --noenv
111 --noenv disables all environment processing. No .ackrc is read and
112 all environment variables are ignored. By default, ack considers
113 .ackrc and settings in the environment.
114 --flush
116 --flush flushes output immediately. This is off by default unless
117 ack is running interactively (when output goes to a pipe or file).
118 -f Only print the files that would be searched, without actually doing
120 any searching. PATTERN must not be specified, or it will be taken
121 as a path to search.
122 --follow, --nofollow
124 Follow or don't follow symlinks, other than whatever starting files
125 or directories were specified on the command line.
126 This is off by default.
128 -G REGEX
130 Only paths matching REGEX are included in the search. The entire
131 path and filename are matched against REGEX, and REGEX is a Perl
132 regular expression, not a shell glob.
133 The options -i, -w, -v, and -Q do not apply to this REGEX.
135 -g REGEX
137 Print files where the relative path + filename matches REGEX. This
138 option is a convenience shortcut for -f -G REGEX.
139 The options -i, -w, -v, and -Q do not apply to this REGEX.
141 --group, --nogroup
143 --group groups matches by file name with. This is the default when
144 used interactively.
145 --nogroup prints one result per line, like grep. This is the
147 default when output is redirected.
148 -H, --with-filename
150 Print the filename for each match.
151 -h, --no-filename
153 Suppress the prefixing of filenames on output when multiple files
154 are searched.
155 --help
157 Print a short help statement.
158 -i, --ignore-case
160 Ignore case in the search strings.
161 This applies only to the PATTERN, not to the regexes given for the
163 -g and -G options.
164 --[no]ignore-dir=DIRNAME
166 Ignore directory (as CVS, .svn, etc are ignored). May be used
167 multiple times to ignore multiple directories. For example, mason
168 users may wish to include --ignore-dir=data. The --noignore-dir
169 option allows users to search directories which would normally be
170 ignored (perhaps to research the contents of .svn/props
171 directories).
172 The DIRNAME must always be a simple directory name. Nested
174 directories like foo/bar are NOT supported. You would need to
175 specify --ignore-dir=foo and then no files from any foo directory
176 are taken into account by ack unless given explicitly on the
177 command line.
178 --line=NUM
180 Only print line NUM of each file. Multiple lines can be given with
181 multiple --line options or as a comma separated list
182 (--line=3,5,7). --line=4-7 also works. The lines are always output
183 in ascending order, no matter the order given on the command line.
184 -l, --files-with-matches
186 Only print the filenames of matching files, instead of the matching
187 text.
188 -L, --files-without-matches
190 Only print the filenames of files that do NOT match. This is
191 equivalent to specifying -l and -v.
192 --match REGEX
194 Specify the REGEX explicitly. This is helpful if you don't want to
195 put the regex as your first argument, e.g. when executing multiple
196 searches over the same set of files.
197 # search for foo and bar in given files
199 ack file1 t/file* --match foo
200 ack file1 t/file* --match bar
201 -m=NUM, --max-count=NUM
203 Stop reading a file after NUM matches.
204 --man
206 Print this manual page.
207 -n, --no-recurse
209 No descending into subdirectories.
210 -o Show only the part of each line matching PATTERN (turns off text
212 highlighting)
213 --output=expr
215 Output the evaluation of expr for each line (turns off text
216 highlighting)
217 --pager=program
219 Direct ack's output through program. This can also be specified
220 via the "ACK_PAGER" and "ACK_PAGER_COLOR" environment variables.
221 Using --pager does not suppress grouping and coloring like piping
223 output on the command-line does.
224 --passthru
226 Prints all lines, whether or not they match the expression.
227 Highlighting will still work, though, so it can be used to
228 highlight matches while still seeing the entire file, as in:
229 # Watch a log file, and highlight a certain IP address
231 $ tail -f ~/access.log | ack --passthru 123.45.67.89
232 --print0
234 Only works in conjunction with -f, -g, -l or -c (filename output).
235 The filenames are output separated with a null byte instead of the
236 usual newline. This is helpful when dealing with filenames that
237 contain whitespace, e.g.
238 # remove all files of type html
240 ack -f --html --print0 | xargs -0 rm -f
241 -Q, --literal
243 Quote all metacharacters in PATTERN, it is treated as a literal.
244 This applies only to the PATTERN, not to the regexes given for the
246 -g and -G options.
247 -r, -R, --recurse
249 Recurse into sub-directories. This is the default and just here for
250 compatibility with grep. You can also use it for turning
251 --no-recurse off.
252 --smart-case, --no-smart-case
254 Ignore case in the search strings if PATTERN contains no uppercase
255 characters. This is similar to "smartcase" in vim. This option is
256 off by default.
257 -i always overrides this option.
259 This applies only to the PATTERN, not to the regexes given for the
261 -g and -G options.
262 --sort-files
264 Sorts the found files lexically. Use this if you want your file
265 listings to be deterministic between runs of ack.
266 --show-types
268 Outputs the filetypes that ack associates with each file.
269 Works with -f and -g options.
271 --thpppt
273 Display the all-important Bill The Cat logo. Note that the exact
274 spelling of --thpppppt is not important. It's checked against a
275 regular expression.
276 --type=TYPE, --type=noTYPE
278 Specify the types of files to include or exclude from a search.
279 TYPE is a filetype, like perl or xml. --type=perl can also be
280 specified as --perl, and --type=noperl can be done as --noperl.
281 If a file is of both type "foo" and "bar", specifying --foo and
283 --nobar will exclude the file, because an exclusion takes
284 precedence over an inclusion.
285 Type specifications can be repeated and are ORed together.
287 See ack --help=types for a list of valid types.
289 --type-add TYPE=.EXTENSION[,.EXT2[,...]]
291 Files with the given EXTENSION(s) are recognized as being of (the
292 existing) type TYPE. See also "Defining your own types".
293 --type-set TYPE=.EXTENSION[,.EXT2[,...]]
295 Files with the given EXTENSION(s) are recognized as being of type
296 TYPE. This replaces an existing definition for type TYPE. See also
297 "Defining your own types".
298 -u, --unrestricted
300 All files and directories (including blib/, core.*, ...) are
301 searched, nothing is skipped. When both -u and --ignore-dir are
302 used, the --ignore-dir option has no effect.
303 -v, --invert-match
305 Invert match: select non-matching lines
306 This applies only to the PATTERN, not to the regexes given for the
308 -g and -G options.
309 --version
311 Display version and copyright information.
312 -w, --word-regexp
314 Force PATTERN to match only whole words. The PATTERN is wrapped
315 with "\b" metacharacters.
316 This applies only to the PATTERN, not to the regexes given for the
318 -g and -G options.
319 -1 Stops after reporting first match of any kind. This is different
321 from --max-count=1 or -m1, where only one match per file is shown.
322 Also, -1 works with -f and -g, where -m does not.
323
325 The .ackrc file contains command-line options that are prepended to the
326 command line before processing. Multiple options may live on multiple
327 lines. Lines beginning with a # are ignored. A .ackrc might look like
328 this:
329 # Always sort the files
331 --sort-files
332 # Always color, even if piping to a another program
334 --color
335 # Use "less -r" as my pager
337 --pager=less -r
338 Note that arguments with spaces in them do not need to be quoted, as
340 they are not interpreted by the shell. Basically, each line in the
341 .ackrc file is interpreted as one element of @ARGV.
342 ack looks in your home directory for the .ackrc. You can specify
344 another location with the ACKRC variable, below.
345 If --noenv is specified on the command line, the .ackrc file is
347 ignored.
348
350 ack allows you to define your own types in addition to the predefined
351 types. This is done with command line options that are best put into an
352 .ackrc file - then you do not have to define your types over and over
353 again. In the following examples the options will always be shown on
354 one command line so that they can be easily copy & pasted.
355 ack --perl foo searches for foo in all perl files. ack --help=types
357 tells you, that perl files are files ending in .pl, .pm, .pod or .t. So
358 what if you would like to include .xs files as well when searching for
359 --perl files? ack --type-add perl=.xs --perl foo does this for you.
360 --type-add appends additional extensions to an existing type.
361 If you want to define a new type, or completely redefine an existing
363 type, then use --type-set. ack --type-set eiffel=.e,.eiffel defines the
364 type eiffel to include files with the extensions .e or .eiffel. So to
365 search for all eiffel files containing the word Bertrand use ack
366 --type-set eiffel=.e,.eiffel --eiffel Bertrand. As usual, you can also
367 write --type=eiffel instead of --eiffel. Negation also works, so
368 --noeiffel excludes all eiffel files from a search. Redefining also
369 works: ack --type-set cc=.c,.h and .xs files no longer belong to the
370 type cc.
371 When defining your own types in the .ackrc file you have to use the
373 following:
374 --type-set=eiffel=.e,.eiffel
376 or writing on separate lines
378 --type-set
380 eiffel=.e,.eiffel
381 The following does NOT work in the .ackrc file:
383 --type-set eiffel=.e,.eiffel
385 In order to see all currently defined types, use --help types, e.g.
387 ack --type-set backup=.bak --type-add perl=.perl --help types
388 Restrictions:
390 · The types 'skipped', 'make', 'binary' and 'text' are considered
392 "builtin" and cannot be altered.
393 · The shebang line recognition of the types 'perl', 'ruby', 'php',
395 'python', 'shell' and 'xml' cannot be redefined by --type-set, it
396 is always active. However, the shebang line is only examined for
397 files where the extension is not recognised. Therefore it is
398 possible to say ack --type-set perl=.perl --type-set
399 foo=.pl,.pm,.pod,.t --perl --nofoo and only find your shiny new
400 .perl files (and all files with unrecognized extension and perl on
401 the shebang line).
402
404 For commonly-used ack options, environment variables can make life much
405 easier. These variables are ignored if --noenv is specified on the
406 command line.
407 ACKRC
409 Specifies the location of the .ackrc file. If this file doesn't
410 exist, ack looks in the default location.
411 ACK_OPTIONS
413 This variable specifies default options to be placed in front of
414 any explicit options on the command line.
415 ACK_COLOR_FILENAME
417 Specifies the color of the filename when it's printed in --group
418 mode. By default, it's "bold green".
419 The recognized attributes are clear, reset, dark, bold, underline,
421 underscore, blink, reverse, concealed black, red, green, yellow,
422 blue, magenta, on_black, on_red, on_green, on_yellow, on_blue,
423 on_magenta, on_cyan, and on_white. Case is not significant.
424 Underline and underscore are equivalent, as are clear and reset.
425 The color alone sets the foreground color, and on_color sets the
426 background color.
427 This option can also be set with --color-filename.
429 ACK_COLOR_MATCH
431 Specifies the color of the matching text when printed in --color
432 mode. By default, it's "black on_yellow".
433 This option can also be set with --color-match.
435 See ACK_COLOR_FILENAME for the color specifications.
437 ACK_COLOR_LINENO
439 Specifies the color of the line number when printed in --color
440 mode. By default, it's "bold yellow".
441 This option can also be set with --color-lineno.
443 See ACK_COLOR_FILENAME for the color specifications.
445 ACK_PAGER
447 Specifies a pager program, such as "more", "less" or "most", to
448 which ack will send its output.
449 Using "ACK_PAGER" does not suppress grouping and coloring like
451 piping output on the command-line does, except that on Windows ack
452 will assume that "ACK_PAGER" does not support color.
453 "ACK_PAGER_COLOR" overrides "ACK_PAGER" if both are specified.
455 ACK_PAGER_COLOR
457 Specifies a pager program that understands ANSI color sequences.
458 Using "ACK_PAGER_COLOR" does not suppress grouping and coloring
459 like piping output on the command-line does.
460 If you are not on Windows, you never need to use "ACK_PAGER_COLOR".
462
464 Vim integration
465 ack integrates easily with the Vim text editor. Set this in your .vimrc
466 to use ack instead of grep:
467 set grepprg=ack\ -a
469 That examples uses "-a" to search through all files, but you may use
471 other default flags. Now you can search with ack and easily step
472 through the results in Vim:
473 :grep Dumper perllib
475 Emacs integration
477 Phil Jackson put together an ack.el extension that "provides a simple
478 compilation mode ... has the ability to guess what files you want to
479 search for based on the major-mode."
480 <http://www.shellarchive.co.uk/content/emacs.html>
482 TextMate integration
484 Pedro Melo is a TextMate user who writes "I spend my day mostly inside
485 TextMate, and the built-in find-in-project sucks with large projects.
486 So I hacked a TextMate command that was using find + grep to use ack.
487 The result is the Search in Project with ack, and you can find it here:
488 <http://www.simplicidade.org/notes/archives/2008/03/search_in_proje.html>"
489 Shell and Return Code
491 For greater compatibility with grep, ack in normal use returns shell
492 return or exit code of 0 only if something is found and 1 if no match
493 is found.
494 (Shell exit code 1 is "$?=256" in perl with "system" or backticks.)
496 The grep code 2 for errors is not used.
498 If "-f" or "-g" are specified, then 0 is returned if at least one file
500 is found. If no files are found, then 1 is returned.
501
503 If ack gives you output you're not expecting, start with a few simple
504 steps.
505 Use --noenv
507 Your environment variables and .ackrc may be doing things you're not
508 expecting, or forgotten you specified. Use --noenv to ignore your
509 environment and .ackrc.
510 Use -f to see what files you're scanning
512 The reason I created -f in the first place was as a debugging tool. If
513 ack is not finding matches you think it should find, run ack -f to see
514 what files are being checked.
515
517 Use the .ackrc file.
518 The .ackrc is the place to put all your options you use most of the
519 time but don't want to remember. Put all your --type-add and
520 --type-set definitions in it. If you like --smart-case, set it there,
521 too. I also set --sort-files there.
522 Use -f for working with big codesets
524 Ack does more than search files. "ack -f --perl" will create a list of
525 all the Perl files in a tree, ideal for sending into xargs. For
526 example:
527 # Change all "this" to "that" in all Perl files in a tree.
529 ack -f --perl | xargs perl -p -i -e's/this/that/g'
530 or if you prefer:
532 perl -p -i -e's/this/thatg/' $(ack -f --perl)
534 Use -Q when in doubt about metacharacters
536 If you're searching for something with a regular expression
537 metacharacter, most often a period in a filename or IP address, add the
538 -Q to avoid false positives without all the backslashing. See the
539 following example for more...
540 Use ack to watch log files
542 Here's one I used the other day to find trouble spots for a website
543 visitor. The user had a problem loading troublesome.gif, so I took the
544 access log and scanned it with ack twice.
545 ack -Q aa.bb.cc.dd /path/to/access.log | ack -Q -B5 troublesome.gif
547 The first ack finds only the lines in the Apache log for the given IP.
549 The second finds the match on my troublesome GIF, and shows the
550 previous five lines from the log in each case.
551 Share your knowledge
553 Join the ack-users mailing list. Send me your tips and I may add them
554 here.
555
557 Why isn't ack finding a match in (some file)?
558 Probably because it's of a type that ack doesn't recognize. ack's
559 searching behavior is driven by filetype. If ack doesn't know what
560 kind of file it is, ack ignores the file.
561 Use the "-f" switch to see a list of files that ack will search for
563 you.
564 If you want ack to search files that it doesn't recognize, use the "-a"
566 switch.
567 If you want ack to search every file, even ones that it always ignores
569 like coredumps and backup files, use the "-u" switch.
570 Why does ack ignore unknown files by default?
572 ack is designed by a programmer, for programmers, for searching large
573 trees of code. Most codebases have a lot files in them which aren't
574 source files (like compiled object files, source control metadata,
575 etc), and grep wastes a lot of time searching through all of those as
576 well and returning matches from those files.
577 That's why ack's behavior of not searching things it doesn't recognize
579 is one of its greatest strengths: the speed you get from only searching
580 the things that you want to be looking at.
581 Wouldn't it be great if ack did search & replace?
583 No, ack will always be read-only. Perl has a perfectly good way to do
584 search & replace in files, using the "-i", "-p" and "-n" switches.
585 You can certainly use ack to select your files to update. For example,
587 to change all "foo" to "bar" in all PHP files, you can do this from the
588 Unix shell:
589 $ perl -i -p -e's/foo/bar/g' $(ack -f --php)
591 Can you make ack recognize .xyz files?
593 That's an enhancement. Please see the section in the manual about
594 enhancements.
595 There's already a program/package called ack.
597 Yes, I know.
598 Why is it called ack if it's called ack-grep?
600 The name of the program is "ack". Some packagers have called it "ack-
601 grep" when creating packages because there's already a package out
602 there called "ack" that has nothing to do with this ack.
603 I suggest you make a symlink named ack that points to ack-grep because
605 one of the crucial benefits of ack is having a name that's so short and
606 simple to type.
607 To do that, run this with sudo or as root:
609 ln -s /usr/bin/ack-grep /usr/bin/ack
611 What does ack mean?
613 Nothing. I wanted a name that was easy to type and that you could
614 pronounce as a single syllable.
615 Can I do multi-line regexes?
617 No, ack does not support regexes that match multiple lines. Doing so
618 would require reading in the entire file at a time.
619 If you want to see lines near your match, use the "--A", "--B" and
621 "--C" switches for displaying context.
622
624 Andy Lester, "<andy at petdance.com>"
625
627 Please report any bugs or feature requests to the issues list at
628 Github: <http://github.com/petdance/ack/issues>
629
631 All enhancement requests MUST first be posted to the ack-users mailing
632 list at http://groups.google.com/group/ack-users
633 <http://groups.google.com/group/ack-users>. I will not consider a
634 request without it first getting seen by other ack users. This
635 includes requests for new filetypes.
636 There is a list of enhancements I want to make to ack in the ack issues
638 list at Github: <http://github.com/petdance/ack/issues>
639 Patches are always welcome, but patches with tests get the most
641 attention.
642
644 Support for and information about ack can be found at:
645 · The ack homepage
647 <http://betterthangrep.com/>
649 · The ack issues list at Github
651 <http://github.com/petdance/ack/issues>
653 · AnnoCPAN: Annotated CPAN documentation
655 <http://annocpan.org/dist/ack>
657 · CPAN Ratings
659 <http://cpanratings.perl.org/d/ack>
661 · Search CPAN
663 <http://search.cpan.org/dist/ack>
665 · Git source repository
667 <http://github.com/petdance/ack>
669
671 How appropriate to have acknowledgements!
672 Thanks to everyone who has contributed to ack in any way, including
674 Nick Hooey, Bo Borgerson, Mark Szymanski, Marq Schneider, Packy
675 Anderson, JR Boyens, Dan Sully, Ryan Niebur, Kent Fredric, Mike
676 Morearty, Ingmar Vanhassel, Eric Van Dewoestine, Sitaram Chamarty, Adam
677 James, Richard Carlsson, Pedro Melo, AJ Schuster, Phil Jackson, Michael
678 Schwern, Jan Dubois, Christopher J. Madsen, Matthew Wickline, David
679 Dyck, Jason Porritt, Jjgod Jiang, Thomas Klausner, Uri Guttman, Peter
680 Lewis, Kevin Riggle, Ori Avtalion, Torsten Blix, Nigel Metheringham,
681 Gabor Szabo, Tod Hagan, Michael Hendricks, var Arnfjoerd` Bjarmason,
682 Piers Cawley, Stephen Steneker, Elias Lutfallah, Mark Leighton Fisher,
683 Matt Diephouse, Christian Jaeger, Bill Sully, Bill Ricker, David
684 Golden, Nilson Santos F. Jr, Elliot Shank, Merijn Broeren, Uwe Voelker,
685 Rick Scott, Ask Bjorn Hansen, Jerry Gay, Will Coleda, Mike O'Regan,
686 Slaven ReziX, Mark Stosberg, David Alan Pisoni, Adriano Ferreira, James
687 Keenan, Leland Johnson, Ricardo Signes and Pete Krawczyk.
688
690 Copyright 2005-2010 Andy Lester.
691 This program is free software; you can redistribute it and/or modify it
693 under the terms of the Artistic License v2.0.
694perl v5.12.3 2011-04-22 ACK(1)