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

NAME

6       tidyall - Your all-in-one code tidier and validator
7

SYNOPSIS

9           # Create a tidyall.ini or .tidyallrc at the top of your project
10           #
11           [PerlTidy]
12           select = **/*.{pl,pm,t}
13           argv = -noll -it=2
14
15           [PerlCritic]
16           select = lib/**/*.pm
17           ignore = lib/UtterHack.pm
18           argv = -severity 3
19
20           # Process all files in the current project,
21           # look upwards from cwd for conf file
22           #
23           % tidyall -a
24
25           # Process one or more specific files,
26           # look upwards from the first file for conf file
27           #
28           % tidyall file [file...]
29
30           # Process a directory recursively
31           #
32           % tidyall -r dir
33

DESCRIPTION

35       There are a lot of great code tidiers and validators out there.
36       "tidyall" makes them available from a single unified interface.
37
38       You can run "tidyall" on a single file or on an entire project
39       hierarchy, and configure which tidiers/validators are applied to which
40       files. "tidyall" will back up files beforehand, and for efficiency will
41       only consider files that have changed since they were last processed.
42
43   What's a tidier? What's a validator?
44       A tidier transforms a file so as to improve its appearance without
45       changing its semantics. Examples include perltidy, podtidy and js-
46       beautify <https://npmjs.org/package/js-beautify>.
47
48       A validator analyzes a file for some definition of correctness.
49       Examples include perlcritic, podchecker and jshint
50       <http://www.jshint.com/>.
51
52       Many tidiers are also validators, e.g. "perltidy" will throw an error
53       on badly formed Perl.
54
55       To use a tidier or validator with "tidyall" it must have a
56       corresponding plugin class, usually under the prefix
57       "Code::TidyAll::Plugin::".  This distribution comes with plugins for:
58
59       •   Perl: perlcritic, perltidy, perltidy-sweet
60
61       •   Pod: podchecker, podspell, podtidy
62
63       •   Mason: masontidy
64
65       •   JavaScript: js-beautify, jshint, jslint
66
67       •   JSON: JSON
68
69       •   CSS: cssunminifier
70
71       •   PHP: phpcs
72
73       •   Misc: Code::TidyAll::Plugin::SortLines
74
75       See Code::TidyAll::Plugin for information about creating your own
76       plugin.
77

USING TIDYALL

79       "tidyall" works on a project basis, where a project is just a directory
80       hierarchy of files. svn or git working directories are typical examples
81       of projects.
82
83       The top of the project is called the root directory. In the root
84       directory you'll need a config file named "tidyall.ini" or
85       ".tidyallrc"; it defines how various tidiers and validators will be
86       applied to the files in your project.
87
88       "tidyall" will find your root directory and config file automatically
89       depending on how you call it:
90
91       "tidyall file [file...]"
92           "tidyall" will search upwards from the first file for the conf
93           file.
94
95       "tidyall -p/--pipe file"
96           "tidyall" will search upwards from the specified file for the conf
97           file.
98
99       "tidyall -a/--all" or "tidyall -s/--svn" or "tidyall -g/--git"
100           "tidyall" will search upwards from the current working directory
101           for the conf file.
102
103       "tidyall -a --root-dir dir"
104           "tidyall" will expect to find the conf file in the specified root
105           directory.
106
107       You can also pass --conf-name to change the name that is searched for,
108       or --conf-file to specify an explicit path.
109

CONFIGURATION

