=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 script
files with the C<--extension> extension in the C<--deploy-dir>,
C<--revert-dir>, and C<--verify-dir> directories, and possibly others. 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 changes 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 changes 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.

For you Git folks out there, C<-m> also works.

=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<-t>

=item C<--template>

=item C<--template-name>

Name of the templates to use for the scripts. When Sqitch searches the
template directory for templates, it uses this name to find them in subdirectories
named for the various types of scripts, including:

=over

=item C<deploy/$name.tmpl>

=item C<revert/$name.tmpl>
      
=item C<verify/$name.tmpl>

=back

Any templates found with the same name in additional subdirectories will also
be evaluated.

This option allows one to define templates for specific tasks, such as
creating a table, and then use them for changes that perform those tasks.
Defaults to the name of the database engine (C<pg>, C<sqlite>, C<mysql>,
C<oracle>, C<firebird>, or C<vertica>.

=item C<--use script=template>

Specify the path to a template for a specific type of script. Defaults to the
individual templates and using C<--template-name>, found in
C<--template-directory> and the configuration template directories.

=item C<--with>

=item C<--without>

Specify a type of template to generate or not generate.

=item C<-e>

=item C<--edit>

=item C<--open-editor>

Open the generated change scripts in an editor.

=item C<--no-edit>

=item C<--no-open-editor>

Do not open the change scripts in an editor. Useful when L<C<add.open_editor>>
is true.

=back

=head1 Templates

Sqitch contains a very simple set of templates for generating the deploy,
revert, and verify scripts, and you can create more of your own. By default,
Sqitch 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 basis by copying templates to F<~/.sqitch/templates> and
making modifications. They may also be overridden by using the
C<--template-directory> or C<--template-name> options, as well as the
template-specific options.

=head2 Directory Layout

Sqitch looks for templates in the following directories, and in this order:

=over

=item * C<--template-directory> or C<add.template_directory>

=item * F<~/.sqitch/templates/>

=item * F<($etc_path)/templates/>

=back

Each should consist of subdirectories named for the types of scripts to be
generated. These should include F<deploy>, F<revert>, and F<verify>, but you
can create any number of other directories to create additional scripts that
will end up in a directory of the same name.

Each directory should include one or more files ending in F<.tmpl>. The
main part of the file name can be anything, but by default Sqitch will
look for a file named for the database engine. Use the C<--template> option
to have Sqitch use a different file.

For example, say you have this directory structure:

  templates/deploy/pg.tmpl
  templates/deploy/create_table.tmpl
  templates/revert/pg.tmpl
  templates/revert/create_table.tmpl
  templates/test/pg.tmpl
  templates/verify/pg.tmpl
  templates/verify/create_table.tmpl

Assuming that you're using the PostgreSQL engine, the code for which is C<pg>,
when you add a new change like so:

  sqitch add schema -n 'Creates schema'

Sqitch will use the C<pg.tmpl> files to create the following files in
C<--top-dir>:

  deploy/schema.sql
  revert/schema.sql
  test/schema.sql
  verify/schema.sql

If you want to use the C<create_table> templates, instead, use the
C<--template> option, like so:

  sqitch add user_table --template create_table -n 'Create user table'

Sqitch will use the C<create_table.tmpl> files to create the following files
in C<--top-dir>:

  deploy/user_table.sql
  revert/user_table.sql
  verify/user_table.sql

Note that the C<test> file was not created, because no
F<test/crate_table.tmpl> file exists.

=head2 Syntax

The syntax of Sqitch templates is the very simple 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

If this is not sufficient for your needs, simply install L<Template::Toolkit>
and all templates will be processed by its more comprehensive features. See
the L<complete Template Toolkit documentation|http://tt2.org/docs/manual/> for
details, especially the L<syntax docs|http://tt2.org/docs/manual/Syntax.html>

=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 transactions=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<--requires> option.

=item C<conflicts>

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

=back

=head1 Configuration Variables

=over

=item C<add.template_directory>

Directory in which to find the templates. Any templates found in this
directory take precedence over user- or system-specific templates, and may in
turn be overridden by the C<--use> option.

=item C<add.template_name>

Name used for template files. Should not include the F<.tmpl> suffix.
Overrides the default, which is the name of the database engine, and may in
turn be overridden by the C<--template> option.

=item C<[add.templates]>

Location of templates of different types. Core templates include:

=over

=item C<add.templates.deploy>

=item C<add.templates.revert>

=item C<add.templates.verify>

=back

But a custom template type can have its location specified here, as well,
such as C<add.template.unit_test>. May be overridden by C<--use>.

=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.

=item C<add.open_editor>

Boolean indicating if the add command should spawn an editor after generating
change scripts.  When true, equivalent to passing C<--edit>.  Defaults off.

=back

=head1 Sqitch

Part of the L<sqitch> suite.