Provided by: sqitch_1.4.1-1_all bug

Name

       sqitch-config - Get and set local, user, or system Sqitch options

Synopsis

         sqitch config [<file-option>] [type] name [value [value_regex]]
         sqitch config [<file-option>] [type] --add name value
         sqitch config [<file-option>] [type] --replace-all name value [value_regex]
         sqitch config [<file-option>] [type] --get name [value_regex]
         sqitch config [<file-option>] [type] --get-all name [value_regex]
         sqitch config [<file-option>] [type] --get-regexp name_regex [value_regex]
         sqitch config [<file-option>] --unset name [value_regex]
         sqitch config [<file-option>] --unset-all name [value_regex]
         sqitch config [<file-option>] --rename-section old_name new_name
         sqitch config [<file-option>] --remove-section name
         sqitch config [<file-option>] -l | --list
         sqitch config [<file-option>] -e | --edit

Description

       You can query/set/replace/unset Sqitch options with this command. The name is actually the
       section and the key separated by a dot, and the value will be escaped.

       Multiple lines can be added to an option by using the "--add" option. If you want to
       update or unset an option which can occur on multiple lines, a Perl regular expression
       "value_regex" needs to be given. Only the existing values that match the regex will be
       updated or unset. If you want to handle lines that do not match the regex, just prepend a
       single "!" (exclamation point) in front (see Examples).

       The "type" specifier can be "--int", "--num", or "--bool", to ensure that the variable(s)
       are of the given type and convert the value to the canonical form (simple integer for
       "--int", decimal number for "--num", a "true" or "false" string for "--bool") If no type
       specifier is passed, no checks or transformations are performed on the value.

       The "file-option" can be one of "--local", "--user", "--system", or "--file", which
       specify where the values will be read from or written to. The default is to assume the
       local config file in the current project directory, for editing, and the all files merged
       for fetching (see "Files").

       On success, the command returns the exit code 0.

Options

       "--replace-all"
           The default behavior is to replace at most one line. This replaces all lines matching
           the key (and optionally the "value_regex").

       "--add"
           Adds a new line to the option without altering any existing values. This is the same
           as providing "^$" as the value_regex in "--replace-all".

       "--get"
           Get the value for a given key (optionally filtered by a regex matching the value).
           Returns error code 1 if the key was not found and error code 2 if multiple values were
           found.

       "--get-all"
           Like "--get", but does not fail if the number of values for the key is not exactly
           one.

       "--get-regexp"
           Like "--get-all", but interprets the name as a regular expression and writes out the
           key names and value.

       "--local"
           For writing options: write to the local ./sqitch.conf file. This is the default if no
           file option is specified.

           For reading options: read only from the local ./sqitch.conf file rather than from all
           available files.

           See also "Files".

       "--user"
           For writing options: write to the user ~/.sqitch/sqitch.conf file rather than the
           repository ./sqitch.conf.

           For reading options: read only from the user ~/.sqitch/sqitch.conf file rather than
           from all available files.

           See also "Files".

       "--global"
           An alias for "--user" for the benefit of the muscle memory of Git users.

       "--system"
           For writing options: write to system-wide $(prefix)/etc/sqitch/sqitch.conf file rather
           than the repository ./sqitch.conf.

           For reading options: read only from system-wide $(prefix)/etc/sqitch/sqitch.conf file
           rather than from all available files.

           Call "sqitch --etc-path" to find out exactly where the system configuration file lives
           (e.g., "$(sqitch --etc-path)/sqitch.conf").

           See also "Files".

       "-f config-file, --file config-file"
           Use the given config file instead of the one specified by $SQITCH_CONFIG.

       "--remove-section"
           Remove the given section from the configuration file.

       "--rename-section"
           Rename the given section to a new name.

       "--unset"
           Remove the line matching the key from config file.

       "--unset-all"
           Remove all lines matching the key from config file.

       "-l, --list"
           List all variables set in config file.

       "--bool"
           "sqitch config" will ensure that the output is "true" or "false".

       "--int"
           "sqitch config" will ensure that the output is a simple integer.

       "--num"
           "sqitch config" will ensure that the output is a simple decimal number.

       "--bool-or-int"
           "sqitch config" will ensure that the output matches the format of either "--bool" or
           "--int", as described above.

       "-e, --edit"
           Opens an editor to modify the specified config file; either "--local", "--user",
           "--system", or "--file". If none of those options is specified, the local file will be
           opened.

