Churn

Discover refactoring candidates by identifying the most frequently-edited files with the highest cyclomatic complexity

Table of Contents

• What Is it?
• How to Use?
• How to Install?
• Understanding Churn Scores
• Similar Packages

What is it?

churn is a package that helps you identify .ex and .exs files in your project that could be good candidates for refactoring. It examines each Elixir file in the path it is provided and:

• Checks how many commits it has.
• Calculates the cyclomatic complexity.
• Creates a score based on these two values.

The results are displayed in a table:

How to use

After installing, run mix churn.

You can use these options to customize how Churn runs:

--min-score-to-show (-s shortcut)

Example:
mix churn -s 2

--commit-since (-t shortcut)

Example:
mix churn -t "2 months ago"

--directories-to-scan (-d shortcut)

Example:
-d lib,test

--file-extensions [-e shortcut]

Example
mix churn -e "ex,exs"

--files-to-ignore [-i shortcut]

Example
mix churn -i "lib/churn/hello_world.ex"

--config [-c shortcut]

Example
mix churn -c foo/bar.exs

How to install

The package can be installed by adding churn to your list of dependencies in mix.exs as follows. You also need to copy .churn.exs into your project.

Update your mix.exs:

def deps do
  [
    {:churn, "~> 0.1", only: :dev}
  ]
end

Copy and configure the .churn.exs file:

%{
  #
  # Minimum score to show in the output table.
  #
  min_score_to_show: 0,

  #
  # Specify when to look for commits. (This string is passed to `git rev-list
  # --since [value]`, so any human-readable string it understands is
  # acceptable.)
  #
  commit_since: "1 year ago",

  #
  # Describes output type for the Churn results
  #
  output_type: :console,

  #
  # Where to find files to analyse and look for refactoring candidates.
  #
  directories_to_scan: ["lib", "apps/*/lib"],

  #
  # Which extensions should be used for seeking files to analyse.
  #
  file_extensions: ["ex", "exs"],

  #
  # Determines files should we ignore and protect from analysis.
  #
  files_to_ignore: []
}

Understanding Churn Scores

Churn will always identify top-scoring files. Also, all scores produced by Churn are relative to the project.

For example, in a newly-generated Mix project, with a simple HelloWorld module, that file will be scored 1.0 and be listed as the sole refactoring candidate. In any real project, the same module would have a very low score.

On the other hand, in a project where every module is complex and frequently-modified, some modules may receive low scores which would receive high scores if they were part of a different project.

When you see the results Churn produces, consider them the most likely refactoring candidates for this project. Whether they actually need refactoring is up to you.

Docs: https://hexdocs.pm/churn.

Similar Packages

• https://github.com/danmayer/churn (Ruby)
• https://github.com/chad/turbulence (Ruby)
• https://github.com/bmitch/churn-php (PHP)

Copyright and License

Copyright (c) 2021 Patryk Woziński

This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See the LICENSE.md file for more details.