WALTER
^{_{KEEPING YOUR CRYSTAL CLEAN}}

What

walter is a command line tool that aims to keep your crystal clean, simplifying the routine checks on staged files that are ready to be committed and help you maintain a healthy and clean codebase.

Why

From a consistency perspective, there are plenty of tools that support us on our never-ending pursue of code-cleanliness. Linters, static code analyzers, code formatters… Great! However, more often than not, our git history ends up cluttered with angry commits fixing violations detected by those tools.

One way to avoid these commits from getting into our history is to run your linters and code formatters before committing your changes. But running these tools against the entire project every time you're committing something can be slow and lead to unexpected or irrelevant results.

This tool allows you to specify a series of commands to run on staged files that match a given pattern.

Installing

Add the following entry to your shard.yml on the development_dependencies section and run shards install.

walter.cr:
  github: gtramontina/walter.cr
  version: <current-version>

^shard.yml

Next, create a .walter.yml at the root of your project with the following content:

expression: \.cr$
command:
  - crystal tool format
  - git add

^.walter.yml

Executing bin/walter now would run crystal tool format and git add on your staged files that match the \.cr$ regular expression. For example, if you have file1.txt, file2.cr and file3.cr, water will run, in this order:

1. crystal tool format file2.cr
2. git add file2.cr
3. crystal tool format file3.cr
4. git add file3.cr

Notice that file1.txt was not referenced, as it doesn't match the \.cr$ regular expression.

Running the commands on each individual staged file was deliberate. The idea is that it would foster a small/atomic commit mindset.

More Examples

Here's a few more configuration examples for you to draw inspiration from:

• Run ameba linting:

expression: \.cr$
command: bin/ameba

• Optimize PNG images with pngcrush:

expression: \.png$
command:
  - pngcrush -ow
  - git add

• All examples at once:

- expression:
    - \.cr$
  command:
    - bin/ameba
    - crystal tool format
    - git add

- expression:
    - \.png$
  command:
    - pngcrush -ow
    - git add

Tips

• Although you can manually run bin/walter before every commit, this quickly becomes boring and quite often forgotten. You can leverage the precommit git hook. Take a look at ghooks.cr. It makes versioning your git hooks easier! Here's an example of a ghooks pre-commit hook (.githooks/pre-commit) configured to run bin/walter:

#!/usr/bin/env sh
bin/walter

^{.githooks/pre-commit}

Help

Walter - Keeping your Crystal clean!

Usage:
  walter
  walter (-c <config> | -C <config-file>)
  walter (-h | --help | -v | --version)

Options:
  -h --help                         Show this screen.
  -v --version                      Show version.
  -c --config=<config>              Rules configuration in YAML.
  -C --config-file=<config-file>    Rules configuration file in YAML [default: .walter.yml]

^{$ bin/walter --help}

Design Decisions

• Every interaction with the operating system is abstracted;
• Methods have only one output (no exceptions or nils). If needed, use the Result class;
• Favor composition over inheritance: augment behavior by decorating existing implementations;

Contributing

Contributions of any kind are very welcome!

Developing

At the root of the project, you'll find a Makefile. This is meant to be the entry point for any build step during development. Running make help will yield you a list of existing phony targets:

make build
make clean
make format
make help
make install (default)
make lint
make test

^{$ make help}

References

• This project is heavily inspired by @okonet's 🚫💩lint-staged. Thank you!
• Icons by Icons8.