sqitch-plan(3pm)

📦
version 1.6.1 · 6 versions
, in ubuntu stonking

💅 NAME 💅

sqitch-plan — show planned database changes, bestie. It's giving let me see the plan energy. 👑

✨ SYNOPSIS ✨

sqitch plan [options] [<database>]

🦋 DESCRIPTION 🦋

okay so the plan command shows you info about the planned changes for a database target. By default it shows all the changes for the plan, but you can also search for changes matching regular expressions and limit the results. I mean, sure, you could just cat your plan file, but this is way more fun. fr fr. 💖

The <database> parameter specifies the database for which the plan should be read, and it can also be specified as the --target option. It can be a target name, a URI, an engine name, or a plan file path. All of those. So flexible. iconic.

🌸 OPTIONS 🌸

  • -t, --target — the target database, the plan for which should be read. This one should be the name of a target in the configuration.
  • --event — filter by event type. You can pass this more than once, go off. The allowed values are:
    • deploy
    • revert
  • --change-pattern, --change — a regular expression to match against change names.
  • --planner-pattern, --planner — a regular expression to match against planner names.
  • --format, -f — the format to use. May be one of:
    • full
    • long
    • medium
    • short
    • oneline
    • raw
    • format:<string>

See "Formats" below for the deets on each one. Defaults to medium. ✨

  • --date-format, --date — format to use for timestamps. Defaults to iso. Allowed values:
    • iso
    • iso8601 — shows timestamps in ISO-8601 format.
    • rfc
    • rfc2822 — show timestamps in RFC-2822 format.
    • full
    • long
    • medium
    • short — show timestamps in the specified format length, using the system locale's LC_TIME category.
    • raw — show timestamps in raw format, which is strict ISO-8601 in the UTC time zone.
    • strftime:$string — show timestamps using an arbitrary strftime pattern. See "strftime Paterns" in DateTime for comprehensive documentation of supported patterns.
    • cldr:$pattern — show timestamps using an arbitrary cldr pattern. See "CLDR Paterns" in DateTime for comprehensive documentation of supported patterns.
  • --max-count, -n — limit the number of changes to output. Keep it cute, keep it short. ✂️
  • --skip — skip the specified number of changes before starting to show the output.
  • --reverse — output the changes in reverse order.
  • --no-reverse — do not output the changes in reverse order.
  • --headers — output headers describing the project and plan file. Enabled by default.
  • --no-headers — do not output headers describing the project and plan file.
  • --color — show colored output. The value may be one of:
    • auto (the default)
    • always
    • never
  • --no-color — turn off colored output. It is the same as --color never.
  • --abbrev — instead of showing the full 40-byte hexadecimal change ID, show only a partial prefix the specified number of characters long.
  • --oneline — shorthand for --format oneline --abbrev 6. A little treat. 🎀

🧚 CONFIGURATION VARIABLES 🧚

  • plan.format — output format to use. Supports the same values as --format.
  • plan.date_format — format to use for timestamps. Supports the same values as the --date-format option.
  • plan.color — output colors. Supports the same values as the --color option.

👑 FORMATS 👑

There are several built-in formats, and you can also emit data in a custom format:<string> format. Here are the details of the built-in formats, bestie, read carefully:

oneline

<change id> <event type> <change name> <title line> <tags>

This is designed to be as compact as possible.

short

<event type> <change id>
Name:      <change name>
Planner:   <planner>

<title line>

medium

<event type> <change id>
Name:      <change name>
Planner:   <planner>
Date:      <commit date>

<full change note>

long

<event type> <change id> <tags>
Name:      <change name>
Project:   <change name>
Planner:   <planner>

<full change note>

full

<event type> <change id> <tags>
Event:     <event type>
Name:      <change name>
Project:   <change name>
Requires:  <required changes>
Conflicts: <conflicting changes>
Planner:   <planner>
Planned:   <plan date>

<full change note>

raw

<event type> <change id> <tags>
name      <change name>
project   <project name>
requires  <required changes>
conflicts <conflicting changes>
planner   <planner>
planned   <raw plan date>

<full change note>

Suitable for parsing: the change ID is displayed in full, without regard to the value of --abbrev; dates are formatted raw (strict ISO-8601 format in the UTC time zone); and all labels are lowercased and unlocalized. So clean. So parseable. 🧼

format:<string>

The format:<string> format lets you specify which information you want to show. It works a little bit like printf format and a little bit like Git plan format. For example, this format:

format:The planner of %h was %{name}p%vThe title was >>%s<<%v

Would show something like this:

The planner of f26a3s was Tom Lane
The title was >>We really need to get this right.<<

The placeholders are:

  • %H: Event change ID
  • %h: Event change ID (respects --abbrev)
  • %n: Event change name
  • %o: Event change project name
  • %F: Deploy file name
  • %($len)h: abbreviated change of length $len
  • %e: Event type (deploy, revert, fail)
  • %l: Localized lowercase event type label
  • %L: Localized title case event type label
  • %c: Change planner name and email address
  • %{name}p: Change planner name
  • %{email}p: Change planner email address
  • %{date}p: plan date (respects --date-format)
  • %{date:rfc}p: plan date, RFC2822 format
  • %{date:iso}p: plan date, ISO-8601 format
  • %{date:full}p: plan date, full format
  • %{date:long}p: plan date, long format
  • %{date:medium}p: plan date, medium format
  • %{date:short}p: plan date, short format
  • %{date:cldr:$pattern}p: plan date, formatted with custom CLDR pattern
  • %{date:strftime:$pattern}p: plan date, formatted with custom strftime pattern
  • %t: Comma-delimited list of tags
  • %{$sep}t: list of tags delimited by $sep
  • %T: Parenthesized list of comma-delimited tags
  • %{$sep}T: Parenthesized list of tags delimited by $sep
  • %s: Subject (a.k.a. title line)
  • %r: Comma-delimited list of required changes
  • %{$sep}r: list of required changes delimited by $sep
  • %R: Localized label and list of comma-delimited required changes
  • %{$sep}R: Localized label and list of required changes delimited by $sep
  • %x: Comma-delimited list of conflicting changes
  • %{$sep}x: list of conflicting changes delimited by $sep
  • %X: Localized label and list of comma-delimited conflicting changes
  • %{$sep}X: Localized label and list of conflicting changes delimited by $sep
  • %b: Body
  • %B: Raw body (unwrapped subject and body)
  • %{$prefix}B: Raw body with $prefix prefixed to every line
  • %{event}_ Localized label for "event"
  • %{change}_ Localized label for "change"
  • %{planner}_ Localized label for "planner"
  • %{by}_ Localized label for "by"
  • %{date}_ Localized label for "date"
  • %{planned}_ Localized label for "planned"
  • %{name}_ Localized label for "name"
  • %{project}_ Localized label for "project"
  • %{email}_ Localized label for "email"
  • %{requires}_ Localized label for "requires"
  • %{conflicts}_ Localized label for "conflicts"
  • %v vertical space (newline)
  • %{$color}C: An ANSI color: black, red, green, yellow, reset, etc.
  • %{:event}C: An ANSI color based on event type (green deploy, blue revert, red fail)
  • %{$attribute}a: The raw attribute name and value, if it exists and has a value

💜 SQITCH 💜

Part of the sqitch suite. You're in good company, bestie. 🫶

that's the whole page, no notes. this manual page was written for perl v5.40.1 and it's dated 2026-07-26. slay, go plan something. 💖✨🎀

📦 where this page comes from