Sqitch

sqitch-config

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

Files

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

Environment

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.

user

Configuration properties that identify the user.

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.

Notes on engine-specific configuration:

core.vcs

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

user

Sqitch

Part of the sqitch suite.