Files

       If not set explicitly with "--file", there are three files in which "sqitch config" will
       search for configuration options:

       ./sqitch.conf
           Local, project-specific configuration file.

       ~/.sqitch/sqitch.conf
           User-specific configuration file.

       $(prefix)/etc/sqitch/sqitch.conf
           System-wide configuration file.

Environment

       "SQITCH_CONFIG"
           Take the local configuration from the given file instead of ./sqitch.conf.

       "SQITCH_USER_CONFIG"
           Take the user configuration from the given file instead of ~/.sqitch/sqitch.conf.

       "SQITCH_SYSTEM_CONFIG"
           Take the system configuration from the given file instead of
           $($etc_prefix)/sqitch.conf.

Examples

       Given a ./sqitch.conf like this:

         #
         # This is the config file, and
         # a '#' or ';' character indicates
         # a comment
         #

         ; core variables
         [core]
                 ; Use PostgreSQL
                 engine    = pg

         ; Bundle command settings.
         [bundle]
                 from      = gamma
                 tags_only = false
                 dest_dir  = _build/sql

         ; Fuzzle command settings
         [core "fuzzle"]
                 clack        = foo
                 clack        = bar
                 clack        = barzlewidth

       You can set the "tags_only" setting to true with

         % sqitch config bundle.tags_only true

       The hypothetical "clack" key in the "core.fuzzle" section might need to set "foo" to "hi"
       instead of "foo". You can make the replacement by passing an additional argument to match
       the old value, which will be evaluated as a regular expression. Here's one way to make
       that change:

         % sqitch config core.fuzzle.clack hi '^foo$'

       To delete the entry for "bundle.from", do

         % sqitch config --unset bundle.from

       If you want to delete an entry for a multivalue setting (like "core.fuzzle.clack"),
       provide a regex matching the value of exactly one line.  This example deletes the "bar"
       value:

         % sqitch config --unset core.fuzzle.clack '^bar$'

       To query the value for a given key, do:

         % sqitch config --get core.engine

       Or:

         % sqitch config core.engine

       Or, to query a multivalue setting for only those values that match "/ba/":

         % sqitch config --get core.fuzzle.clack ba

       If you want to know all the values for a multivalue setting, do:

         % sqitch config --get-all core.fuzzle.clack

       If you like to live dangerously, you can replace all "core.fuzzle.clack" with a new one
       with

         % sqitch config --replace-all core.fuzzle.clack funk

       However, if you only want to replace lines that don't match "bar", prepend the matching
       regular expression with an exclamation point ("!"), like so:

         % sqitch config --replace-all core.fuzzle.clack yow '!bar'

       To match only values with an exclamation mark, you have to escape it:

         % sqitch config section.key '[!]'

       To add a new setting without altering any of the existing ones, use:

         % sqitch config --add core.fuzzle.set widget=fred

