When working with a Ruby on Rails project, you often need to run commands that depend on specific gem versions defined in your Gemfile.lock. The usual way to ensure you’re using the correct gem versions is by prefixing commands with bundle exec. However, forgetting to do this can sometimes lead to issues, especially when different versions of gems are installed globally on your system.

To solve this, Bundler provides a feature called binstubs, which are small shell scripts designed to ensure that the correct gem versions are loaded and the proper executable paths are used.

What Are Binstubs?

Binstubs are lightweight wrappers around executables that are created inside your project’s bin/ directory. They automatically load Bundler before running the intended command, eliminating the need to manually prefix commands with bundle exec.

By default, every new Rails project includes the following binstubs:

  • bin/bundle – A wrapper for Bundler
  • bin/rails – The Rails command-line tool
  • bin/rake – The Rake task runner (often deleted in favor of using rails for Rake tasks)
  • bin/importmap – Used for managing JavaScript imports in modern Rails applications

Generating Additional Binstubs

If you frequently use a gem that provides command-line executables, you can generate binstubs for it using the following command:

bundle binstubs some-gem-name

For example, if you are using RSpec and want to create a binstub for it, you would run:

bundle binstubs rspec-core

This will create a bin/rspec file in your project. Now, instead of running:

bundle exec rspec

you can simply run:

bin/rspec

Improving Your Workflow with bin/

At first glance, using bin/rspec instead of bundle exec rspec might not seem like a significant improvement. However, you can take it a step further by adding your project’s bin/ directory to your shell’s search path. This way, you can run commands directly without any prefixes.

Adding bin/ to Your Path

If you’re using a containerized development environment, you can configure the container to automatically include bin/ in the system’s search path. Another great tool for managing environment-specific paths is direnv.

After installing direnv, you can create a .envrc file in your project directory and add:

PATH_add bin

Then, run:

direnv allow

Now, any time you enter your project directory, direnv will automatically update your path, allowing you to run commands like rails, rake, or rspec without needing to prefix them with bin/ or bundle exec.

Conclusion

Binstubs provide a simple yet effective way to streamline command execution in a Rails project by ensuring the correct gem versions are used. By leveraging bundle binstubs and adding bin/ to your path, you can significantly improve your development workflow and avoid common gem version conflicts. Whether you’re working locally or inside a containerized environment, setting up binstubs properly can save time and reduce potential headaches.