How to specify local Ruby gems in your Gemfile.

Let’s say you’re building a Ruby app and your team has extracted one or more gems referenced in your Gemfile, such as your custom Trello API client, Tacokit.rb.

# Gemfile
source ""

# lots of gems ...

gem "tacokit"

You add some code to the gem, but now you want to test the changes in your app. How do you do that?

According to the most popular answer (and accepted) answer to the question, “How can I specify a local gem in my Gemfile?”, we should do the following:

gem "tacokit", path: "/path/to/tacokit"

Avoid this recommendation
Using the :path often means pointing to a location that only exists on our local machine. Every time we want to develop against the local tacokit gem, we have to remember to edit the Gemfile to remove the option so we don’t screw up our teammates or break the build. We also can’t forget to point to correct branch. This workflow is no good because we’re human and humans tend to forget to do things.

Buried deep in the Bundler docs is a better solution for working with local git repo: the bundle config local command. Instead of specifying the :path option, we can run the following on command line:

bundle config local.tacokit /path/to/tacokit

Here we instruct Bundler to look in a local resource by modifying our local Bundler configuration. That’s the one that lives in .bundle/config outside of version control.

We can scope the configuration to a specific folder with the --local flag:

bundle config --local local.tacokit /path/to/tacokit

To take advantage of this local override in the app, we have to specify the remote repo and branch in the Gemfile:

gem "tacokit", github: "rossta/tacokit", branch: "master"

Bundler will abort if the local gem branch doesn’t match the one in the Gemfile and checks that the sha in Gemfile.lock exists in the local repository. This way we ensure our Gemfile.lock contains a valid reference to our local gem.
It’s easy to remove the local config after we don’t need it:

bundle config --delete local.YOUR_GEM_NAME
Alexander M about 6 years ago
This website uses short-lived cookies to improve usability.
Accept or learn more