111       The config file ("tidyall.ini" or ".tidyallrc") is in Config::INI
112       format.  Here's a sample:
113
114           ignore = **/*.bak
115
116           [PerlTidy]
117           select = **/*.{pl,pm,t}
118           argv = -noll -it=2
119
120           [PerlCritic]
121           select = lib/**/*.pm
122           ignore = lib/UtterHack.pm lib/OneTime/*.pm
123           argv = -severity 3
124
125           [PodTidy]
126           select = lib/**/*.{pm,pod}
127
128       In order, the four sections declare:
129
130       •   Always ignore "*.bak" files.
131
132       •   Apply "PerlTidy" with settings "-noll -it=2" to all *.pl, *.pm, and
133           *.t files.
134
135       •   Apply "PerlCritic" with severity 3 to all Perl modules somewhere
136           underneath "lib/", except for "lib/UtterHack.pm".
137
138       •   Apply "PodTidy" with default settings to all *.pm and *.pod files
139           underneath "lib/".
140
141   Standard configuration elements
142       [class] or [class description]
143           The header of each section refers to a tidyall plugin. The name is
144           automatically prefixed with "Code::TidyAll::Plugin::" unless it
145           begins with a '+', e.g.
146
147               ; Uses plugin Code::TidyAll::Plugin::PerlTidy
148               ;
149               [PerlTidy]
150
151               ; Uses plugin My::TidyAll::Plugin
152               ;
153               [+My::TidyAll::Plugin]
154
155           You can also include an optional description after the class. The
156           description will be ignored and only the first word will be used
157           for the plugin. This allows you to a list a plugin more than once,
158           with different configuration each time.  For example, two different
159           "PerlCritic" configurations:
160
161               ; Be brutal on libraries
162               ;
163               [PerlCritic strict]
164               select = lib/**/*.pm
165               argv = --brutal
166
167               ; but gentle on scripts
168               ;
169               [PerlCritic lenient]
170               select = bin/**/*.pl
171               argv = --gentle
172
173           Warning: If you simply list the same plugin twice with no
174           description (or the same description), one of them will be silently
175           ignored.
176
177       select
178           One or more File::Zglob patterns, separated by whitespace or on
179           multiple lines, indicating which files to select. At least one is
180           required. e.g.
181
182               ; All .t and .pl somewhere under bin and t;
183               ; plus all .pm files directly under lib/Foo and lib/Bar
184               ;
185               select = {bin,t}/**/*.p[lm]
186               select = lib/{Foo,Bar}/*.pm
187
188               ; All .txt files anywhere in the project
189               ;
190               select = **/*.txt
191
192           The pattern is relative to the root directory and should have no
193           leading slash.  All standard glob characters ("*", "?", "[]", "{}")
194           will work; in addition, "**" can be used to represent zero or more
195           directories. See File::Zglob documentation for more details.
196
197       ignore
198           One or more File::Zglob patterns, separated by whitespace or on
199           multiple lines, indicating which files to ignore.  This is optional
200           and overrides "select". e.g.
201
202               ; All .pl files anywhere under bin, except bin/awful.pl or anywhere
203               ; under bin/tmp
204               ;
205               select = bin/**/*.pl
206               ignore = bin/awful.pl bin/tmp/**/*.pl
207
208           Ignore patterns can also specified at the beginning of the file
209           before any plugin section was started, thus making them global.
210           These ignores will be applied for all plugins.
211
212       shebang
213           One or more words on multiple lines, indicating which shebang lines
214           to accept.  This is optional and further filters "select".  e.g.
215
216               ; All files with no extension anywhere under bin that include a "perl" or
217               ; "perl5" shebang line.
218               select = bin/**/*
219               ignore = bin/**/*.*
220               shebang = perl
221               shebang = perl5
222
223       only_modes
224           A list of modes, separated by whitespace. e.g.
225
226               only_modes = test cli
227
228           The plugin will only run if one of these modes is passed to
229           "tidyall" via "-m" or "--mode".
230
231       except_modes
232           A list of modes, separated by whitespace. e.g.
233
234               except_modes = commit editor
235
236           The plugin will not run if one of these modes is passed to
237           "tidyall" via "-m" or "--mode".
238
239       argv
240           Many plugins (such as perltidy, perlcritic and podtidy) take this
241           option, which specifies arguments to pass to the underlying
242           command-line utility.
243
244       weight
245           This is an integer that is used to sort plugins. By default, tidier
246           plugins run first, then validator plugins, with each group sorted
247           alphabetically.
248

PLUGIN ORDER AND ATOMICITY

250       If multiple plugins match a file, tidiers are applied before validators
251       so that validators are checking the final result. Within those two
252       groups, the plugins are applied in alphabetical order by plugin
253       name/description.
254
255       You can also explicitly set the weight of each plugin. By default,
256       tidiers have a weight of 50 and validators have a weight of 60. You can
257       set the weight to any integer to influence when the plugin runs.
258
259       The application of multiple plugins is all-or-nothing. If an error
260       occurs during the application of any plugin, the file is not modified
261       at all.
262

COMMAND-LINE OPTIONS

