Tutorial

Ick coordinates the running of automated rules on your code and other files. Rules can check for conformance, or can transform your files to apply needed modifications.

Rules can be sourced from many places: your code’s repo, a rules repo of your own, a rules repo provided by someone else, or even a local directory. Ick lets you use rules from a number of sources at once.

For this tutorial, we’ll be using two repos. The first will stand in for your code: the code you want to analyze or modify with ick. To start, clone this dead-simple repo:

$ git clone https://github.com/advice-animal/ick-tutorial-sample-1
Cloning into 'ick-tutorial-sample-1'...
$ cd ick-tutorial-sample-1

This repo only has a few files:

├── README.md
├── isort.cfg
└── pyproject.toml

The simple rule we’ll demonstrate moves isort settings from the isort.cfg file into the pyproject.toml file. That rule is in our second repo, but you don’t need to clone it. We’ll refer to it with the --rule-repo option for ick.

Ick can show us the rules available:

$ ick --rules-repo=https://github.com/advice-animal/ick-tutorial-rules-1 list-rules
LATER
=====
* move_isort_cfg

If we run the rules, ick is cautious and shows diff stats of what would change, but no files are changed:

$ ick --rules-repo=https://github.com/advice-animal/ick-tutorial-rules-1 run
-> move_isort_cfg: NEEDS_WORK
     isort.cfg -3
     pyproject.toml +4

This shows that isort.cfg would have three lines deleted, and pyproject.toml would have four lines added.

To see the full diff, use the --patch option:

$ ick --rules-repo=https://github.com/advice-animal/ick-tutorial-rules-1 run --patch
-> move_isort_cfg: NEEDS_WORK
--- a/isort.cfg
+++ b/isort.cfg
@@ -1,3 +0,0 @@
-[settings]
-line_length = 88
-multi_line_output = 3
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,3 +1,7 @@
 [project]
 name = "tutorial-sample"
 description = "A simple bare-bones repo for a tutorial"
+
+[tool.isort]
+line_length = "88"
+multi_line_output = "3"

[WHAT ELSE SHOULD GO HERE?]

Writing rules

Next up if you interested: how to write rules, demonstrated in the Writing rules Tutorial.