=head1 Name

sqitch-add - Add a database change to the plan

=head1 Synopsis

  sqitch [options] add [<dependency-options>] [<template-options>] name

=head1 Description

Add a database change to the plan. This will result in the creation of a new
script files with the C<--extension> extension in the C<--deploy-dir>,
C<--revert-dir>, and C<--verify-dir> directories. The content of these files is
determined by the evaluation of templates. By default, system templates in
F<$(etc_path)/templates> are used. These can be overridden by a single user by
creating templates in F<~/.sqitch/templates/> See L</Templates> for details.

Note that the name of the new change must adhere to the rules as defined in
L<sqitchchanges>.

=head1 Options

=over

=item C<-r>

=item C<--requires>

Name of a change that is required by the new change. May be specified multiple
times. See L<sqitchchanges> for the various ways in which change targets can
be specified.

=item C<-c>

=item C<--conflicts>

Name of a change that conflicts with the new change. May be specified multiple
times. See L<sqitchchanges> for the various ways in which change targets can
be specified.

=item C<-n>

=item C<--note>

A brief note describing the purpose of the change. The note will be attached
to the change as a comment. Multiple invocations will be concatenated together
as separate paragraphs.

=item C<-s>

=item C<--set>

Set a variable name and value for use in the templates. The format must be
C<name=value>, e.g., C<--set comment='This one is for you, babe.'>.

=item C<--template-directory>

Location to look for the templates. If none is specified, C<add> will
first look in F<~/.sqitch/templates/> for each template, and fall back on
F<$($etc_prefix)/templates>.

=item C<--deploy-template>

=item C<--revert-template>

=item C<--verify-template>

Path to the template for the given change script. Defaults to the individual
templates found in C<--template-directory>.

=item C<--no-deploy>

=item C<--no-revert>

=item C<--no-verify>

Do not generate the named script.

=item C<--deploy>

=item C<--revert>

=item C<--verify>

Generate the named script. These are not mutually exclusive.

=back

=head1 Templates

Sqitch contains a very simple set of templates for generating the deploy,
revert, and verify scripts. By default, it uses system-wide templates installed
in F<($etc_path)/templates>; call C<sqitch --etc-path> to find out where,
exactly. Individual templates may be overridden on a user bases by copying
templates to F<~/.sqitch/tempates> and making modifications. They may also be
overridden by using the C<--tmplaet-directory> option, as well as the
template-specific options.

=head2 Syntax

The syntax of the templates is the very simple but limited language provided
by L<Template::Tiny>, which is limited to:

=over

=item C<[% %]>

This is the directive syntax. By default, the return value of the expression
is output:

  -- Deploy [% change %]

You can add C<-> to the immediate start or end of a directive tag to control
the whitespace chomping options:

  [% IF foo -%]    # remove trailing newline
  We have foo!
  [%- END %]       # remove leading newline

=item C<[% IF %]>

=item C<[% IF %] / [% ELSE %]>

=item C<[% UNLESS %]>

Conditional blocks:

  [% IF transactions  %]
  BEGIN;
  [% ELSE %]
  -- No transaction, beware!
  [% END %]

=item C<[% FOREACH item IN list %]>

Loop over a list of values:

  [% FOREACH item IN requires -%]
  -- requires: [% item %]
  [% END -%]

=back

=head2 Variables

Sqitch defines three variables for all templates. Any number of additional variables
can be added via the C<--set> option, like so:

  sqitch add --set transations=1 --set schema=foo

Any number of variables may be specified in this manner. You may then use
those variables in custom templates. Variables that appear multiple times will
be passed to the templates as lists of values for which you will likely want
to use C<[% FOREACH %]>. If the templates do not reference your variables,
they will be ignored. Variables may also be specified in a
C<[add "variables]> L<config|sqitch-config> section (see 
L</Configuration Variables>). Variables specified via C<--set> will override
configuration variables.

The three core variables are:

=over

=item C<change>

The name of the change being added.

=item C<requires>

A list of required changes as passed via one or more instances of the
C<--requiers> option.

=item C<conflicts>

A list of conflicting changes as passed via one or more instances of the
C<--requiers> option.

=back

=head1 Configuration Variables

=over

=item C<add.template_directory>

Directory in which to find the templates which should be named F<deploy.tmpl>,
F<revert.tmpl>, and F<verify.tmpl>. This will override looking for user- or
system-specific templates, and may in turn be overridden by the
C<--template-directory>, C<--deploy-template>, C<--revert-template>, and
C<--verify-template> options.

=item C<add.with_deploy>

=item C<add.with_revert>

=item C<add.with_verify>

Boolean variable indicating whether or not to generate the specified script
when adding a change. They are all enabled by default. If you've disabled them
but wish to create them for a given call to C<add>, use the appropriate
option: C<--deploy>, C<--revert>, or C<--verify>.

=item C<add.deploy_template>

=item C<add.revert_template>

=item C<add.verify_template>

Location of individual templates. My be overridden by the appropriate option:
C<--deploy-template>, C<--revert-template>, or C<--verify-template>.

=item C<[add.variables]>

A section defining template variables. Useful if you've customized templates
with your own variables and want project-, user-, or system-specific defaults
for them.

=back

=head1 Files

Unless explicitly told where to find templates via C<--template-directory> or,
as appropriate, C<--deploy-template>, C<--user-template> or
C<--verify-template>, Sqitch looks in two locations for templates: A
system-wide location and a user-specific location:

=over

=item F<$(etc_path)/templates/deploy.tmpl>

=item F<$(etc_path)/templates/revert.tmpl>

=item F<$(etc_path)/templates/verify.tmpl>

The system-wide templates for creating deploy, revert, and verify scripts.

=item F<~/.sqitch/templates/deploy.tmpl>

=item F<~/.sqitch/templates/revert.tmpl>

=item F<~/.sqitch/templates/verify.tmpl>

User-specific templates to override the system-wide templates.

=back

=head1 Sqitch

Part of the L<sqitch> suite.