264       -a, --all
265           Process all files. Does a recursive search for all files in the
266           project hierarchy, starting at the root, and processes any file
267           that matches at least one plugin in the configuration.
268
269       -i, --ignore
270           Ignore matching files. This uses zglob syntax. You can pass this
271           option more than once.
272
273       -g, --git
274           Process all added or modified files in the current git working
275           directory.
276
277       -l, --list
278           List each file along with the list of plugins it matches (files
279           without any matches are skipped). Does not actually process any
280           files and does not care whether files are cached. Generally used
281           with -a, -g, or -s. e.g.
282
283               % tidyall -a -l
284               lib/CHI.pm (PerlCritic, PerlTidy, PodTidy)
285               lib/CHI/Benchmarks.pod (PodTidy)
286               lib/CHI/CacheObject.pm (PerlCritic, PerlTidy, PodTidy)
287
288       -m, --mode
289           Optional mode that can affect which plugins run. Defaults to "cli".
290           See "MODES".
291
292       -p path, --pipe path
293           Read content from STDIN and write the resulting content to STDOUT.
294           If successful, tidyall exits with status 0. If an error occurs,
295           tidyall outputs the error message to STDERR, mirrors the input
296           content to STDOUT with no changes, and exits with status 1. The
297           mirroring means that you can safely pipe to your destination
298           regardless of whether an error occurs.
299
300           When specifying this option you must specify exactly one filename,
301           relative or absolute, which will be used to determine which plugins
302           to apply and also where the root directory and configuration file
303           are. The file will not actually be read and does need even need to
304           exist.
305
306           This option implies --no-backups and --no-cache (since there's no
307           actual file) and --quiet (since we don't want to mix extraneous
308           output with the tidied result).
309
310               # Read from STDIN and write to STDOUT, with appropriate plugins
311               # for some/path.pl (which need not exist)
312               #
313               % tidyall --pipe some/path.pl
314
315       -r, --recursive
316           Recursively enter any directories listed on the command-line and
317           process all the files within. By default, directories encountered
318           on the command-line will generate a warning.
319
320       -j, --jobs
321           Specify how many jobs should run in parallel. By default, we only
322           run 1, but if you have multiple cores this should cause tidyall to
323           run faster, especially on larger code bases.
324
325       -s, --svn
326           Process all added or modified files in the current svn working
327           directory.
328
329       -q, --quiet
330           Suppress output except for errors.
331
332       -v, --verbose
333           Show extra output.
334
335       -I path1,path2,...
336           Add one or more library paths to @INC, like Perl's -I. Useful if
337           --tidyall-class or plugins are in an alternate lib directory.
338
339       --backup-ttl duration
340           Amount of time before backup files can be purged. Can be a number
341           of seconds or any string recognized by Time::Duration::Parse, e.g.
342           "4h" or "1day".  Defaults to "1h".
343
344       --check-only
345           Instead of actually tidying files, check if each file is tidied
346           (i.e. if its tidied version is equal to its current version) and
347           consider it an error if not. This is used by Test::Code::TidyAll
348           and the svn and git pre-commit hooks, for example, to enforce that
349           you've tidied your files.
350
351       --plugins name
352           Only run the specified plugins. The name should match the name
353           given in the config file exactly, including a leading "+" if one
354           exists.
355
356           This overrides the "--mode" option.
357
358           Note that plugins will still only run on files which match their
359           "select" and "ignore" configuration.
360
361       --conf-file path
362           Specify relative or absolute path to conf file, instead of
363           searching for it in the usual way.
364
365       --conf-name name
366           Specify a conf file name to search for instead of the defaults
367           ("tidyall.ini" / ".tidyallrc").
368
369       --data-dir path
370           Contains data like backups and cache. Defaults to
371           root_dir/.tidyall.d
372
373       --iterations count
374           Run each tidier transform count times. Default is 1.
375
376           In some cases (hopefully rare) the output from a tidier can be
377           different if it is applied multiple times. You may want to perform
378           multiple iterations to make sure the content "settles" into its
379           final tidied form -- especially if the tidiness is being enforced
380           with a version-control hook or a test. Of course, performance will
381           suffer a little. You should rarely need to set this higher than 2.
382
383           This only affects tidiers, not validators; e.g.  perlcritic and
384           jshint would still only be run once.
385
386       --no-backups
387           Don't backup files before processing.
388
389       --no-cache
390           Don't cache last processed times; process all files every time. See
391           also "--refresh-cache".
392
393       --no-cleanup
394           Don't clean up temporary files.
395
396       --output-suffix suffix
397           Suffix to add to a filename before outputting the modified version,
398           e.g.  ".tdy". Default is none, which means overwrite the file.
399
400       --refresh-cache
401           Erase any existing cache info before processing each file, then
402           write new cache info. See also "--no-cache".
403
404       --root-dir
405           Specify root directory explicitly. Usually this is inferred from
406           the specified files or the current working directory.
407
408       --tidyall-class class
409           Subclass to use instead of "Code::TidyAll".
410
411       --version
412           Show the version of Code::TidyAll that this script invokes.
413
414       -h, --help
415           Print help message
416
417   Specifying options in configuration
418       Almost any command-line option can be specified at the top of the
419       config file, above the plugin sections. Replace dashes with
420       underscores. e.g.
421
422           backup_ttl = 4h
423           iterations = 2
424           tidyall_class = My::Code::TidyAll
425
426           [PerlTidy]
427           select = **/*.{pl,pm,t}
428           argv = -noll -it=2
429
430           ...
431
432       If an option is passed in both places, the command-line takes
433       precedence.
434
435       inc
436
437       You can specify "inc" as a global configuration option outside of any
438       plugin's section. You can specify this more than once to include
439       multiple directories.  Any directories you list here will be prepended
440       to @INC before loading plugins or a "tidyall_class"
441

EXIT STATUS

443       "tidyall" will exit with status 1 if any errors occurred while
444       processing files, and 0 otherwise.
445

MODES

447       You can use tidyall in a number of different contexts, and you may not
448       want to run all plugins in all of them.
449
450       You can pass a mode to tidyall via "-m" or "--mode", and then specify
451       that certain plugins should only be run in certain modes (via
452       "only_modes") or should be run in all but certain modes (via
453       "except_modes").
454
455       Examples of modes:
456
457       •   "cli" - when invoking tidyall explicitly from the command-line with
458           no mode specified
459
460       •   "editor" - when invoking from an editor
461
462       •   "commit" - when using a commit hook like
463           Code::TidyAll::SVN::Precommit or Code::TidyAll::Git::Precommit
464
465       •   "test" - when using Test::Code::TidyAll
466
467       Now since perlcritic is a bit time-consuming, you might only want to
468       run it during tests and explicit command-line invocation:
469
470           [PerlCritic]
471           select = lib/**/*.pm
472           only_modes = test cli
473           ...
474
475       Or you could specify that it be run in all modes except the editor:
476
477           [PerlCritic]
478           select = lib/**/*.pm
479           except_modes = editor
480           ...
481
482       If you specify neither "only_modes" nor "except_modes" for a plugin,
483       then it will always run.
484

