When you build Rails apps, you’ll use piles of gems. Some of them seem totally magical! But how does that magic happen?

In most gems, there’s nothing they’re doing that you couldn’t. It’s just Ruby code. Sometimes it’s complicated Ruby code. But if you explore that code, you’ll begin to understand where that magic comes from.

Finding the source code

To understand how a gem works, you have to find its code.

If there’s a method that you want to know more about, you have an easy way to find the source: method and source_location . I wrote a little bit about these earlier. Here’s an example:

irb(main):001:0> ActiveRecord :: Base . method ( :find ). source_location => [ "/usr/local/lib/ruby/gems/2.1.0/gems/ activerecord-4.2.0.beta4/lib/active_record/core.rb" , 127 ]

But what if you’re interested in more than one method?

If you have a console open inside your Rails app’s directory, you can go right to a gem’s code:

~/Source/gem_example[master] jweiss $ bundle open rack

If it’s in your Gemfile , bundle open rack will open up the entire rack gem in your editor. You can comfortably browse all of the files inside it.

Where do you start?

Now that you know where the gem’s code is, how do you begin to understand it?

If you try to learn how activerecord works by reading lib/active_record.rb , you’re not going to get anywhere. You’re just going to find a lot of autoload s and require s.

It’s easiest to understand a gem after your app uses it a little bit. Once you know more about the kind of work that the gem is doing for you. That way, you’ll already have an idea about which interesting classes and methods you should start with.

After you have the names of some interesting methods, you can use source_location , Find in Project in your editor, or ag on the command line to see where those methods are defined. And that’s when the fun starts.

The gem’s code is on your machine, right? That means you can change it however you want! You could even break it, and nobody else has to know.

When I’m trying to understand how a gem works, I don’t just read the code. I add puts statements into the gem, I throw exceptions to figure out how my app got to certain lines, and I mess with the code to understand why the author wrote it that way.

Once you know how the trick’s done, it’s a lot less magical. And you won’t have to guess how that code will act in strange situations, because you’ll be able to see it for yourself.

Cleaning up after yourself

After you mess with gem code, your app could be in pretty bad shape. It might not even run anymore! And even if it does, it’s going to spam all those puts statements you added into your console.

But RubyGems has a quick way to bring things back to normal:

~ jweiss $ gem pristine activerecord -v 4.2.0 Restoring gems to pristine condition... Restored activerecord-4.2.0

Or, if you don’t remember which gems you messed with, and you’re really patient:

~ jweiss $ gem pristine --all

After that, all your gems will be back to the way they were when you installed them.

What are you going to explore?

When you find, read, and explore the code inside your gems, you’ll understand the code you depend on at a deeper level. And you won’t have to rely on assumptions and guesses anymore.

This post was originally sent exclusively to my list. To get more posts like it in your inbox every Friday, sign up here!