/ 
App-Critique-0.05
River stage zero No dependents
/ App::Critique::Command::tutorial

NAME

App::Critique::Command::tutorial - Tutorial about how to use critique

VERSION

version 0.05

DESCRIPTION

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.

Setup

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.

Initialize

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.

Collect

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 --filter passed.

> 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 (--filter, --match and --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.

Status

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 more or less.

> critique status -v | more

It is useful to run this command regularly and take a look at the status of your work.

Process

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 --back or --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.

AUTHOR

Stevan Little <stevan@cpan.org>

COPYRIGHT AND LICENSE

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.