Sqitch: sqitch-plan Documentation

Name

sqitch-plan - Show planned database changes

Synopsis

sqitch plan [options] [<database>]

Description

The plan command displays information about planned changes for a database target. By default, it will show all the changes for the plan, but you can also search for changes matching regular expressions, and limit the results. Of course you could just cat your plan file, but this is more fun.

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

Options

-t
--target

The target database, the plan for which should be read. This option should be the name of a target in the configuration.
--event

Filter by event type. May be specified more than once. 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” for details on each format. 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.
--skip

Skip the specified number 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.

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 emit data in a custom format format:<string> format. Here are the details of the built-in formats:

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.
format:<string>

The format:<string> format allows you to specify which information you want to show. It works a little bit like printf format and a little 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.