AGENTS.md
Guidance for AI coding agents (and humans) working in the ack3 repository.
What this project is
ack is a grep-like code-searching tool optimized for programmers searching
large source trees. It is written in Perl, distributed on CPAN as ack
(modules under App::Ack::), and also built as a single-file
“standalone” script. The author and maintainer is Andy Lester. Project
home: https://beyondgrep.com/. The license is the Artistic License 2.0.
The current version is in lib/App/Ack.pm ($VERSION) and in the ack
script itself. Current release line: v3.x.
Repository layout
ack: The main program (installed as theackexecutable).lib/App/Ack.pm: Core logic and$VERSION.lib/App/Ack/*.pm: Supporting modules.- Config loading:
ConfigLoader,ConfigDefault,ConfigFinder. - File walking:
Files,File. - Filter system (
Filter/*.pm):Match,Extension,IsPath,FirstLineMatch,Collection,Inverse, etc.
- Config loading:
t/: Test suite.*.t: Perl tests.*.yaml: data-driven CLI tests.Util.pm: shared helpers.swamp/andtext/: fixture trees searched by the tests.
xt/: Author/release tests:coding-standards.t,pod.t,man.t,coresubs.t.dev/: Developer tools and notes.- Scripts:
timings.pl: Times ack in common scenarios against a large checkout (Parrot is the usual one). Rundev/timings.pl --helpfor options. Used bymake timings.display-option-coverage.pl: Readsopts.coverage(written whenACK_OPTION_COVERAGEis set duringmake test) and prints the command-line options the test suite never uses.record-options: Called byt/Util.pmfor each ack command the test suite runs whenACK_OPTION_COVERAGEis set. It appends the options used toopts.coverage.generate-completion-scripts.pl: Builds the bash and zsh completion scripts from the option list, with zsh descriptions. Used bymake completion.bashandmake completion.zsh.find-minimum-dep-versions.pl: Searches for the oldest version of each dependency incpanfilethat ack still runs with. It checks each module alone, so it does not catch version combinations that fail together.crank-mutex: Holds a table of mutually exclusive option combinations (invalid_combinations) for checking that ack rejects them.bench.pl: Benchmarks four regex variants (plain, word-boundary, case-insensitive, and combinations) against one sample line withBenchmark::timethese.generate-rgb-codes.pl: Prints the 216-colorTerm::ANSIColorcube as an HSL grid, for choosing highlight colors.issues-scrub.pl: Maintainer tool. Lists open GitHub issues that lack a label or a milestone. RequiresNet::GitHub.walk: Lists every file under a directory withFile::Next, unsorted, skipping.svndirectories.linecount: Counts lines in each.txtfile under a directory.linecount-fork: Same aslinecount, but splits the work between a finder process and a counting process with a pipe.
- Docker:
docker/:Dockerfile,docker-compose.yml, anddocker-entrypoint.shfor a Perl 5.30 development environment withFile::Nextinstalled. Usage is inDEVELOPERS.md.
- Release and reference documents:
RELEASE-INSTRUCTIONS.md: Step-by-step release process.Cookbook.pm: Usage examples for ack, written as POD. Includes command pipelines and quoting notes for Windows.IGNORE.md: Design notes on--ignore-pathand the bugs reported against--ignore-dirand--ignore-file.multi-process.md: Notes from Rob Hoelz on experiments with running ack across multiple worker processes.questions.md: Q&A on filetype detection and shebang matching.
- Scripts:
garage/: Archived standalone builds of past releases (ack-v3.x.y). Do not modify.squash: Script that concatenates modules intoack-standalone.tack: Runsblib/-built ack from the repo root for quick manual testing.Makefile.PL,cpanfile,MANIFEST: Build and distribution metadata.perlcriticrc,perltidyrc: Lint and format configuration..github/workflows/testsuite.yml: CI: tests on every supported Perl version since 5.10, plus Perl devel, on Linux and macOS.
Generated files (not committed; already in .gitignore): Makefile,
MYMETA.*, blib/, ack-standalone, pm_to_blib, Build, *~.
Hard design constraints
These are settled design decisions (see DESIGN.md). Do not violate them
without an explicit decision from the maintainer.
- Perl 5.10.1 or later, core modules plus
File::Nextonly. No Moose, Moo, or any other CPAN dependency. Do not use the smartmatch operator. - Must build as a single-file standalone script. Its source must contain
only characters in the range
[ -~](printable ASCII).xt/coding-standards.tenforces this, along with the module count below. - Must be distributable on CPAN under the
App::Ack::namespace. - Must run on Windows, and under Perl taint mode.
- No external tools. ack never shells out to
fileor similar utilities. - Text detection uses Perl’s
-Toperator. Filetype detection is only by user-defined rules (the--typedefinitions). - Configuration is command-line only.
.ackrcfiles are just collections of command-line switches. - Not a sed. ack does not replace text, edit files, or invoke editors.
- No default sorting of results. Sorting requires reading the whole directory first, which hurts performance on very large directories.
- Be grep-compatible where possible when deciding on behavior.
Building and testing
Prerequisite check:
perl -MFile::Next -E'say "ack is ready to build!"'
Build and test:
perl Makefile.PL
make
make test # runs test_classic and test_standalone
Individual targets:
make test_classic # tests against lib/ via blib/
make test_standalone # tests against the built ack-standalone
make test_xt # author tests in xt/
make fulltest # classic + standalone + xt
make pytest # runs the YAML-driven tests via t/run_yaml_test.py
make ack-standalone # build the single-file version
make critic # perlcritic with perlcriticrc
Running one test file (requires make first so blib/ is current):
prove -b t/context.t
Quick manual run of the built code from the repo root: ./tack <args>
(again, run make first).
Test notes:
t/*.yamlcases are run byt/run_yaml_test.py(pytest, requires PyYAML). Each case givesargs, and optionallystdout,stderr,exitcode.t/Util.pmprovides helpers (prep_environment,create_globals,touch_ackrc,is_windows,has_io_pty, and so on). Reuse them rather than reimplementing.- Set
ACK_OPTION_COVERAGE=1to record which options the suite exercises;dev/display-option-coverage.pllists the ones it doesn’t. - Some tests are skipped on Windows and some need
IO::Pty. Those skips are intentional, not failures. - Setting
AUTHOR_TESTING,AUTOMATED_TESTING, andRELEASE_TESTINGto 1 turns on extra checks. CI does this.
Coding standards
- Keep
use strict; use warnings;in every module and script. - Format with
perltidy -pro=perltidyrc; the config is inperltidyrc(120-column limit, 4-space indent, no tabs, preserved line endings). make criticmust pass withperlcriticrc.- Keep the code in the printable-ASCII range
[ -~]. Use\x{...}escapes or similar if you need other characters in a test. - Write new code that runs on Perl 5.10.1. Avoid newer syntax (signatures,
postfix dereference,
//=is fine since 5.10, but check each feature). xt/coding-standards.tasserts that there are exactly 20.pmmodules underlib/plusack. If you add or remove a module, update that count in the same change.- New command-line options need tests. Look at existing
t/*.yamlcases for the pattern.
Changes, versioning, and releases
- Add user-visible changes to the
NEXTsection at the top ofChanges, under a heading such as[ENHANCEMENTS],[FIXES], or[SECURITY]. - Do not change the version number in ordinary development work. Version bumps
and the release process are in
dev/RELEASE-INSTRUCTIONS.md: update$VERSIONinlib/App/Ack.pmand theackscript, update theChangesdate and version heading, runmake disttest, tag, and copy the standalone build intogarage/. - Keep
MANIFESTin sync when you add or remove files that belong in the distribution (make manifestregenerates it).
Git workflow
- The default and integration branch is
dev. Create topic branches fromdevand open pull requests againstdev. (DEVELOPERS.mdmentionsmaster, but in this repositorydevis the main branch.) - Commits are cheap. Keep each commit focused, and write a message that says what changed and why.
- Do not commit or push unless asked.
- Do not edit
garage/(archived releases),tags, or generated files. Changes~and editor swap files such as.Changes.swpare not project content. Do not commit them.
Things to avoid
- Adding a CPAN dependency or a non-core Perl module.
- Adding non-ASCII characters to
ackor anylib/module. - Changing default output ordering, or adding text-editing behavior.
- Shelling out to external programs for detection or processing.
- Changing
garage/contents or theack-v3.x.yarchives. - Adding Perl features newer than 5.10.1 without checking the minimum version.
Related projects
- ripgrep (
rg) is a Rust code-search tool that was inspired by ack. It is a separate project with its own design. It respects.gitignoreby default, where ack uses its own filetype rules and ignore settings. ack’s constraints (Perl only, core modules plusFile::Next, no external tools) are the reason ack does not follow ripgrep’s implementation. Do not port ripgrep’s design into ack without checkingDESIGN.mdfirst.
Where to get more context
README.md: user-facing overview and build instructions.DEVELOPERS.md: helper scripts, test rules, branching, and release notes.DESIGN.md: the inviolable design decisions and rejected features.CONTRIBUTING.md: how to request new filetypes (issue first, not a PR).RELEASE-NOTES.mdandChanges: history.