The Naked Gemspec

December 14, 2012 Doc Ritezel

Before we start, the .gemspec itself only appears once. Here it is, as generated by bundle init and hand-tweaked for relevance:

lib = File.expand_path("../lib", __FILE__)
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
require "your_gem/version" do |s|        = "your-gem"
  s.version     = YourGem::VERSION
  s.authors     = ["Your Name"]       = [""]
  s.homepage    = ""
  s.summary     = "Describe this gem like you're talking to me."
  s.description = "Describe this gem like you're talking to your mom."

  s.require_paths = ["lib"]
  s.files         = `git ls-files`.split("n")
  s.test_files    = `git ls-files -- spec/*`.split("n")

  s.add_dependency "hashie", "~> 2.0"
  s.add_development_dependency "rspec", "~> 2.12"

But what does all this mean? Moreover, how do all these crazy bits fit together?


The most important component of any gemspec is the list of files that it includes when building the gem. After all, a .gem file is just a tarball with a metadata header written in Ruby. Here’s how we make that happen:

s.files         = ['file/one', 'file/two']
s.test_files    = ['spec/one', 'spec/two']

Let’s exploit part of git to give us the list of files. Don’t use git on your project? Start using git. Problem solved! Here’s what it gives us:

$ git ls-files

We can make this output into a Ruby array of strings quite simply:

`git ls-files`.split("n")

Now, gems are laid out in a conventional way. That means a lib directory, a spec directory and some predictable files. That means nobody has to guess where your files are, which is fantastic!

Now let’s say you want to exclude your .rvmrc and .gitignore, because those files aren’t really all that important:

`git ls-files`.split("n") - %w(.rvmrc .gitignore)

Note: exclude Gemfile.lock from git, even though it might exist in your directory. This is conventional.


Your gem’s classes are called YourGem, while they live in files named your_gem. As a matter of taste, I believe gems should be named your-gem. There’s an argument to be made that gem names should match their requires (i.e., the gem should be named your_gem).


The first component here is the version number for your gem. In this example, the your_gem/version.rb looks like this:

module YourGem
  VERSION = "0.1.0"

This is a Semantic Versioning string, and it’s the Simplest Thing that Could Possibly Work for a version.


This is the fun part. I’m of the opinion that dependencies should be as loose as possible until they’re not, but that throwing them away by doing >= 0 is the wrong approach.

For example, the above file will pull in RSpec as a dependency, but require any version that matches a pattern like 2.y.z, as long as y is above 12. Note that z is allowed to be anything, which allows patch versions to be included.

Of course, this means that everyone in the community has to play along and not break their gem on a minor version bump. Also, the community now includes you!


So now you’ve got a conventional gem with loosely-required dependencies. How do you know if these change? Well, if you’re on github, you can use Gemnasium to watch for new dependency versions and see if anything’s broken!

Dropping a new version of your gem is as easy as gem release with @svenfuchs‘s gem-release gem.

More Reading

About the Author


D.J. Patil: Data Science is Storytelling
D.J. Patil: Data Science is Storytelling

There’s a significant gap between collecting and analyzing Big Data, and being able to confidently act upon...

Rename all snake cased coffeescript files to CamelCase
Rename all snake cased coffeescript files to CamelCase

While I don't necessarily think CamelCase is the best way to name your coffeescript files, I was unhappy th...

SpringOne 2021

Register Now