TIDYALL(1p)

📦
version 0.85 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 TIDYALL(1p) 💖

User Contributed Perl Documentation — yep bestie, this is the tidyall page, and it's literally your all-in-one code tidier AND validator. One interface, every tidier, no chaos. 🎀

✨ NAME ✨

tidyall — Your all-in-one code tidier and validator 🦋

✨ SYNOPSIS ✨

# Create a tidyall.ini or .tidyallrc at the top of your project
#
[PerlTidy]
select = **/*.{pl,pm,t}
argv = -noll -it=2

[PerlCritic]
select = lib/**/*.pm
ignore = lib/UtterHack.pm
argv = -severity 3

# Process all files in the current project,
# look upwards from cwd for conf file
#
% tidyall -a

# Process one or more specific files,
# look upwards from the first file for conf file
#
% tidyall file [file...]

# Process a directory recursively
#
% tidyall -r dir

✨ DESCRIPTION ✨

okay so real talk: there are SO many great code tidiers and validators out there, and tidyall makes them all available from a single unified interface. one girl, one command, infinite glow-up. 💅

You can run tidyall on a single file or on an entire project hierarchy, and configure which tidiers/validators get applied to which files. And because it's not messy, tidyall will back up files beforehand, and for efficiency it will only consider files that have changed since they were last processed. iconic behavior, honestly. ✨

🌸 What's a tidier? What's a validator? 🌸

A tidier transforms a file so as to improve its appearance without changing its semantics. Examples include perltidy, podtidy and js-beautify <https://npmjs.org/package/js-beautify>.

A validator analyzes a file for some definition of correctness. Examples include perlcritic, podchecker and jshint <http://www.jshint.com/>.

Many tidiers are also validators, e.g. perltidy will throw an error on badly formed Perl. it's giving multitasking queen. 👑

To use a tidier or validator with tidyall it must have a corresponding plugin class, usually under the prefix Code::TidyAll::Plugin::. This distribution comes with plugins for:

  • Perl: perlcritic, perltidy, perltidy-sweet
  • Pod: podchecker, podspell, podtidy
  • Mason: masontidy
  • JavaScript: js-beautify, jshint, jslint
  • JSON: JSON
  • CSS: cssunminifier
  • PHP: phpcs
  • Misc: Code::TidyAll::Plugin::SortLines

See Code::TidyAll::Plugin for information about creating your own plugin. yes bestie, you can build your own. main character energy fr fr. 🦋

✨ USING TIDYALL ✨

tidyall works on a project basis, where a project is just a directory hierarchy of files. svn or git working directories are typical examples of projects. 🧚

The top of the project is called the root directory. In the root directory you'll need a config file named tidyall.ini or .tidyallrc; it defines how various tidiers and validators will be applied to the files in your project. 💖

tidyall will find your root directory and config file automatically depending on how you call it:

  • tidyall file [file...] — tidyall will search upwards from the first file for the conf file.
  • tidyall -p/--pipe file — tidyall will search upwards from the specified file for the conf file.
  • tidyall -a/--all or tidyall -s/--svn or tidyall -g/--git — tidyall will search upwards from the current working directory for the conf file.
  • tidyall -a --root-dir dir — tidyall will expect to find the conf file in the specified root directory.

You can also pass --conf-name to change the name that is searched for, or --conf-file to specify an explicit path. so flexible, we love her. ✨

✨ CONFIGURATION ✨

The config file (tidyall.ini or .tidyallrc) is in Config::INI format. Here's a sample:

ignore = **/*.bak

[PerlTidy]
select = **/*.{pl,pm,t}
argv = -noll -it=2

[PerlCritic]
select = lib/**/*.pm
ignore = lib/UtterHack.pm lib/OneTime/*.pm
argv = -severity 3

[PodTidy]
select = lib/**/*.{pm,pod}

In order, the four sections declare:

  • Always ignore *.bak files.
  • Apply PerlTidy with settings -noll -it=2 to all *.pl, *.pm, and *.t files.
  • Apply PerlCritic with severity 3 to all Perl modules somewhere underneath lib/, except for lib/UtterHack.pm.
  • Apply PodTidy with default settings to all *.pm and *.pod files underneath lib/.

🎀 Standard configuration elements 🎀

[class] or [class description]

