Skip to content
A linting tool that helps you to write better Chef Infra cookbooks by detecting and automatically correcting style, syntax, and logic mistakes in your code.
Ruby Shell
Branch: master
Clone or download
Chef Expeditor
Chef Expeditor Update to reflect the promotion of 5.9.3
Obvious fix; these changes are the result of automation not creative thinking.
Latest commit c79646e Oct 16, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Fix the regression where we no longer show the cookstyle version Aug 14, 2019
config Fix ChefModernize/UnnecessaryDependsChef14 to detect version constraints Oct 14, 2019
lib Bump version to 5.9.3 by Chef Expeditor Oct 14, 2019
tasks Dont fail if yard isn't installed Sep 6, 2019
.rspec adding chefstyle base Apr 19, 2016
.rubocop.yml Further document 5.5 Sep 6, 2019 Add a code of conduct file Dec 7, 2018 Require Ruby 2.2+ and update boilerplate Dec 22, 2018 Developer guide fixes from review Jul 26, 2019
Gemfile Remove the instance eval from the Gemfile Sep 19, 2019
LICENSE Slim the gem size and ship 3.0.1 Nov 21, 2018 Update Sep 26, 2019 Update Oct 16, 2019
Rakefile Avoid cookstyle warning in the Rake file Sep 6, 2019
cookstyle.gemspec Add a better description to the gem Oct 12, 2019

Chef Cookstyle - Chef Infra Cookbook linting with autocorrection

Build status Gem Version

Cookstyle is a code linting tool that helps you to write better Chef Infra cookbooks by detecting and automatically correcting style, syntax, and logic mistakes in your code.

Cookstyle is powered by the RuboCop linting engine. RuboCop ships with over three-hundred rules, or cops, designed to detect common Ruby coding mistakes and enforce a common coding style. We've customized Cookstyle with a subset of those cops that we believe are perfectly tailored for cookbook development. We also ship Chef specific cops that catch common cookbook coding mistakes, cleanup portions of code that are no longer necessary, and detect deprecations that prevent cookbooks from running on the latest releases of Chef Infra Client.

For a complete list of Cookstyle rules see the Cops Documentation

Cookstyle vs. RuboCop

How does Cookstyle differ from RuboCop?

Tailored for Cookbooks

Cookbook development differs from that of traditional Ruby software development, so we have tailored the list of built-in cops in RuboCop for cookbook development. For the most part, this means disabling cops deemed not useful for cookbook development. Occasionally, we've changed the configuration of a rule to enforce a different behavior altogether. We've also extended the base RuboCop package with a set of our own Chef Infra-specific cops. These cops are only found in Cookstyle and will help you to write more reliable and future-proof cookbooks.

See the current set of cops in config/cookstyle.yml.


RuboCop is an incredibly active project with new cops being introduced monthly. The new cops cause existing codebases to fail CI tests and force authors to constantly update their code. With Cookstyle, we update the RuboCop engine for bug and performance fixes, but we only change the set of cops that will fail tests once a year during Chef Infra's April major release. All new cops are introduced at RuboCop's "refactor" alert level, meaning they will alert to the screen as you run Cookstyle, but they won't fail a build. This stability means you are free to upgrade releases of Cookstyle without being forced to update your infrastructure code.


Cookstyle is included in the ChefDK and Chef Workstation. If you choose not to use these packages, you can still install Cookstyle manually using the instructions below.

Add this line to your application's Gemfile:

gem 'cookstyle'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cookstyle


cookstyle Command

Use this tool just as you would RuboCop, but invoke the cookstyle binary instead, which patches RuboCop to load cops from the cookstyle gem. For example:

cookstyle -D --format offenses


In a Rakefile, the setup is similar, except you need to require the cookstyle library first:

require "cookstyle"
require "rubocop/rake_task" do |task|
  task.options << "--display-cop-names"

From RuboCop

Run RuboCop as normal, and simply add a -r cookstyle option when running:

rubocop -r cookstyle -D --format offenses


You can use one of two methods. The simplest is to add the -r cookstyle option to the :cli option in your Guardfile:

guard :rubocop, cli: "-r cookstyle" do
  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }

Alternatively you could pass the path to Cookstyle's configuration by using the Cookstyle.config method:

require "cookstyle"

guard :rubocop, cli: "--config #{Cookstyle.config}" do
  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }


As with RuboCop, any custom settings can still be placed in a .rubocop.yml file in the root of your project.

Getting Involved

We'd love to have your help in developing Cookstyle. See our Contributing Guide for more information on contributing to Chef projects. There's also a Developer Guide for Cookstyle that outlines how the configs work and how you can upgrade the RuboCop engine.

License and Copyright

Copyright 2016-2019, Chef Software, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
You can’t perform that action at this time.