= An Example cartage.yml

The best way to understand how to configure Cartage is to see an annotated
example of a +cartage.yml+ file.

== Secrets and cartage.yml

The items in the main part of the Cartage configuration are *not* generally
secret, but they are also not typically things that would be set in a static
configuration file. The main value that would probably be set under most
circumstances is the +name+ value.

Because Cartage reads its configuration through ERB, the following structure is
recommended for +config/cartage.yml+. Note that Cartage::Config.import is
shorthand for <tt>File.read(filename) if File.exist?(filename)</tt>. Both
+config/ansible/cartage.yml+ and +config/local/cartage.yml+ should be in your
+.gitignore+.

    ---
    name: my-application

    # This must not be indented for it to work.
    <%= Cartage::Config.import 'config/ansible/cartage.yml' %>
    <%= Cartage::Config.import 'config/local/cartage.yml' %>

== Main Cartage Configuration Options

=== +name+

The name of the application. Optional, defaults to the basename of the origin
repo URL. Overridden with <tt>cartage --name NAME</tt>.

    name: my-application

=== +target+

The target path for the Cartage package. Optional, defaults to <tt>./tmp</tt>.
Overridden with <tt>cartage --target PATH</tt>.

    target: tmp/cartage

=== +root_path+

The root path of the application. Optional, defaults to the top of the
repository (<tt>git rev-parse --show-cdup</tt>). Overridden with <tt>cartage
--root-path ROOT_PATH</tt>.

    root_path: .

=== +timestamp+

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

===  +compression+

The type of compression to be used. Optional, defaults to 'bzip2'. Must be one
of 'bzip2', 'gzip', or 'none'. Overridden with <tt>cartage --compression
TYPE</tt>.

This affects the compression and filenames of both the final package and the
dependency cache.

    compression: gzip

===  +quiet+

Silence normal output. Optional, defaults false. Overridden with <tt>cartage
--quiet</tt>.

    quiet: true

===  +verbose+

Show verbose output. Optional, defaults false. Overridden with <tt>cartage
--verbose</tt>.

    verbose: true

===  +disable_dependency_cache+

Disable dependency caching. Optional, defaults false.

    disable_dependency_cache: true

===  +dependency_cache_path+

The path where the dependency cache will be written
(<tt>dependency-cache.tar.*</tt>) for use in successive builds. Optional,
defaults to <tt>./tmp</tt>. Overridden with <tt>cartage --dependency-cache-path
PATH</tt>.

On a CI system, this should be written somewhere that the CI system uses for
build caching.

    dependency_cache_path: <%= ENV['SEMAPHORE_CACHE'] %>

=== +commands+

This dictionary is for command-specific configuration. As of 2.0, none of the
commands provided by default or in existing plug-ins have command-specific
configuration. The keys are freeform and should be based on the *primary* name
of the command (so the <tt>cartage pack</tt> command should use the key
<tt>pack</tt>.)

    commands: {}

=== +plugins+

This dictionary is for plug-in-specific configuration. See each plug-in for
configuration options. The keys to the plug-ins are based on the plug-in name.
cartage-bundler is available as Cartage::Bundler; the transformed plug-in name
will be <tt>bundler</tt>.

    plugins: {}