The header of each section refers to a tidyall plugin. The name is automatically prefixed with Code::TidyAll::Plugin:: unless it begins with a +, e.g.

; Uses plugin Code::TidyAll::Plugin::PerlTidy
;
[PerlTidy]

; Uses plugin My::TidyAll::Plugin
;
[+My::TidyAll::Plugin]

You can also include an optional description after the class. The description will be ignored and only the first word will be used for the plugin. This allows you to a list a plugin more than once, with different configuration each time. For example, two different PerlCritic configurations:

; Be brutal on libraries
;
[PerlCritic strict]
select = lib/**/*.pm
argv = --brutal

; but gentle on scripts
;
[PerlCritic lenient]
select = bin/**/*.pl
argv = --gentle
Warning: If you simply list the same plugin twice with no description (or the same description), one of them will be silently ignored. 💀 so pls give them different descriptions bestie.

select

One or more File::Zglob patterns, separated by whitespace or on multiple lines, indicating which files to select. At least one is required. e.g.

; All .t and .pl somewhere under bin and t;
; plus all .pm files directly under lib/Foo and lib/Bar
;
select = {bin,t}/**/*.p[lm]
select = lib/{Foo,Bar}/*.pm

; All .txt files anywhere in the project
;
select = **/*.txt

The pattern is relative to the root directory and should have no leading slash. All standard glob characters (*, ?, [], {}) will work; in addition, ** can be used to represent zero or more directories. See File::Zglob documentation for more details. 🌈

ignore

One or more File::Zglob patterns, separated by whitespace or on multiple lines, indicating which files to ignore. This is optional and overrides select. e.g.

; All .pl files anywhere under bin, except bin/awful.pl or anywhere
; under bin/tmp
;
select = bin/**/*.pl
ignore = bin/awful.pl bin/tmp/**/*.pl

Ignore patterns can also specified at the beginning of the file before any plugin section was started, thus making them global. These ignores will be applied for all plugins. global ignores? we stan a boundary-setting queen. 💅

shebang

One or more words on multiple lines, indicating which shebang lines to accept. This is optional and further filters select. e.g.

; All files with no extension anywhere under bin that include a "perl" or
; "perl5" shebang line.
select = bin/**/*
ignore = bin/**/*.*
shebang = perl
shebang = perl5

only_modes

A list of modes, separated by whitespace. e.g.

only_modes = test cli

The plugin will only run if one of these modes is passed to tidyall via -m or --mode.

except_modes

A list of modes, separated by whitespace. e.g.

except_modes = commit editor

The plugin will not run if one of these modes is passed to tidyall via -m or --mode. 🙈

argv

Many plugins (such as perltidy, perlcritic and podtidy) take this option, which specifies arguments to pass to the underlying command-line utility.

weight

This is an integer that is used to sort plugins. By default, tidier plugins run first, then validator plugins, with each group sorted alphabetically. ⭐

✨ PLUGIN ORDER AND ATOMICITY ✨

If multiple plugins match a file, tidiers are applied before validators so that validators are checking the final result. Within those two groups, the plugins are applied in alphabetical order by plugin name/description. order matters, bestie, it's a whole routine. 🎀

You can also explicitly set the weight of each plugin. By default, tidiers have a weight of 50 and validators have a weight of 60. You can set the weight to any integer to influence when the plugin runs.

The application of multiple plugins is all-or-nothing. If an error occurs during the application of any plugin, the file is not modified at all. 🔥

no partial glow-ups here. either the whole file slays or nothing happens. periodt. 💖

✨ COMMAND-LINE OPTIONS ✨

Okay bestie, this is the part where you get to tell tidyall exactly what to do. Every flag, every option, no skips. Let's go 💅

  • -a, --all — Processes all the files. It does a recursive search for every file in the project hierarchy, starting at the root, and processes anything that matches at least one plugin in your config.
  • -i, --ignore — Skips matching files. This one uses zglob syntax. You can pass it more than once, so stack 'em up 🫶
  • -g, --git — Processes all the added or modified files in your current git working directory.
  • -l, --list — Lists each file alongside the plugins it matches (files with zero matches just get skipped, no drama). It does not actually process anything, and it doesn't care whether files are cached. Usually you'd use this with -a, -g, or -s. Like:
