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:

"--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:

"--date-format"

"--date"

Format to use for timestamps. Defaults to "iso". Allowed values:

"--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:

"--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:

Sqitch

Part of the sqitch suite.