Configuration File

       The sqitch configuration file contains a number of variables that affect the sqitch
       command's behavior. The ./sqitch.conf file local to each project is used to store the
       configuration for that project, and $HOME/.sqitch/sqitch.conf is used to store a per-user
       configuration as fallback values for the ./sqitch.conf file. The file
       $($etc_prefix)/sqitch.conf can be used to store a system-wide default configuration.

       The variables are divided into sections, wherein the fully qualified variable name of the
       variable itself is the last dot-separated segment and the section name is everything
       before the last dot. The variable names are case-insensitive, allow only alphanumeric
       characters and -, and must start with an alphabetic character. Some variables may appear
       multiple times.

   Syntax
       The syntax is fairly flexible and permissive; white space is mostly ignored.  The "#" and
       ";" characters begin comments to the end of line, blank lines are ignored.

       The file consists of sections and variables. A section begins with the name of the section
       in square brackets and continues until the next section begins.  Section names are not
       case sensitive. Only alphanumeric characters, "-" and "." are allowed in section names.
       Each variable must belong to some section, which means that there must be a section header
       before the first setting of a variable.

       Sections can be further divided into subsections. To begin a subsection put its name in
       double quotes, separated by space from the section name, in the section header, like in
       the example below:

            [section "subsection"]

       Subsection names are case sensitive and can contain any characters except newline (double
       quote and backslash have to be escaped as "\"" and "\\", respectively). Section headers
       cannot span multiple lines. Variables may belong directly to a section or to a given
       subsection. You can have "[section]" if you have "[section "subsection"]", but you don't
       need to.

       All the other lines (and the remainder of the line after the section header) are
       recognized as setting variables, in the form "name = value". If there is no equal sign on
       the line, the entire line is taken as name and the variable is recognized as boolean
       "true". The variable names are case-insensitive, allow only alphanumeric characters and
       "-", and must start with an alphabetic character. There can be more than one value for a
       given variable; we say then that the variable is multivalued.

       Leading and trailing whitespace in a variable value is discarded. Internal whitespace
       within a variable value is retained verbatim.

       The values following the equals sign in variable assignments are either strings, integers,
       numbers, or booleans. Boolean values may be given as yes/no, 1/0, true/false or on/off.
       Case is not significant in boolean values, when converting value to the canonical form
       using the "--bool" type specifier; "sqitch config" will ensure that the output is "true"
       or "false".

       String values may be entirely or partially enclosed in double quotes. You need to enclose
       variable values in double quotes if you want to preserve leading or trailing whitespace,
       or if the variable value contains comment characters (i.e. it contains "#" or ";"). Double
       quote and backslash characters in variable values must be escaped: use "\"" for """ and
       "\\" for "\".

       The following escape sequences (beside "\"" and "\\") are recognized: "\n" for newline
       character (NL), "\t" for horizontal tabulation (HT, TAB) and "\b" for backspace (BS). No
       other character escape sequence or octal character sequence is valid.

       Variable values ending in a "\" are continued on the next line in the customary UNIX
       fashion.

       Some variables may require a special value format.

   Example
         # Core variables
         [core]
             engine    = pg
             top_dir   = migrations
             extension = ddl

         [engine "pg"]
             registry  = widgetopolis

         [revert]
             to        = gamma

         [bundle]
             from      = gamma
             tags_only = yes
             dest_dir  = _build/sql

   Variables
       Note that this list is not comprehensive and not necessarily complete. For command-
       specific variables, you will find a more detailed description in the appropriate manual
       page.

       "core.plan_file"
           The plan file to use. Defaults to $top_dir/sqitch.plan.

       "core.engine"
           The database engine to use. Supported engines include:

           •   "pg" - PostgreSQL <https://postgresql.org/>, Postgres-XC
               <https://sourceforge.net/projects/postgres-xc/>, and YugabyteDB
               <https://www.yugabyte.com/yugabytedb/>

           •   "sqlite" - SQLite <https://sqlite.org/>

           •   "oracle" - Oracle <https://www.oracle.com/us/products/database/>

           •   "mysql" - MySQL <https://dev.mysql.com/> and MariaDB <https://mariadb.com/>

           •   "firebird" - Firebird <https://www.firebirdsql.org/>

           •   "vertica" - Vertica <https://my.vertica.com/>

           •   "exasol" - Exasol <https://www.exasol.com/>

           •   "snowflake" - Snowflake <https://www.snowflake.net/>

           •   "cockroach" - CockroachDB <https://www.cockroachlabs.com/product/>

       "core.top_dir"
           Path to directory containing deploy, revert, and verify SQL scripts. It should contain
           subdirectories named "deploy", "revert", and (optionally) "verify". These may be
           overridden by "deploy_dir", "revert_dir", and "verify_dir". Defaults to ".".

       "core.deploy_dir"
           Path to a directory containing SQL deployment scripts. Overrides the value implied by
           "core.top_dir".

       "core.revert_dir"
           Path to a directory containing SQL reversion scripts. Overrides the value implied by
           "core.top_dir".

       "core.verify_dir"
           Path to a directory containing SQL verify scripts. Overrides the value implied by
           "core.top_dir".

       "core.extension"
           The file name extension on deploy, revert, and verify SQL scripts. Defaults to "sql".

       "core.verbosity"
           An integer determining how verbose Sqitch should be. Defaults to 1. Set to 0 to
           silence status messages and to 2 or three to increase verbosity. Error message output
           will not be affected by this property.

       "core.pager"
           The command to use as a pager program. This overrides the "PAGER" environment variable
           on UNIX like systems. Both can be overridden by setting the $SQITCH_PAGER environment
           variable. If none of these variables are set, Sqitch makes a best-effort search among
           the commonly installed pager programs like "less" and "more".

       "core.editor"
           The command to use as a editor program. This overrides the "EDITOR" environment
           variable on UNIX like systems. Both can be overridden by setting the $SQITCH_EDITOR
           environment variable. If none of these variables are set, Sqitch defaults to
           "notepad.exe" on Windows and "vi" elsewhere.

       "user"

       Configuration properties that identify the user.

       "user.name"
           Your full name, to be recorded in changes and tags added to the plan, and to commits
           to the database.

       "user.email"
           Your email address, to be recorded in changes and tags added to the plan, and to
           commits to the database.

       "engine.$engine"

       Each supported engine offers a set of configuration variables, falling under the key
       "engine.$engine" where $engine may be any value accepted for "core.engine".

       "engine.$engine.target"
           A database target, either the name of target managed by the "target" command, or a
           database connection URI. If it's a target name, then the associated "uri", "registry",
           and "client" values will override any values specified for the values below. Targets
           are the preferred way to configure engines on a per-database basis, and the one
           specified here should be considered the default.

       "engine.$engine.uri"
           A database connection URI.

       "engine.$engine.registry"
           The name of the Sqitch registry schema or database. Sqitch will store its own data in
           this schema.

       "engine.$engine.client"
           Path to the engine command-line client. Defaults to the first instance found in the
           path.

       Notes on engine-specific configuration:

       "engine.pg.registry"
           For the PostgreSQL engine, the "registry" value identifies the schema for Sqitch to
           use for its own data. No other data should be stored there. Defaults to "sqitch".

       "engine.sqlite.registry"
           For the SQLite engine, if the "registry" value looks like an absolute path, then it
           will be the database file. Otherwise, it will be in the same directory as the database
           specified by the "uri". Defaults to "sqitch".

       "engine.mysql.registry"
           For the MySQL engine, the "registry" value identifies the database for Sqitch to use
           for its own data. If you need to manage multiple databases on a single server, and
           don't want them all to share the same registry, change this property to a value
           specific for your database. Defaults to "sqitch".

       "engine.oracle.registry"
           For Oracle, "registry" value identifies the schema for Sqitch to use for its own data.
           No other data should be stored there. Uses the current schema by default (usually the
           same name as the connection user).

       "engine.firebird.registry"
           For the Firebird engine, if the "registry" value looks like an absolute path, then it
           will be the database file. Otherwise, it will be in the same directory as the database
           specified by the "uri". Defaults to "sqitch.$extension", where $extension is the same
           as that in the "uri", if any.

       "engine.vertica.registry"
           For the Vertica engine, the "registry" value identifies the schema for Sqitch to use
           for its own data. No other data should be stored there. Defaults to "sqitch".

       "engine.exasol.registry"
           For the Exasol engine, the "registry" value identifies the schema for Sqitch to use
           for its own data. No other data should be stored there. Defaults to "sqitch".

       "engine.snowflake.registry"
           For the Snowflake engine, the "registry" value identifies the schema for Sqitch to use
           for its own data. No other data should be stored there. Defaults to "sqitch".

       "core.vcs"

       Configuration properties for the version control system. Currently, only Git is supported.

       "core.vcs.client"
           Path to the "VCS" command-line client. Defaults to the first instance of git found in
           the path.

       "user"

       "user.email"
           Your email address to be recorded in any newly planned changes.

       "user.name"
           Your full name to be recorded in any newly planned changes.

Sqitch

       Part of the sqitch suite.