=head1 Name

sqitch-init - Create a new Sqitch project

=head1 Synopsis

  sqitch [options] init project
  sqitch [options] init --uri uri project

=head1 Description

This command creates an new Sqitch project -- basically a F<sqitch.conf> file,
a F<sqitch.plan> file, and a F<sql> directory with F<deploy>, F<revert>, and
F<verify> subdirectories.

Running sqitch init in an existing repository is safe. It will not overwrite
things that are already there.

=head1 Options

=over

=item C<--uri>

Optional URI to associate with the project. If present, the URI will be
written to the project plan and used for added uniqueness in hashed object
IDs.

=back

=head1 Configuration

The most important thing C<sqitch init> does is create the project plan file,
F<sqitch.conf>. While the C<init> command has no options of its own, it relies
on several of the options to C<sqitch> to determine what to write to this file:

=over

=item C<--plan-file>

Sets the C<core.plan_file> configuration variable.

=item C<--top-dir>

Determines the top-level directory to use when writing the plan and
theC<core.deploy_dir>, C<core.revert_dir>, and C<core.verify_dir> variables --
unless they are overridden by their more-specific options, detailed below.

=item C<--deploy-dir>

Sets the C<core.deploy_dir> configuration variable.

=item C<--revert-dir>

Sets the C<core.revert_dir> configuration variable.

=item C<--verify-dir>

Sets the C<core.verify_dir> configuration variable.

=item C<--extension>

Sets the C<core.extension> configuration variable.

=item C<--engine>

Sets the C<core.engine> configuration variable.

=back

As a general rule, you likely won't need any of them except for C<--engine>,
since your project can have only one engine at a time, and specifying it on
the command-line forever after would be annoying.

These variables will only be written if their corresponding options are
specified. Otherwise, they get written as comments with user or system
configuration settings, or, failing any values from those locations, from
their default values. If no defaults are specified, they will still be
written, commented out, with a bar C<=> and no value. This allows one to know
what sorts of things are available to edit.

Relatedly, the engine-specific L<sqitch> options will also be used to
write variables, as follows:

=over

=item C<--db-client>

Used to set C<core.pg.client>, C<core.sqlite.client>, or C<core.mysql.client>.

=item C<--db-name>

Used to set C<core.pg.db_name>, C<core.sqlite.db_name>, or
C<core.mysql.db_name>.

=item C<--db-user>

Used to set C<core.pg.username>, or C<core.mysql.username>.

=item C<--db-host>

Used to set C<core.pg.host>, or C<core.mysql.host>.

=item C<--db-port>

Used to set C<core.pg.port>, or C<core.mysql.port>.

=back

Again, if these are no specified, the engine-specific options will still be
written out, but as comments with values either from user or system
configuration, or default values.

=head1 Examples

Start a new Sqitch project using the SQLite engine, setting the
default database file to F</var/db/widgets.db>

  sqitch --engine --db-name /var/db/widgets.db sqlite init

Start a new Sqitch project using the PostgreSQL engine, with the default
database name "widgets", the default user name "postgres", and a
version-specific client:

  sqitch --engine pg \
  --db-name   widgets \
  --db-user   postgres \
  --db-client /opt/pgsql-9.1/bin/psql init

=head1 Sqitch

Part of the L<sqitch> suite.