cartage 1.0

data/README.rdoc

@@ -0,0 +1,192 @@
+= Cartage by Kinetic Cafe
+
+code :: https://github.com/KineticCafe/cartage/
+issues :: https://github.com/KineticCafe/cartage/issues
+docs :: http://www.rubydoc.info/github/KineticCafe/cartage/master
+continuous integration :: {<img src="https://travis-ci.org/KineticCafe/cartage.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/KineticCafe/cartage]
+
+== Description
+
+Cartage provides a plug-in based tool to reliably create a package for a
+Bundler-based Ruby application that can be used in deployment with a
+configuration tool like Ansible, Chef, Puppet, or Salt. The package is created
+with its dependencies bundled in +vendor/bundle+, so it can be deployed in
+environments with strict access control rules and without requiring development
+tool access.
+
+Cartage has learned its tricks from Heroku, Capistrano, and Hoe. From Hoe, it
+learned to keep a manifest to control what is packaged (as well as its plug-in
+system). From Heroku, it learned to keep a simple ignore file. From Capistrano,
+it learned to mark the Git hashref as a file in its built package, and to
+timestamp the packages.
+
+Cartage follows a relatively simple set of steps when creating a package:
+
+1.  Copy the application files to the work area. The application’s files are
+    specified in +Manifest.txt+ and filtered against the exclusion list
+    (+.cartignore+). If there is no +.cartignore+, try to use +.slugignore+. If
+    there is no +.slugignore+, Cartage will use a sensible default exclusion
+    list. To override the use of this exclusion list, an empty +.cartignore+
+    file must be present.
+
+2.  The Git hashref is written to the work area (as +release_hashref+) and to
+    the package staging area.
+
+3.  Files that have been modified are restored to pristine condition in the
+    work area. The source files are not touched. (This ensures that
+    +config/database.yml+, for example, will not be the version used by a
+    continuous integration system.)
+
+4.  Bundler is fetched into the work area, and the bundle is installed into the
+    work area’s +vendor/bundle+ without the +development+ and +test+
+    environments. If a bundle cache is kept (by default, one is), the resulting
+    +vendor/bundle+ will be put into a bundle cache so that future bundle
+    installs are faster.
+
+5.  A timestamped tarball is created from the contents of the work area. It can
+    then be copied to a more permanent or accessible location.
+
+Cartage is extremely opinionated about its tools and environment:
+
+* The packages are created with +tar+ and +bzip2+ using <tt>tar cfj</tt>.
+* Cartage only understands +git+, which is used for creating
+  <tt>release_hashref</tt>s, +Manifest.txt+ creation and comparison, and even
+  default application name detection (from the name of the origin remote).
+
+== Synopsis
+
+    # Build a package from the current machine, using the Manifest.txt.
+    cartage pack
+
+    # Create or update a Manifest.txt from the current repository.
+    cartage manifest
+    # Check the current Manifest against the files that should be there.
+    cartage check
+
+    # Create a .cartignore file for use.
+    cartage install-ignore
+    # Overwrite the current .cartignore with the default.
+    cartage install-ignore --force
+    # Merge the current .cartignore with the default. Merging automatically
+    # removes any comments.
+    cartage install-ignore --merge
+
+== Install
+
+Add cartage to your Gemfile:
+
+    gem 'cartage', '~> 1.0', groups: [ :development, :test ]
+
+Or manually install:
+
+  % gem install cartage
+
+== Cartage Plug-Ins
+
+Cartage is extensible by plug-ins. This version of the plug-in system provides
+one integration point, subcommands. Cartage is implemented with
+{cmdparse}[http://cmdparse.gettalong.org/], and plug-ins implement a class that
+performs the work (nested under the Cartage namespace) and one or more commands
+that execute on the work. Plug-in files are discovered immediately relative to
+the +cartage+ directory, and are registered on inheritance from
+Cartage::Plugin. This plug-in would be found in <tt>'cartage/info.rb'</tt>.
+Each plug-in will get a lazy-instantiation constructor added to Cartage itself
+that provides a reference to the owning Cartage instance.
+
+Below is an example of a Cartage plug-in to provide a <tt>cartage info</tt>
+command. This command isn’t very useful, since most values used in Cartage
+packaging are lazily resolved, but it demonstrates how simple a plug-in can be.
+
+    require 'cartage/plugin'
+    require 'cartage/command'
+
+    # An instance of this will be created lazily by calling Cartage#info.
+    class Cartage::Info < Cartage::Plugin
+      # It does not matter what this method is. It’s just a public instance
+      # method used by the command.
+      def run
+        @cartage.instance_variables.sort.each { |ivar|
+          puts "#{ivar}: #{@cartage.instance_variable_get(ivar)}"
+        }
+      end
+
+      # This will create a CmdParse command that responds to 'info' and takes
+      # no subcommands. If the plug-in provides a number of features, it is
+      # recommended that subcommands be used.
+      class InfoCommand < Cartage::Command
+        # The Cartage::Command objects are initialized with the cartage
+        # instance. Set the command name with the string here.
+        def initialize(cartage)
+          super(cartage, 'info', takes_commands: false)
+          short_desc('Shows configuration information about Cartage.')
+        end
+
+        # This is run by Cartage::Command#execute to make the command happen.
+        # An exception should be thrown on failure, as return values do not
+        # affect the status code of the application.
+        def perform
+          @cartage.info.run
+        end
+      end
+
+      # This returns the command(s) created by this plug-in.
+      def self.commands
+        [ Cartage::Info::InfoCommand ]
+      end
+    end
+
+For a more comprehensive example, see the implementation of Manifest
+(<tt>lib/cartage/manifest.rb</tt>) and its commands
+(<tt>lib/cartage/manifest/commands.rb</tt>).
+
+Future releases of Cartage will offer additional ways to extend Cartage.
+
+== Alternate Projects
+
+The closest project to Cartage is {pkgr}[https://github.com/crohr/pkgr]. Pkgr
+will create a distribution package for Ubuntu (14.04 and 12.02, Debian 7),
+CentOS 6, SLES 12, and Fedora 20.
+
+Both Cartage and Pkgr provide isolated builds with all in-application
+dependencies included.
+
+Pkgr offers several advantages over Cartage:
+
+* It supports more languages than just Ruby (suport for Go and Node.js are
+  confirmed and more are in progress). Cartage will probably have more language
+  support in the future, but it is not an immediate priority. For Ruby and
+  Node.js, the interpreters are included locally to the application.
+
+* It creates a distribution package, meaning that you can just use +apt-get+ to
+  install or upgrade your package.
+
+* It reuses Heroku buildpacks (this requires that your application behave a bit
+  more like a Heroku application, which may be a bit more 
+
+Cartage offers advantages over Pkgr:
+
+* Cartage offers a plug-in based extension system. While the plug-in system is
+  currently limited to adding new +cartage+ commands, this is not its only
+  possible use. Existing plug-ins are +cartage-s3+ (upload the resulting
+  package to S3), +cartage-remote+ (build on a remote machine), and
+  +cartage-rack+ (provide a Rack application to read the +release_hashref+ over
+  an API call).
+
+* Cartage makes it easier to integrate into a workflow translated from
+  Capistrano, as it essentially replaces the source control checkout stage.
+  This process makes it really easy to integrate into an Ansible playbook (as
+  we have done at Kinetic Cafe).
+
+== Cartage Semantic Versioning
+
+Cartage uses a {Semantic Versioning}[http://semver.org/] scheme with one
+significant change:
+
+* When PATCH is zero (+0+), it will be omitted from version references.
+
+Additionally, the major version will generally be reserved for plug-in
+infrastructure changes.
+
+:include: Contributing.rdoc
+
+:include: Licence.rdoc

data/Rakefile

@@ -0,0 +1,62 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require 'pathname'
+
+Hoe.plugin :doofus
+Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
+Hoe.plugin :gemspec2
+Hoe.plugin :git
+Hoe.plugin :minitest
+Hoe.plugin :rubygems
+Hoe.plugin :travis
+
+spec = Hoe.spec 'cartage' do
+  developer('Austin Ziegler', 'aziegler@kineticcafe.com')
+
+  self.history_file = 'History.rdoc'
+  self.readme_file = 'README.rdoc'
+  self.extra_rdoc_files = FileList['*.rdoc'].to_a
+
+  license 'MIT'
+
+  self.extra_deps << ['cmdparse', '~> 3.0']
+
+  self.extra_dev_deps << ['rake', '~> 10.0']
+  self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
+  self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
+  self.extra_dev_deps << ['hoe-git', '~> 1.5']
+  self.extra_dev_deps << ['hoe-geminabox', '~> 0.3']
+  self.extra_dev_deps << ['hoe-travis', '~> 1.2']
+  self.extra_dev_deps << ['minitest', '~> 5.4']
+  self.extra_dev_deps << ['minitest-autotest', '~> 1.0']
+  self.extra_dev_deps << ['minitest-bisect', '~> 1.2']
+  self.extra_dev_deps << ['minitest-focus', '~> 1.1']
+  self.extra_dev_deps << ['minitest-moar', '~> 0.0']
+  self.extra_dev_deps << ['minitest-pretty_diff', '~> 0.1']
+  self.extra_dev_deps << ['simplecov', '~> 0.7']
+end
+
+module Hoe::Publish
+  alias_method :original_make_rdoc_cmd, :make_rdoc_cmd
+
+  def make_rdoc_cmd(*extra_args) # :nodoc:
+    spec.extra_rdoc_files.reject! { |f| f == 'Manifest.txt' }
+    original_make_rdoc_cmd(*extra_args)
+  end
+end
+
+namespace :test do
+  task :coverage do
+    prelude = <<-EOS
+require "simplecov"
+SimpleCov.start("test_frameworks") { command_name "Minitest" }
+gem "minitest"
+    EOS
+    spec.test_prelude = prelude.split($/).join('; ')
+    Rake::Task['test'].execute
+  end
+end
+
+# vim: syntax=ruby

data/bin/cartage

@@ -0,0 +1,8 @@
+#! /usr/bin/env ruby
+
+git_path = File.expand_path('../../.git', __FILE__)
+$:.unshift(File.expand_path('../../lib', __FILE__)) if File.exist?(git_path)
+
+require 'cartage/command'
+
+exit Cartage.run(ARGV)

data/cartage.yml.sample

@@ -0,0 +1,172 @@
+---
+# The name of the application. Optional, defaults to the basename of the origin
+# Git URL. Overridden with <tt>cartage --name NAME</tt>.
+# ---
+# name: my-application
+
+# The target path for the Cartage package. Optional and defaults to
+# <tt>./tmp</tt>. Overridden with <tt>cartage --target PATH</tt>.
+# ---
+# target: tmp/cartage
+
+# The root path of the application. Optional, defaults to the top of the Git
+# repository (<tt>git rev-parse --show-cdup</tt>). Overridden with <tt>cartage
+# --root-path ROOT_PATH</tt>.
+# ---
+# root_path: .
+
+# The timestamp for the final package (which is
+# <tt><em>name</em>-<em>timestamp</em></tt>). Optional, defaults to the current
+# time in UTC. Overridden with <tt>cartage --timestamp TIMESTAMP</tt>. This
+# value is *not* validated to be a time value when supplied.
+# ---
+# timestamp: not-a-timestamp
+
+# The bundle cache path, where the package’s <tt>vendor-bundle.tar.bz2</tt>
+# will be stored between builds. Optional, defaults to <tt>./tmp</tt>.
+# Overridden with <tt>cartage --bundle-cache BUNDLE_CACHE</tt>.
+# ---
+# bundle_cache: tmp/cache
+
+# The groups to exclude from <tt>bundle install</tt>. Optional, defaults to
+# <tt>[ "development", "test"]</tt>. Overridden with <tt>cartage --without
+# group1,group2</tt>.
+# ---
+# without:
+#   - development
+#   - test
+#   - other
+
+# This section is for all plug-in configuration.
+plugins:
+  # This section is for cartage-s3.
+  s3:
+    # The path to the cartage S3 bucket or directory (for another service that
+    # Fog::Storage supports). This has no default and is overridden with
+    # <tt>cartage s3 --path PATH</tt>.
+    # ---
+    # path: cartage-bucket
+
+    # The credentials dictionary passed to Fog::Storage for uploads. Each
+    # provider has different keys. If present, this will dictionary be used in
+    # preference to <tt>cartage s3</tt> flags <tt>--key-id</tt>,
+    # <tt>--secret-key</tt>, and <tt>--region</tt> as those work *only* with
+    # Amazon AWS S3.
+    credentials:
+      # The name of the provider.
+      # ---
+      # provider: AWS
+      # provider: Rackspace
+      # provider: Google
+
+      # The name of the access user. The name of this key varies per provider.
+      # ---
+      # aws_access_key_id: YOUR_AWS_ACCESS_KEY_ID
+      # rackspace_username: RACKSPACE_USERNAME
+      # google_storage_access_key_id: YOUR_SECRET_ACCESS_KEY_ID
+
+      # The authentication key. The name of this key varies per provider.
+      # ---
+      # aws_secret_access_key: YOUR_AWS_SECRET_ACCESS_KEY
+      # rackspace_api_key: RACKSPACE_API_KEY
+      # google_storage_secret_access_key: YOUR_SECRET_ACCESS_KEY
+
+      # Other keys can be provided as needed for the provider. AWS generally
+      # wants to know the +region+, and Rackspace needs to know if you are
+      # using its European datacentre.
+      # ---
+      # region: us-west-2
+      # rackspace_auth_url: lon.auth.api.rackspacecloud.com
+
+  # This section is for cartage-remote. cartage-remote will not work without a
+  # configuration section at this point because remote build scripts tend to be
+  # heavily customized. This may change in the future.
+  remote:
+    # The name of the build server. This field is required and can show up in
+    # two different formats.
+    # ---
+    # server: build@my-build-machine:2222
+    # server:
+    #   user: build
+    #   host: my-build-machine
+    #   port: 2222
+
+    # The SSH key(s) used to connect to the server. Optional, and
+    # cartage-remote will use <tt>~/.ssh/*id_[rd]sa</tt> to find keys if this
+    # is not provided. Three formats are available.
+    #
+    # As a dictionary (first form), the private keys are embedded directly in
+    # the configuration file. As a string or an array, provides glob patterns
+    # to find key files on disk.
+    # ---
+    # keys:
+    #   custom: |
+    #     -----BEGIN RSA PRIVATE KEY-----
+    #     ...
+    #     -----END RSA PRIVATE KEY-----
+    # keys:
+    #   - "config/secrets/*id_[rd]sa"
+    #   - "~/.ssh/*id_[rd]sa"
+    # keys: "config/secrets/*id_[rd]sa"
+
+    # The build script that will be run on the remote server. This is optional
+    # with a reasonable default.
+    #
+    #   #!/bin/bash
+    #   set -e
+    #   if [ -f Gemfile ]; then
+    #     bundle install --path %<remote_bundle>s
+    #     bundle exec cartage build \
+    #       --config-file %<config_file>s \
+    #       --target %<project_path>s
+    #   else
+    #     cartage build --config-file %<config_file>s \
+    #       --target %<project_path>s
+    #   fi
+    # ---
+    # build: |
+    #   #!/bin/bash
+    #   set -e
+    #   if [ -f Gemfile ]; then
+    #     bundle install --path %<remote_bundle>s
+    #     bundle exec cartage s3 \
+    #       --config-file %<config_file>s \
+    #       --target %<project_path>s \
+    #       --verbose
+    #   else
+    #     cartage build \
+    #       --config-file %<config_file>s \
+    #       --target %<project_path>s \
+    #       --verbose
+    #   fi
+
+    # The prebuild script that will be run on the local system. This is
+    # optional with a reasonable default.
+    #
+    #   #!/bin/bash
+    #   ssh-keyscan -H %<remote_host>s >> ~/.ssh/known_hosts
+    # ---
+    # prebuild: |
+    #   #!/bin/bash
+    #   ssh-keyscan -H %<remote_host>s >> ~/.ssh/known_hosts
+    #   echo 'Prebuild complete'
+
+    # The postbuild script that will be run on the local system. This is
+    # optional with no default (no post-build actions).
+    # ---
+    # postbuild: |
+    #   #!/bin/bash
+    #   t="token=SLACK_TOKEN"
+    #   c="channel=%23ci"
+    #   d=MYDOMAIN
+    #   u="https://${d}.slack.com/services/hooks/slackbot?${t}&${c}"
+    #   curl --data "Build %<name>s-%<timestamp>s complete." ${u}
+
+# This must not be indented for it to work.
+<% if File.exist?('config/ansible/cartage.yml') %>
+<%= File.read('config/ansible/cartage.yml') %>
+<% end %>
+<% if File.exist?('config/local/cartage.yml') %>
+<%= File.read('config/local/cartage.yml') %>
+<% end %>
+

data/lib/cartage.rb

@@ -0,0 +1,496 @@
+require 'pathname'
+
+# Cartage, a package builder.
+class Cartage
+  VERSION = '1.0' #:nodoc:
+
+  # Plug-in commands that want to return a non-zero exit code should raise
+  # Cartage::QuietError.new(exitstatus).
+  class QuietError < StandardError
+    # Initialize the exception with +exitstatus+.
+    def initialize(exitstatus)
+      @exitstatus = exitstatus
+    end
+
+    # The exit status to be returned from this exception.
+    attr_reader :exitstatus
+  end
+
+  ##
+  # :attr_accessor: name
+  #
+  # The name of the package to create. Defaults to #default_name.
+
+  ##
+  # :method: default_name
+  #
+  # The default name of the package to be created, derived from the
+  # repository's Git URL.
+
+  ##
+  # :attr_accessor: root_path
+  #
+  # The root path for the application.
+
+  ##
+  # :method: default_root_path
+  #
+  # The default root path of the package, the top-level path of the Git
+  # repository.
+
+  ##
+  # :attr_accessor: target
+  #
+  # The target where the final Cartage package will be created.
+
+  ##
+  # :method: default_target
+  #
+  # The default target of the package, './tmp'.
+
+  ##
+  # :attr_accessor: timestamp
+  #
+  # The timestamp to be applied to the final package name.
+
+  ##
+  # :method: default_timestamp
+  #
+  # The default timestamp.
+
+  ##
+  # :attr_accessor: without_groups
+  #
+  # The environments to exclude from a bundle install.
+
+  ##
+  # :method: default_without_environments
+  #
+  # The default environments to exclude from a bundle install. The default is
+  # <tt>[ 'test', 'development' ]</tt>.
+
+  # Commands that normally output data will have that output suppressed.
+  attr_accessor :quiet
+
+  # Commands will be run with extra information.
+  attr_accessor :verbose
+
+  # The environment to be used when resolving configuration options from a
+  # configuration file. Cartage configuration files do not usually have
+  # environment partitions, but if they do, use this to select the environment
+  # partition.
+  attr_accessor :environment
+
+  # The Config object. If +with_environment+ is +true+ (the default) and
+  # #environment has been set, only the subset of the config matching
+  # #environment will be returned. If +with_environment+ is +false+, the full
+  # configuration will be returned.
+  #
+  # If +for_plugin+ is specified, only the subset of the config for the named
+  # plug-in will be returned.
+  #
+  #     # Assume that #environment is 'development'.
+  #     cartage.config
+  #       # => base_config[:development]
+  #     cartage.config(with_environment: false)
+  #       # => base_config
+  #     cartage.config(for_plugin: 's3')
+  #       # => base_config[:development][:plugins][:s3]
+  #     cartage.config(for_plugin: 's3', with_environment: false)
+  #       # => base_config[:plugins][:s3]
+  def config(with_environment: true, for_plugin: nil)
+    env  = environment.to_sym if with_environment && environment
+    plug = for_plugin.to_sym if for_plugin
+
+    cfg = if env
+            base_config[env]
+          else
+            base_config
+          end
+
+    cfg = cfg.plugins[plug] if plug && cfg.plugins
+    cfg
+  end
+
+  # The configuration file to read. This should not be used by clients.
+  attr_writer :load_config #:nodoc:
+
+  # The base config file. This should not be used by clients.
+  attr_accessor :base_config #:nodoc:
+
+  def initialize #:nodoc:
+    @load_config = :default
+  end
+
+  # Create the package.
+  def pack
+    timestamp # Force the timestamp to be set now.
+    prepare_work_area
+    save_release_hashref
+    fetch_bundler
+    install_vendor_bundle
+    restore_modified_files
+    build_final_tarball
+  end
+
+  # Set or return the bundle cache. The bundle cache is a compressed tarball of
+  # <tt>vendor/bundle</tt> in the working path.
+  #
+  # If it exists, it will be extracted into <tt>vendor/bundle</tt> before
+  # <tt>bundle install --deployment</tt> is run, and it will be created after
+  # the bundle has been installed. In this way, bundle installation works
+  # almost the same way as Capistrano’s shared bundle concept as long as the
+  # path to the bundle_cache has been set to a stable location.
+  #
+  # On Semaphore CI, this should be created relative to
+  # <tt>$SEMAPHORE_CACHE</tt>.
+  #
+  #   cartage pack --bundle-cache $SEMAPHORE_CACHE
+  def bundle_cache(location = nil)
+    if location || !defined?(@bundle_cache)
+      @bundle_cache = Pathname(location || tmp_path).
+        join('vendor-bundle.tar.bz2').expand_path
+    end
+    @bundle_cache
+  end
+
+  # Return the release hashref. If the optional +save_to+ parameter is
+  # provided, the release hashref will be written to the specified file.
+  def release_hashref(save_to: nil)
+    @release_hashref ||= %x(git rev-parse HEAD).chomp
+    File.open(save_to, 'w') { |f| f.write @release_hashref } if save_to
+    @release_hashref
+  end
+
+  # The repository URL.
+  def repo_url
+    unless defined? @repo_url
+      origin = %x(git remote show -n origin)
+      match = origin.match(%r{\n\s+Fetch URL: (?<fetch>[^\n]+)})
+      @repo_url = match[:fetch]
+    end
+    @repo_url
+  end
+
+  # The path to the resulting package.
+  def final_tarball
+    @final_tarball ||= Pathname("#{final_name}.tar.bz2")
+  end
+
+  # The path to the resulting release_hashref.
+  def final_release_hashref
+    @final_release_hashref ||=
+      Pathname("#{final_name}-release-hashref.txt")
+  end
+
+  # A utility method for Cartage plug-ins to display a message only if verbose
+  # is on. Unless the command implemented by the plug-in is output only, this
+  # should be used.
+  def display(message)
+    __display(message)
+  end
+
+  private
+  def resolve_config!(*with_plugins)
+    return unless @load_config
+    @base_config = Cartage::Config.load(@load_config)
+
+    cfg = config
+    maybe_assign :target, cfg.target
+    maybe_assign :name, cfg.name
+    maybe_assign :root_path, cfg.root_path
+    maybe_assign :timestamp, cfg.timestamp
+    maybe_assign :without_groups, cfg.without
+
+    bundle_cache(cfg.bundle_cache) unless cfg.bundle_cache.nil? ||
+      cfg.bundle_cache.empty?
+
+    with_plugins.each do |name|
+      next unless respond_to? name
+      plugin = send(name)
+
+      next unless plugin
+      plugin.send(:resolve_config!, config(for_plugin: name))
+    end
+  end
+
+  def maybe_assign(name, value)
+    return if value.nil? || value.empty? ||
+      instance_variable_defined?(:"@#{name}")
+    send(:"#{name}=", value)
+  end
+
+  def __display(message, partial: false, verbose: verbose())
+    return unless verbose && !quiet
+
+    if partial
+      print message
+    else
+      puts message
+    end
+  end
+
+  def run(command)
+    display command.join(' ')
+
+    IO.popen(command + [ err: [ :child, :out ] ]) do |io|
+      __display(io.read(128), partial: true, verbose: true) until io.eof?
+    end
+
+    unless $?.success?
+      raise StandardError, "Error running '#{command.join(' ')}'"
+    end
+  end
+
+  def prepare_work_area
+    display "Preparing cartage work area..."
+
+    work_path.rmtree if work_path.exist?
+    work_path.mkpath
+
+    xf_status = cf_status = nil
+
+    manifest.resolve(root_path) do |file_list|
+      tar_cf_cmd = [
+        'tar', 'cf', '-', '-C', parent, '-h', '-T', file_list
+      ].map(&:to_s)
+
+      tar_xf_cmd = [
+        'tar', 'xf', '-', '-C', work_path, '--strip-components=1'
+      ].map(&:to_s)
+
+      IO.popen(tar_cf_cmd) do |cf|
+        IO.popen(tar_xf_cmd, 'w') do |xf|
+          xf.write cf.read
+        end
+
+        unless $?.success?
+          raise StandardError, "Error running #{tar_xf_cmd.join(' ')}"
+        end
+      end
+
+      unless $?.success?
+        raise StandardError, "Error running #{tar_cf_cmd.join(' ')}"
+      end
+    end
+  end
+
+  def save_release_hashref
+    display 'Saving release hashref...'
+    release_hashref save_to: work_path.join('release_hashref')
+    release_hashref save_to: final_release_hashref
+  end
+
+  def extract_bundle_cache
+    run %W(tar xfj #{bundle_cache} -C #{work_path}) if bundle_cache.exist?
+  end
+
+  def install_vendor_bundle
+    extract_bundle_cache
+
+    Bundler.with_clean_env do
+      Dir.chdir(work_path) do
+        run %w(bundle install --jobs=4 --deployment --clean --without) +
+          without_groups
+      end
+    end
+
+    create_bundle_cache
+  end
+
+  def restore_modified_files
+    %x(git status -s).split($/).map(&:split).map(&:last).each { |file|
+      restore_modified_file file
+    }
+  end
+
+  def fetch_bundler
+    Dir.chdir(work_path) do
+      run %w(gem fetch bundler)
+    end
+  end
+
+  def build_final_tarball
+    run %W(tar cfj #{final_tarball} -C #{tmp_path} #{name})
+  end
+
+  def work_path
+    @work_path ||= tmp_path.join(name)
+  end
+
+  def clean
+    [ work_path ] + final
+  end
+
+  def final
+    [ final_tarball, final_release_hashref ]
+  end
+
+  def parent
+    @parent ||= root_path.parent
+  end
+
+  def restore_modified_file(filename)
+    command = [
+      'git', 'show', "#{release_hashref}:#{filename}"
+    ]
+
+    IO.popen(command) do |show|
+      work_path.join(filename).open('w') { |f| f.write show.read }
+    end
+  end
+
+  def tmp_path
+    @tmp_path ||= root_path.join('tmp')
+  end
+
+  def final_name
+    @final_name ||= tmp_path.join("#{name}-#{timestamp}")
+  end
+
+  class << self
+    private
+
+    def lazy_accessor(sym, default: nil, setter: nil, &block)
+      ivar = :"@#{sym}"
+      wsym = :"#{sym}="
+      dsym = :"default_#{sym}"
+
+      if default.nil? && block.nil?
+        raise ArgumentError, "No default provided."
+      end
+
+      if setter && !setter.respond_to?(:call)
+        raise ArgumentError, "setter must be callable"
+      end
+
+      setter ||= ->(v) { v }
+
+      dblk = if default.respond_to?(:call)
+               default
+             elsif default.nil?
+               block
+             else
+               -> { default }
+             end
+
+      define_method(sym) do
+        instance_variable_get(ivar) || send(dsym)
+      end
+
+      define_method(wsym) do |value|
+        instance_variable_set(ivar, setter.call(value || send(dsym)))
+      end
+
+      define_method(dsym, &dblk)
+    end
+  end
+
+  lazy_accessor :name, default: -> { File.basename(repo_url, '.git') }
+  lazy_accessor :root_path, setter: ->(v) { Pathname(v).expand_path },
+    default: -> { Pathname(%x(git rev-parse --show-cdup).chomp).expand_path }
+  lazy_accessor :target, setter: ->(v) { Pathname(v) },
+    default: -> { Pathname('tmp') }
+  lazy_accessor :timestamp, default: -> {
+    Time.now.utc.strftime("%Y%m%d%H%M%S")
+  }
+  lazy_accessor :without_groups, setter: ->(v) { Array(v) },
+    default: -> { %w(development test) }
+  lazy_accessor :base_config, default: -> { OpenStruct.new }
+end
+
+class << Cartage
+  # Run the Cartage command-line program.
+  def run(args) #:nodoc:
+    require_relative 'cartage/plugin'
+    Cartage::Plugin.load
+    Cartage::Plugin.decorate(Cartage)
+
+    cartage = Cartage.new
+
+    cli = CmdParse::CommandParser.new(handle_exceptions: true)
+    cli.main_options.program_name = 'cartage'
+    cli.main_options.version = Cartage::VERSION.split(/\./)
+    cli.main_options.banner = 'Manage releaseable packages.'
+
+    cli.global_options do |opts|
+      # opts.on('--[no-]quiet', 'Silence normal command output.') { |q|
+      #   cartage.quiet = !!q
+      # }
+      opts.on('--[no-]verbose', 'Show verbose output.') { |v|
+        cartage.verbose = !!v
+      }
+      opts.on(
+        '-E', '--environment [ENVIRONMENT]', <<-desc
+Set the environment to be used when necessary. If an environment name is not
+provided, it will check the values of $RAILS_ENV and RACK_ENV. If neither is
+set, this option is ignored.
+        desc
+      ) { |e| cartage.environment = e || ENV['RAILS_ENV'] || ENV['RACK_ENV'] }
+      opts.on(
+        '-C', '--[no-]config-file load_config', <<-desc
+Configure Cartage from a default configuration file or a specified
+configuration file.
+        desc
+      ) { |c| cartage.load_config = c }
+    end
+
+    cli.add_command(CmdParse::HelpCommand.new)
+    cli.add_command(CmdParse::VersionCommand.new)
+    cli.add_command(Cartage::PackCommand.new(cartage))
+
+    Cartage::Plugin.registered.each do |plugin|
+      if plugin.respond_to?(:commands)
+        Array(plugin.commands).flatten.each do |command|
+          registered_commands << command
+        end
+      end
+    end
+
+    registered_commands.uniq.each { |cmd| cli.add_command(cmd.new(cartage)) }
+    cli.parse
+    0
+  rescue Cartage::QuietError => qe
+    qe.exitstatus
+  rescue StandardError => e
+    $stderr.puts "Error:\n    " + e.message
+    $stderr.puts e.backtrace.join("\n") if cartage.verbose
+    2
+  end
+
+  # Set options common to anything that builds a package (that is, it calls
+  # Cartage#pack).
+  def common_build_options(opts, cartage)
+    opts.on(
+      '-t', '--target PATH',
+      'The build package will be placed in PATH, which defaults to \'tmp\'.'
+    ) { |t| cartage.target = t }
+    opts.on(
+      '-n', '--name NAME',
+      "Set the package name. Defaults to '#{cartage.default_name}'."
+    ) { |n| cartage.name = n }
+    opts.on(
+      '-r', '--root-path PATH',
+      'Set the root path. Defaults to the repository root.'
+    ) { |r| cartage.root_path = r }
+    opts.on(
+      '--timestamp TIMESTAMP',
+      'The timestamp used for the final package.'
+    ) { |t| cartage.timestamp = t }
+    opts.on(
+      '--bundle-cache PATH',
+      'Set the bundle cache path.'
+    ) { |b| cartage.bundle_cache(b) }
+    opts.on(
+      '--without GROUP1,GROUP2', Array,
+      'Set the groups to be excluded from bundle installation.',
+    ) { |w| cartage.without_environments = w }
+  end
+
+  private
+  def registered_commands
+    @registered_commands ||= []
+  end
+end
+
+require_relative 'cartage/config'