id       = "sqitch"
name     = "Sqitch"
homepage = "https://sqitch.org"
description = "Sensible database-native change management for framework-free development and dependable deployment."
# The project's own logo, the apple-touch-icon on sqitch.org.
icon     = "https://sqitch.org/img/apple-touch.png"
executables   = ["sqitch"]

[dotfiles]

# The description is sqitch.org's own summary line.
#
# sqitch-config(3), FILES: "~/.sqitch/sqitch.conf" is "used to store a per-user
# configuration as fallback values for the ./sqitch.conf file", overridable
# with $SQITCH_USER_CONFIG. The system file, $(prefix)/etc/sqitch/sqitch.conf,
# is not user-level; ./sqitch.conf belongs to the project's repository, not to
# the user's home.
paths = ["~/.sqitch/sqitch.conf"]

exclude = []

# The user config is a git-style ini file: user.name / user.email, editor and
# pager preferences, engine defaults. It is not a credential end to end — only
# the connection URI in it can be, and that is lifted out below.
secret = []

# Read once per invocation; sqitch is a client with no resident process.
side_effect = false

# sqitch-target(3) gives the URI format as
# "db:engine:[//[user[:password]@][host][:port]/][dbname][?params][#fragment]",
# so a `uri` line can carry a database password in the clear — which is why
# sqitch-authentication(3) opens with "Don't use Passwords" and offers a
# password file and $SQITCH_PASSWORD instead. The key is written `uri` inside a
# [target "name"] or [engine "pg"] section, which is the shape a prefix match
# sees. Lifting the whole line is deliberate over-classification: a URI without
# a password costs the user one setting, a URI with one costs them the
# password.
[[dotfiles.secret_paths]]
file  = "~/.sqitch/sqitch.conf"
match = { prefix = ["uri"] }

# sqitch-config(3): "engine.$engine.client — Path to the engine command-line
# client. Defaults to the first instance found in the path", and "core.vcs.client"
# the same for the VCS client. Both are absolute paths to a binary on this
# host's disk; the next machine has psql or git somewhere else. It is a path
# decided by the kind of machine — a Homebrew prefix, a distribution layout —
# rather than by the individual box, so it travels to another machine of the
# same class.
[[dotfiles.machine_lines]]
file  = "~/.sqitch/sqitch.conf"
match = { prefix = ["client"] }
scope = "platform"

[commands]
format = 1
label = "Sqitch"
description = "Deploy or revert database changes, or add a new change to the plan. Other subcommands (init, tag, rebase, bundle, status, verify) are not covered."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = false, short_bundles = false }

[[commands.subcommand]]
path = ["deploy"]
label = "Deploy changes"
description = "Deploy changes from the plan to a target database. Positional target and change arguments are left out; use the target and to-change fields."

[[commands.subcommand.source]]
id = "deploy-pod"
kind = "manual"
url = "https://github.com/sqitchers/sqitch/blob/HEAD/lib/sqitch-deploy.pod"
revision = "HEAD 2026-10-27"
evidence = """
=item C<-t>
=item C<--target>
The target database to which to connect. This option can be either a URI or
the name of a target in the configuration.
=item C<--to-change>
=item C<--change>
=item C<--to>
Specify the deployment change. Defaults to the last point in the plan.
=item C<--mode>
Specify the reversion mode to use in case of deploy or verify failure.
=item C<all>
=item C<tag>
=item C<change>
=item C<--verify>
Verify each change by running its verify script, if there is one.
=item C<--no-verify>
Don't verify each change. This is the default.
=item C<-s>
=item C<--set>
Set a variable name and value for use by the database engine client. The format must be name=value
=item C<--log-only>
Log the changes as if they were deployed, but without actually running the deploy scripts.
=item C<--lock-timeout>
Set the number of seconds for Sqitch to wait to get an exclusive advisory lock on the target database. Defaults to 60.
"""

[[commands.subcommand.field]]
id = "target"
label = "Target"
description = "A database URI or the name of a configured target."
type = "string"
option = ["--target", "-t"]
sources = ["deploy-pod"]

[[commands.subcommand.field]]
id = "to_change"
label = "Deploy up to change"
description = "Defaults to the last point in the plan."
type = "string"
option = ["--to-change", "--change", "--to"]
sources = ["deploy-pod"]

[[commands.subcommand.field]]
id = "mode"
label = "Failure reversion mode"
type = "enum"
choices = [{ value = "all", label = "Revert everything deployed (default)" }, { value = "tag", label = "Revert to last applied tag" }, { value = "change", label = "Do not revert deploy failures" }]
option = ["--mode"]
sources = ["deploy-pod"]

[[commands.subcommand.field]]
id = "verify"
label = "Verify each change"
type = "boolean"
option = ["--verify"]
false_option = "--no-verify"
sources = ["deploy-pod"]

[[commands.subcommand.field]]
id = "log_only"
label = "Log only"
description = "Record changes as deployed without running the deploy scripts."
type = "boolean"
option = ["--log-only"]
sources = ["deploy-pod"]