LAST-PROCESSED CACHE

486       "tidyall" keeps track of each file's signature after it was last
487       processed. On subsequent runs, it will only process a file if its
488       signature has changed. The cache is kept in files under the data dir.
489
490       You can force a refresh of the cache with "--refresh-cache", or turn
491       off the behavior entirely with "--no-cache".
492

BACKUPS

494       "tidyall" will backup each file before modifying it. The timestamped
495       backups are kept in a separate directory hierarchy under the data dir.
496
497       Old backup files will be purged automatically as part of occasional
498       "tidyall" runs. The duration specified in "--backup-ttl" indicates both
499       the minimum amount of time backups should be kept, and the frequency
500       that purges should be run. It may be specified as "30m" or "4 hours" or
501       any string acceptable to Time::Duration::Parse. It defaults to "1h" (1
502       hour).
503
504       You can turn off backups with "--no-backups".
505

"MISSING" PREREQS

507       The "Code::TidyAll" distribution intentionally does not depend on the
508       prereqs needed for each plugin. This means that if you want to use the
509       perltidy, you must install the Perl::Tidy module manually.
510
512       •   etc/editors/tidyall.el <https://raw.github.com/autarch-code/perl-
513           code-tidyall/master/etc/editors/tidyall.el> and
514           etc/editors/tidyall.vim <https://raw.github.com/autarch-code/perl-
515           code-tidyall/master/etc/editors/tidyall.vim> in this distribution
516           contains Emacs and Vim commands for running "tidyall" on the
517           current buffer. You can assign this to the keystroke of your choice
518           (e.g.  ctrl-t or ,t).
519
520       •   Code::TidyAll::SVN::Precommit implements a subversion pre-commit
521           hook that checks if all files are tidied and valid according to
522           "tidyall", and rejects the commit if not.
523
524       •   Code::TidyAll::Git::Precommit and Code::TidyAll::Git::Prereceive
525           implement git pre-commit and pre-receive hooks, respectively, that
526           check if all files are tidied and valid according to "tidyall".
527
528       •   Test::Code::TidyAll is a testing library to check that all the
529           files in your project are in a tidied and valid state.
530

KNOWN BUGS

532       •   Does not yet work on Windows
533

AUTHOR

535       Jonathan Swartz
536

ACKNOWLEDGMENTS

538       Thanks to Jeff Thalhammer for helping me refine this API. Thanks to
539       Jeff for perlcritic, Steve Hancock for perltidy, and all the other
540       authors of great open source tidiers and validators.
541
542
543
544perl v5.32.1                      2021-01-27                        TIDYALL(1)
Impressum