Gem Version Dependency Status Security Status


Buildar provides a set of rake tasks to help automate releasing your gem:

  • Versioning
  • Building / Packaging
  • Publishing

With a set of options to integrate with your current project.

Rake tasks


  • release - build publish tag
  • build - pre_build gem build a pkg/.gem
  • gem_package - pre_build Gem::PackageTask builds a pkg/.gem
  • publish - built gem push
  • buildar - config check


  • pre_build - invoke test and bump:build conditionally
  • built - build conditionally
  • install - built gem install .gem
  • install_new - build install built .gem
  • version - show the current project version

With git integration

  • tag - message git tag current version, push to origin
  • message - capture a message from ENV['message'] or prompt STDIN

With version file integration

  • bump:build - increment the 4th version number ( ->
  • bump:patch - increment the 3rd version number ( ->
  • bump:minor - increment the 2nd version number ( ->
  • bump:major - increment the 1st version number ( ->
  • release:patch - bump:patch release
  • release:minor - bump:minor release
  • release:major - bump:major release

Just show me the tasks


$ gem install buildar     # sudo as necessary


Edit your Rakefile. Add to the top:

require 'buildar' do |b|
  b.gemspec_file = 'example.gemspec'

That is basically the minimal Rakefile needed for Buildar to operate, assuming you have a valid gemspec file named example.gemspec.

$ rake release
gem build example.gemspec
WARNING:  no email specified
Successfully built RubyGem
Name: example
Version: 1.2.3
File: example-1.2.3.gem
mv example-1.2.3.gem pkg/example-
gem push pkg/example-1.2.3.gem
Pushing gem to
Successfully registered gem: example (1.2.3)

Without a gemspec file do |b| = 'example'
  b.gemspec.summary  = 'Example of foo lorem ipsum'   = 'Buildar'
  b.gemspec.license  = 'MIT'
  b.gemspec.description = 'Foo bar baz quux'
  b.gemspec.files = ['Rakefile']
  b.gemspec.version = '1.2.3'

From examples/no_gemspec_file.rb


Here is Buildar's Rakefile:

require 'buildar' do |b|
  b.gemspec_file = 'buildar.gemspec'
  b.version_file = 'VERSION'
  b.use_git      = true

With b.version_file and b.use_git

$ rake release:patch message="added version task; demonstrating Usage"
bumping to
git commit VERSION -m "Buildar version:bump_patch to"
[master 5df1ff8] Buildar version:bump_patch to
1 file changed, 1 insertion(+), 1 deletion(-)
bumping to
git commit VERSION -m "Buildar version:bump_build to"
[master 73d9bdb] Buildar version:bump_build to
1 file changed, 1 insertion(+), 1 deletion(-)
gem build buildar.gemspec
WARNING:  no email specified
Successfully built RubyGem
Name: buildar
File: buildar-
mv buildar- pkg/buildar-
gem push pkg/buildar-
Pushing gem to
Successfully registered gem: buildar (
git tag -a "v2.0.1.1" -m "added version task; demonstrating Usage"
git push origin --tags
* [new tag]         v2.0.1.1 -> v2.0.1.1

Use a VERSION file

  • Buildar can manage your version numbers with b.version_file
  • The version only matters in the context of a release. For internal development, git SHAs vastly outclass version numbers.
  • "The right version number" for the next release is a function of the current release version and the magnitude (or breakiness) of the change
  • Automate everything

The VERSION file at your project root should look something like

Buildar will be able to bump:major bump:minor bump:patch and bump:build. This helps with a repeatable, identifiable builds: build invokes bump:build etc.

Every build bumps the build number. Since the build operates off of your potentially dirty working copy, and not some commit SHA, there is no guarantee that things haven't changed between builds, even if "nothing is supposed to have changed". This guarantees that you can't have 2 builds floating around with the same version number but different contents.

Typically you'll want to let Buildar manage the build number, and you manage the major, minor, and patch numbers with:

  • release:major - bump:major
  • release:minor - bump:minor
  • release:patch - bump:patch

To make your app or lib aware of its version via this file, simply:

# e.g. lib/foo.rb
module Foo
  def self.version
    file = File.expand_path('../../VERSION', __FILE__)

b.version_file defaults to nil, so if you don't set it, you'll have to keep your gemspec's version attribute updated.

Gemspec file tricks

With do |b|
  b.gemspec_file = 'example.gemspec'
  b.version_file = 'VERSION'

You'll need to keep your gemspec file in synch with the version_file. Here's how Buildar does it:

# do |s|
  # ...
  # dynamic setup
  this_dir = File.expand_path('..', __FILE__)
  version_file = File.join(this_dir, 'VERSION')
  manifest_file = File.join(this_dir, 'MANIFEST.txt')

  # dynamic assignments
  s.version  =
  s.files = File.readlines(manifest_file).map { |f| f.chomp }

I also like to maintain a MANIFEST.txt -- the canonical list of files belonging to the project -- outside of the gemspec.