[[commands.subcommand.field]]
id = "set"
label = "Client variables"
description = "One name=value per entry."
type = "string"
option = ["--set", "-s"]
multiple = true
sources = ["deploy-pod"]

[[commands.subcommand.field]]
id = "lock_timeout"
label = "Lock timeout (seconds)"
type = "integer"
option = ["--lock-timeout"]
sources = ["deploy-pod"]

[[commands.subcommand.task]]
id = "deploy_all"
label = "Deploy to a target"
fields = ["target", "verify"]
required = ["target"]

[[commands.subcommand.task]]
id = "deploy_verified"
label = "Deploy and verify each change"
fields = ["target", "to_change", "verify"]
required = ["target"]
set = { verify = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["target", "to_change", "verify", "mode"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["log_only", "set", "lock_timeout"]

[[commands.subcommand]]
path = ["revert"]
label = "Revert changes"
description = "Revert deployed changes from a target database. Positional arguments are left out."

[[commands.subcommand.source]]
id = "revert-pod"
kind = "manual"
url = "https://github.com/sqitchers/sqitch/blob/HEAD/lib/sqitch-revert.pod"
revision = "HEAD 2026-10-27"
evidence = """
=item C<-t>
=item C<--target>
The target database to which to connect. This option can be either a URI or
the name of a target in the configuration.
=item C<--to-change>
=item C<--change>
=item C<--to>
Specify the reversion change. Defaults to reverting all changes.
=item C<-m>
=item C<--modified>
Finds the change to revert onto based on modifications to deploy scripts.
=item C<--log-only>
Log the changes as if they were reverted, but without actually running the revert scripts.
=item C<-y>
Disable the prompt that normally asks whether or not to execute the revert.
"""

[[commands.subcommand.field]]
id = "target"
label = "Target"
type = "string"
option = ["--target", "-t"]
sources = ["revert-pod"]

[[commands.subcommand.field]]
id = "to_change"
label = "Revert to change"
description = "Defaults to reverting all changes."
type = "string"
option = ["--to-change", "--change", "--to"]
sources = ["revert-pod"]

[[commands.subcommand.field]]
id = "modified"
label = "Revert to earliest modified change"
type = "boolean"
option = ["--modified", "-m"]
sources = ["revert-pod"]

[[commands.subcommand.field]]
id = "log_only"
label = "Log only"
type = "boolean"
option = ["--log-only"]
effect = "delete"
sources = ["revert-pod"]

[[commands.subcommand.field]]
id = "yes"
label = "Skip confirmation prompt"
type = "boolean"
option = ["-y"]
effect = "delete"
sources = ["revert-pod"]

[[commands.subcommand.task]]
id = "revert_target"
label = "Revert a target"
fields = ["target", "to_change"]
required = ["target"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["target", "to_change", "modified"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["log_only", "yes"]

[[commands.subcommand]]
path = ["add"]
label = "Add a change"
description = "Add a new change and its deploy, revert and verify scripts to the plan."

[[commands.subcommand.source]]
id = "add-pod"
kind = "manual"
url = "https://github.com/sqitchers/sqitch/blob/HEAD/lib/sqitch-add.pod"
revision = "HEAD 2026-10-27"
evidence = """
  sqitch add widgets [options
  sqitch add slinkies --require sprockets --set schema=industry
=item C<-c>
=item C<--change>
=item C<--change-name>
The name of the change to add.
=item C<-r>
=item C<--requires>
Name of a change that is required by the new change. May be specified multiple times.
=item C<-x>
=item C<--conflicts>
Name of a change that conflicts with the new change. May be specified multiple times.
=item C<-n>
=item C<--note>
A brief note describing the purpose of the change.
=item C<-e>
=item C<--edit>
Open the generated change scripts in an editor.
=item C<--no-edit>
"""

[[commands.subcommand.field]]
id = "change"
label = "Change name"
type = "string"
option = ["--change", "-c", "--change-name"]
sources = ["add-pod"]

[[commands.subcommand.field]]
id = "requires"
label = "Required changes"
type = "string"
option = ["--requires", "-r"]
multiple = true
sources = ["add-pod"]

[[commands.subcommand.field]]
id = "conflicts"
label = "Conflicting changes"
type = "string"
option = ["--conflicts", "-x"]
multiple = true
sources = ["add-pod"]

[[commands.subcommand.field]]
id = "note"
label = "Note"
type = "string"
option = ["--note", "-n"]
sources = ["add-pod"]

[[commands.subcommand.field]]
id = "edit"
label = "Open scripts in editor"
type = "boolean"
option = ["--edit", "-e"]
false_option = "--no-edit"
sources = ["add-pod"]

[[commands.subcommand.task]]
id = "add_change"
label = "Add a change"
fields = ["change", "requires", "note"]
required = ["change"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["change", "requires", "conflicts", "note", "edit"]