% tidyall -a -l
lib/CHI.pm (PerlCritic, PerlTidy, PodTidy)
lib/CHI/Benchmarks.pod (PodTidy)
lib/CHI/CacheObject.pm (PerlCritic, PerlTidy, PodTidy)
  • -m, --mode — An optional mode that can change which plugins actually run. Defaults to "cli". Go peek at the MODES section below, it's giving lore 👑
  • -p path, --pipe path — Reads content from STDIN and writes the result to STDOUT. If it works, tidyall exits with status 0. If something goes wrong, tidyall prints the error to STDERR, mirrors the input content to STDOUT completely unchanged, and exits with status 1. That mirroring is the whole point: you can safely pipe to your destination no matter what happens. 🚰

When you use this option you have to specify exactly one filename, relative or absolute. It's used to figure out which plugins to apply, and also where the root directory and config file live. The file is not actually read, and it doesn't even need to exist. It's just there for vibes and pathing, fr fr.

This option implies --no-backups and --no-cache (because there's literally no actual file) plus --quiet (because we do not want extra output getting mixed into the tidied result).

# Read from STDIN and write to STDOUT, with appropriate plugins
# for some/path.pl (which need not exist)
#
% tidyall --pipe some/path.pl
  • -r, --recursive — Recursively enters any directories you list on the command-line and processes all the files inside. By default, directories you pass on the command-line just generate a warning. 😭
  • -j, --jobs — Says how many jobs should run in parallel. Default is just 1, but if you've got multiple cores this should make tidyall run faster — especially on bigger code bases. Slay the parallelism 💅
  • -s, --svn — Processes all the added or modified files in your current svn working directory.
  • -q, --quiet — Suppresses output, except for errors. 🤫
  • -v, --verbose — Shows extra output.
  • -I path1,path2,... — Adds one or more library paths to @INC, just like Perl's -I. Super useful if --tidyall-class or your plugins live in an alternate lib directory.
  • --backup-ttl duration — How long before backup files can be purged. Can be a number of seconds, or any string that Time::Duration::Parse recognizes — like "4h" or "1day". Defaults to "1h".
  • --check-only — Instead of actually tidying files, it checks whether each file is already tidied (i.e. its tidied version equals its current version) and treats it as an error if not. Test::Code::TidyAll uses this, and so do the svn and git pre-commit hooks, to enforce that you've tidied your files. Yes bestie, it will catch you. 🫣
  • --plugins name — Only runs the specified plugins. The name has to match the name in the config file exactly, including a leading "+" if one exists.

This overrides the --mode option.

Heads up: plugins will still only run on files that match their "select" and "ignore" configuration.

  • --conf-file path — Specify a relative or absolute path to the conf file, instead of searching for it the usual way.
  • --conf-name name — Specify a conf file name to search for instead of the defaults ("tidyall.ini" / ".tidyallrc").
  • --data-dir path — Holds data like backups and cache. Defaults to root_dir/.tidyall.d.
  • --iterations count — Runs each tidier transform count times. Default is 1.

In some cases (hopefully rare) the output of a tidier can differ if you apply it multiple times. You might want multiple iterations to make sure the content "settles" into its final tidied form — especially if you're enforcing tidiness with a version-control hook or a test. Of course, performance will suffer a little. You should rarely need to set this higher than 2.

This only affects tidiers, not validators; e.g. perlcritic and jshint would still only run once.

  • --no-backups — Doesn't back up files before processing. Live dangerously I guess 💀
  • --no-cache — Doesn't cache last-processed times; processes all files every single time. See also --refresh-cache.
  • --no-cleanup — Doesn't clean up temporary files.
  • --output-suffix suffix — A suffix to add to a filename before outputting the modified version, e.g. ".tdy". Default is none, which means overwrite the file.
  • --refresh-cache — Erases any existing cache info before processing each file, then writes new cache info. See also --no-cache.
  • --root-dir — Specify the root directory explicitly. Usually it's inferred from the specified files or the current working directory.
  • --tidyall-class class — A subclass to use instead of "Code::TidyAll".
  • --version — Shows the version of Code::TidyAll that this script invokes.
  • -h, --help — Prints the help message. 🎀

🌸 Specifying options in configuration 🌸

Almost any command-line option can be specified at the top of the config file, above the plugin sections. Just swap the dashes for underscores. Like:

backup_ttl = 4h
iterations = 2
tidyall_class = My::Code::TidyAll

[PerlTidy]
select = **/*.{pl,pm,t}
argv = -noll -it=2

...

If an option is passed in both places, the command-line wins. Periodt.

inc

You can specify "inc" as a global configuration option, outside of any plugin's section. You can specify it more than once to include multiple directories. Any directories you list here get prepended to @INC before loading plugins or a "tidyall_class".

🚦 EXIT STATUS 🚦

"tidyall" exits with status 1 if any errors happened while processing files, and 0 otherwise. Simple as that 💖

👑 MODES 👑

You can use tidyall in a bunch of different contexts, and you may not want to run all plugins in all of them.

You can pass a mode to tidyall via -m or --mode, and then specify that certain plugins should only run in certain modes (via "only_modes") or should run in all but certain modes (via "except_modes").

Examples of modes:

  • "cli" — when invoking tidyall explicitly from the command-line with no mode specified
  • "editor" — when invoking from an editor
  • "commit" — when using a commit hook like Code::TidyAll::SVN::Precommit or Code::TidyAll::Git::Precommit
  • "test" — when using Test::Code::TidyAll

Now, since perlcritic is a bit time-consuming, you might only want to run it during tests and explicit command-line invocation:

[PerlCritic]
select = lib/**/*.pm
only_modes = test cli
...

Or you could say it should run in all modes except the editor:

[PerlCritic]
select = lib/**/*.pm
except_modes = editor
...

If you specify neither "only_modes" nor "except_modes" for a plugin, then it always runs. Main character energy ✨

💾 LAST-PROCESSED CACHE 💾

"tidyall" keeps track of each file's signature after it was last processed. On later runs, it will only process a file if its signature has changed. The cache lives in files under the data dir.

You can force a refresh of the cache with --refresh-cache, or turn the behavior off entirely with --no-cache.

🎀 BACKUPS 🎀

"tidyall" will back up each file before modifying it. The timestamped backups are kept in a separate directory hierarchy under the data dir.

Old backup files get purged automatically as part of occasional "tidyall" runs. The duration in --backup-ttl indicates both the minimum amount of time backups should be kept and how often purges should run. It can be specified as "30m" or "4 hours" or any string acceptable to Time::Duration::Parse. It defaults to "1h" (1 hour).

You can turn off backups with --no-backups.

😭 "MISSING" PREREQS 😭

The "Code::TidyAll" distribution intentionally does not depend on the prereqs needed for each plugin. This means that if you want to use the perltidy, you must install the Perl::Tidy module manually. Yes, you have to go get it yourself bestie, it's not coming with the bundle 🙈

  • etc/editors/tidyall.el <https://raw.github.com/autarch-code/perl-code-tidyall/master/etc/editors/tidyall.el> and etc/editors/tidyall.vim <https://raw.github.com/autarch-code/perl-code-tidyall/master/etc/editors/tidyall.vim> in this distribution contain Emacs and Vim commands for running "tidyall" on the current buffer. You can assign this to the keystroke of your choice (e.g. ctrl-t or ,t). 🌈
  • Code::TidyAll::SVN::Precommit implements a subversion pre-commit hook that checks if all files are tidied and valid according to "tidyall", and rejects the commit if not. No sneaky un-tidied commits allowed 💅
  • Code::TidyAll::Git::Precommit and Code::TidyAll::Git::Prereceive implement git pre-commit and pre-receive hooks, respectively, that check if all files are tidied and valid according to "tidyall".
  • Test::Code::TidyAll is a testing library to check that all the files in your project are in a tidied and valid state.

💀 KNOWN BUGS 💀

  • Does not yet work on Windows. Yeah. That's the whole list. 🫠

🫶 AUTHOR 🫶

Jonathan Swartz

🌟 ACKNOWLEDGMENTS 🌟

Thanks to Jeff Thalhammer for helping me refine this API. Thanks to Jeff for perlcritic, Steve Hancock for perltidy, and all the other authors of great open source tidiers and validators. Icons, every single one 👑

And that's the whole page, bestie! This one's from perl v5.40.1, dated 2025-12-20, and it's the TIDYALL(1p) man page 💖 Go forth and tidy, you absolute legend. 🎀✨🦋

📦 where this page comes from