App::Critique::Command::tutorial - Tutorial about how to use critique
Here is a short description of one my workflows. One thing to note is that there is a pretty extensive help system here, so anytime you need more info you can just do critique help or critique help $command_name and get more info.
The very first thing you need to do is navigate to a git checkout directory. Just like git itself, critique needs a working directory to do its work in.
Next you need to initialise a critique session, I have found that focusing on a single Perl::Critic policy at a time can be helpful and so I use the line below to initialize my session.
> critique init -v --perl-critic-policy Variables::ProhibitUnusedVariables
You will likely want to include the
-v (verbose) flag at a minimum, but there is also a
-d (debug) flag which can be helpful.
Next you want to ask critique to find all the files you want to process. This will basically just traverse the directory tree and find all the available perl files, and looks like this:
> critique collect -v --root lib/ExampleCompany/
You can also provide different criteria to help create the file list that you want. You can do this in a few ways, here are some examples.
> critique collect -v --root lib/ --filter ExampleCompany/Db/
This would traverse the lib/ directory, but exclude any paths which match the
> critique collect -v --root lib/ --match /Db/
You can also specify what to include using the
--match argument, the above will traverse lib/ but only match files which have a /Db/ folder in their path.
> critique collect -v --root lib/ --no-violation
You can also tell critique to only collect files which have a Perl::Critic violation in them.
Lastly, it is possible to combine these three arguments (
--no-violation) in any way you choose.
Note that this is a destructive command, it will overwrite any previous files and file associated settings. It is possible however to use
--dry-run flag to specify a non-destructuve test run.
So at this point it is good to know about the
status command. The simplest version will just display information about the files that have been collected and your current status in the critique session.
> critique status
There is also additonal information available in (
-v) verbose mode including the associated
git commit shas for each file and the critique session configuration information. Sometimes this is a lot of information, so I recommend running it through a pager program like
> critique status -v | more
It is useful to run this command regularly and take a look at the status of your work.
So, now onto the actual processing of files, the
process command will do this one file at a time in a loop. If at any point you want to stop processing it is possible to just press
Cntl-C to halt and critique will make every effort to save state.
> critique process -v
This is the only interactive command in this tool and I suggest you use it a few times and read the output carefully. No tutorial I could write will replace just using it a little.
As mentioned above, a simple
Cntl-C will exit the current processing loop. When you resume, you can either pick up where critique thinks you left off, or you can use the
--next arguments to move backwards and forwards through history. Additionaly you can use the
--reset flag to start from the very beginning of the list again.
Lastly, keep in mind that this tool is non-destructive, meaning that it if things don't work correctly, it is as simple as just pressing
Cntl-C and repairing your
git checkout manually.
Stevan Little <email@example.com>
This software is copyright (c) 2016 by Stevan Little.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.