# Flog scores Ruby methods by how much they hurt to read

> Flog is a Ruby command line tool that parses source with ruby_parser and reports a pain score per method, so you can see which parts of a codebase are the most tangled. It is a diagnosis tool rather than a fix, and the score is a heuristic, not a defect list.

**seattlerb/flog** — Flog reports the most tortured code in an easy to read pain report. The higher the score, the more pain the code is in.

- Repository: https://github.com/seattlerb/flog
- Website: http://ruby.sadi.st/Flog.html
- Stars: 971 · Forks: 74
- Language: Ruby
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/seattlerb-flog

## Flog ranks methods by a pain score, not by a defect list

The description is unusually blunt for a code analysis tool: Flog reports the most tortured code in an easy to read pain report, and the higher the score, the more pain the code is in. That framing matters, because it tells you what the output is and is not. A high score is not a bug report. It does not name a missing test, a leaked resource, or a race condition. It says that a method is complicated in the sense that a human has to hold a lot of it in their head at once, and it ranks the methods so you know where to look first. The stated feature is easy to read reporting of complexity and pain. The audience is a developer looking at an unfamiliar or aging codebase and asking which file to open first.

## Running flog on a library directory prints a ranked score list

The synopsis in the README shows the tool invoked against a directory, with the -g flag, and the result is a compact list rather than a wall of text:

```
% ./bin/flog -g lib
Total Flog = 1097.2 (17.4 flog / method)

   323.8: Flog total
    85.3: Flog#output_details
    61.9: Flog#process_iter
    53.7: Flog#parse_options
    ...
```

Two things are visible in that output. There is a total across everything scanned, 1097.2, and a derived average per method of 17.4, which is the number most useful when comparing two runs of the same project. And then there is the ranked list, where the worst method in that example is Flog#output_details at 85.3. The output names the class and the method, so the ranking points directly at a line of code you can open. Notice that the tool is scoring itself here, which is a fair hint that the numbers are relative measures of structure rather than a verdict on any particular style.

## Installing flog pulls in a parser, a path helper, and optionally ruby2ruby

The install section of the README is a single line, and the requirements list is the part worth reading first. Flog needs ruby_parser to parse source and path_expander to handle the file arguments, and it lists ruby2ruby as a soft dependency, needed only for the -v flag. The install itself is a gem install:

```bash
sudo gem install flog
```

The path_expander dependency is what gives the tool its argument handling. The README describes the features it brings: a dir_arg that expands a directory automatically, an @file_of_args form that persists arguments in a file, and -path_to_subtract to ignore intersecting subsets of files and directories. That last one is the feature that decides whether this tool is usable in a monorepo, since you can subtract the vendored or generated directories from the scan rather than trying to pass only the paths you care about. The @file_of_args form is what lets a project keep its chosen arguments in version control and run the same analysis on every machine.

## The score depends on how you run the tool, so compare like with like

The reporting is easy to read, but the number is only meaningful in context. Two configuration choices change what you are measuring. The first is the set of files you scan, which path_expander determines, and the second is the options the report is generated with. The method names in the example output, Flog#output_details and Flog#process_iter, indicate that Flog produces a detailed breakdown rather than only a ranking, so you can ask for more than the summary lines. The right way to use the tool is differential. Run it over the same target set before and after a change, and treat a drop in the per method average as the signal that a refactor actually simplified something. A single absolute score tells you little, because the scale depends on the size and shape of the code you scanned. The README does not document a threshold at which a score becomes unacceptable, and that is deliberate: the tool gives you a ranking and leaves the policy decision to you.

## Flog needs a working Ruby parser, so it measures source, not behaviour

The mechanism underneath is straightforward. Flog parses your Ruby source with ruby_parser and computes a score per method from the structure it finds. That design has consequences worth being explicit about. It means Flog is a static, source level tool. It never runs your code, so it cannot tell you that a method is slow, that it returns the wrong value, or that it is called a million times. It also means the tool only sees what the parser sees, and a project using unusual syntax or heavy metaprogramming will have methods whose real complexity is invisible to any static reader. The -v flag, which pulls in the soft dependency ruby2ruby, is the one hint that the tool can show you the parsed form of the code, which is the sensible next step when a score looks surprising.

## The Ruby ecosystem alternative is a metric library with its own output format

The comparison to make is with other ways of measuring Ruby complexity. A metric library that exposes a count of branches and conditionals per method gives you a number as well, and usually a threshold based one that fails a build when a method crosses a limit. The difference is in what the number means and how it arrives. Flog computes a pain score designed to be read as a ranking, and its output is deliberately plain text that fits in a terminal or a diff. A threshold metric library is designed to be wired into a continuous integration job as a gate, and it usually works from raw counts you set a policy on. Neither replaces the other. If you want to know where to look, Flog gives a clearer answer than a build failure does. If you want a build to fail when a method gets too complicated, that is a different tool with a different integration.

## MIT licensed by Ryan Davis, with no tagged releases

The README states the licence as the MIT License, with copyright held by Ryan Davis of seattle.rb, and prints the standard permission and warranty text. The MIT terms allow use, modification, and redistribution including commercial use, provided the copyright notice and permission notice travel with the software. The repository layout is small and conventional for a Ruby gem of this vintage: an .autotest directory, a History.rdoc changelog, a Manifest.txt, a README.rdoc, a Rakefile, a bin directory, a lib directory, and a test directory. The project page is at ruby.sadi.st, with rdoc documentation at docs.seattlerb.org/flog, and there is a separate vim plugin for Flog hosted by another author, which tells you the community treats it as a long standing tool rather than a new one. The repository has no GitHub releases, and the last push was on 2026-07-22, so the History.rdoc file is where you look for what changed rather than a release page.

## Conclusion

Adopt Flog when you have inherited a Ruby codebase and need a ranked list of the methods that will cost you the most to change, or when you want to watch a metric that pushes toward simpler methods as a side effect of a refactor. It does not fit a team looking for a list of concrete defects, since Flog reports a score and not a cause, and it does not fit languages other than Ruby. Before you use the output as a target, run the same command over code you consider well written to learn the scale of the tool on your own style, and remember that the last push to the repository was on 2026-07-22 with no tagged releases on the project page.

## FAQ

### What does Flog measure in Ruby code?

Flog reports the pain of each method as a score, where a higher score means more tangled code, and prints a ranked list of the worst methods.

### How do I install Flog?

The README gives a single gem install command, sudo gem install flog. It requires ruby_parser and path_expander, and ruby2ruby only if you want the -v flag.

### Can Flog skip directories I do not want to scan?

Yes. The README lists path_expander features including dir_arg to expand a directory automatically, @file_of_args to persist arguments in a file, and -path_to_subtract to ignore intersecting subsets of files and directories.

### What licence is Flog released under?

The README states the MIT License, with copyright held by Ryan Davis of seattle.rb. The project repository itself lists no licence identifier.

## Sources

- [Issues](https://github.com/seattlerb/flog/issues)
- [Project website](http://ruby.sadi.st/Flog.html)
- [README](https://github.com/seattlerb/flog/blob/master/README.md)
- [seattlerb/flog on GitHub](https://github.com/seattlerb/flog)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/seattlerb-flog