Ruby Style Guide: a document that tells you when to ignore it
A community-driven Ruby coding style guide
At a glance
- What is it?
- The Ruby Style Guide is prose, not a gem: one README.adoc with no library code, no releases and no recorded licence. It settles most Ruby formatting questions, hands three of them back to your team, and tells you not to break backwards compatibility just to comply.
- Who is it for?
- Adopt the Ruby Style Guide as the written rationale behind your RuboCop configuration, not as a rulebook to paste wholesale. Teams writing Rails or RSpec code should read the matching guides as well.
- Can I use it commercially?
- Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- rubocop/ruby-style-guide16,540 ★ · -9
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| rubocop/ruby-style-guide | 16.5k | 16.5k |
-9 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One AsciiDoc file, and no library to install
The entire repository is a document. Its top-level entries are `.circleci/`, `.gitattributes`, `.github/`, `.gitignore`, `README.adoc` and `codespell.txt`. There is no `lib/` directory, no gem manifest, no executable, and the recorded language and licence fields are both blank. The default branch is `master`, and the project publishes no GitHub releases, so there is no version number to pin against and nothing to upgrade.
That shape is the first fact an adopter has to accept. You do not install this project, you read it. The last recorded push was 2026-10-30, so the document still moves, but a style guide has a different upgrade path from a gem. Nothing in your build breaks when a rule changes, and nothing warns you that it changed either. Code written against an older revision drifts out of compliance quietly, and you find out during a review rather than during a release.
Rendering README.adoc is the whole build step
There is no gem to install, but there is a document to render. The guide gives AsciiDoctor commands for generating PDF and HTML copies.
# Generates README.pdf
asciidoctor-pdf -a allow-uri-read README.adoc
# Generates README.html
asciidoctor README.adocThe PDF command carries `-a allow-uri-read` and the HTML command does not. The document does reference remote URLs, including the rubystyle.guide site and two book pages, so that flag has something to resolve.
Syntax highlighting is opt-in through the `rouge` gem, which the guide recommends as a separate step:
gem install rougeThe highlighter itself is selected by AsciiDoc attributes in the header of `README.adoc`:
:source-highlighter: rouge
:toc-title: pass:[<h2>Table of Contents</h2>]Readers who only want the text should start at https://rubystyle.guide, which the guide points to as the version with much improved navigation.
Three formatting arguments the guide refuses to settle
Some areas have no clear consensus in the Ruby community, and the guide names them rather than picking a winner: string literal quoting, spacing inside hash literals, and dot position in multi-line method chaining. Its stated position is that all popular styles are acknowledged and it is up to you to choose one and apply it consistently.
That is a real limitation, and it is deliberate. A document that picked single quotes over double quotes would be wrong for the teams that prefer double quotes, so it declines and hands the decision over. What you give up is a default. Two teams can each be entirely compliant with this guide and still collide on every line they touch together.
The cost lands on tooling rather than on review. Whichever option you choose has to be written into your own RuboCop configuration, because the guide will never resolve it.
The backwards compatibility clause outranks every other rule
The guide ranks itself explicitly. Consistency with this style guide matters less than consistency within a project, and that matters less than consistency within one class or method. It then lists four reasons to ignore a guideline outright: when applying it would make the code less readable, when the surrounding code already breaks it, when the code predates the rule and nothing else is touching it, and when the code must stay compatible with older Ruby versions that lack the recommended feature.
The last reason is the one that changes how you adopt the document. `Do not break backwards compatibility just to comply with this guide!` is stated as an absolute, which means a linter configured straight from these rules can flag code you are not permitted to change. That gap between what the prose recommends and what your runtime allows is exactly where style enforcement stalls, and no amount of reading closes it. You have to record the exception somewhere your tooling can see it.
This is also why the guide cannot be enforced end to end by a machine. It is written to be argued with.
RuboCop is where the prose turns into offenses
The guide positions RuboCop as a static code analyzer, a linter and formatter, based on this style guide. That sentence is the whole difference in approach between the two projects. This repository holds the reasoning, and RuboCop holds the checks.
A linter answers a question the guide cannot answer, namely whether this code violates a rule right now. The guide answers a question a linter cannot answer, namely why the rule exists and when to skip it. It also carries the rationale behind each guideline that the editors added on purpose, which is the part a cop has no way to carry.
Every question the guide left open becomes a setting you must choose.
Ten translations are linked, and none of them is owned
The guide is translated into ten languages: Chinese Simplified, Chinese Traditional, Egyptian Arabic, French, Japanese, Korean, Portuguese (pt-BR), Russian, Spanish (esLA) and Vietnamese. Each lives in a repository outside this one.
The guide attaches a warning to that list. The translations are not maintained by its editor team, their quality and level of completeness may vary, and the translated versions often lag behind the upstream English version.
So a translation is a reading aid, not a source of truth. A team working from one will not learn which rules are current, and the translation cannot tell you whether a difference is a translation artefact or a genuine rule change upstream. Before you encode a translated rule into a linter configuration, check it against `README.adoc` on the `master` branch. Where the two disagree, the English original is the file that receives edits.
No license file, and no release to pin a revision against
Licensing is the sharpest gap here. The repository records no license, and no `LICENSE` file appears among its top-level entries, which are `.circleci/`, `.gitattributes`, `.github/`, `.gitignore`, `README.adoc` and `codespell.txt`. Check the end of `README.adoc` for any licence statement before assuming the text is unlicensed.
For a team that wants to quote the rules, link them from internal documentation, or paste them into an onboarding page, that difference matters. The guide does credit third-party sources it drew on, including Programming Ruby and The Ruby Programming Language, but that is attribution for influence rather than a grant of permission. Settle the question with whoever owns your legal review before you copy the text anywhere.
The second gap is versioning. With no releases, and with `master` as the default branch, the only stable reference to a given set of rules is the date of a commit. Pin by commit SHA whenever you need to prove which revision a code review was measured against.
Editorial conclusion
Adopt the Ruby Style Guide as the written rationale behind your RuboCop configuration, not as a rulebook to paste wholesale. Teams writing Rails or RSpec code should read the matching guides as well. Before you vendor the text into internal documentation, settle the licence question: GitHub records no licence for the repository and no LICENSE file appears among its top-level entries, so check README.adoc itself for licence terms. Pin any copied wording to a commit SHA, because the project publishes no releases.
Frequently asked questions
Is the Ruby Style Guide a Ruby gem that I can install?
No, it is a prose document. The repository's top-level entries are .circleci/, .gitattributes, .github/, .gitignore, README.adoc and codespell.txt, there is no library directory, and the project publishes no GitHub releases. You read it or render it to another format rather than adding it to a build.
How do I build a PDF or HTML copy of the Ruby Style Guide?
The guide gives two commands: asciidoctor-pdf -a allow-uri-read README.adoc produces a PDF, and asciidoctor README.adoc produces HTML. It also recommends installing the rouge gem for syntax highlighting, and the document selects that highlighter through the AsciiDoc attribute :source-highlighter: rouge.
Does RuboCop cover the whole Ruby Style Guide?
The guide describes RuboCop as a static code analyzer and formatter based on this style guide. The guide also leaves string literal quoting, spacing inside hash literals and dot position in multi-line method chaining open, so those choices stay with your own configuration.
Are the translated Ruby Style Guides kept up to date?
The guide states that its translations are not maintained by the editor team, that their quality and level of completeness may vary, and that they often lag behind the upstream English version. Check a translated rule against README.adoc on the master branch before you encode it in a linter configuration.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/rubocop-ruby-style-guide)Star history chart for your README
[](https://hysenlabs.com/projects/rubocop-ruby-style-guide)Was this useful?