=head1 Name

sqitch-log - Show Sqitch change deployment logs

=head1 Synopsis

  sqitch log [options] [<database>]

=head1 Description

Sqitch keeps a record of the deployment, failed deployment, or reversion of
all changes in a target database. Even after a change has been reverted, a log
of its earlier deployment is retained. The C<log> command is your key to
accessing it. You can simply list all the events, search for events matching
regular expressions, and limit the results.

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

=head1 Options

=over

=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<--event>

Filter by event type. May be specified more than once. Allowed values are:

=over

=item * C<deploy>

=item * C<revert>

=item * C<fail>

=back

=item C<--change-pattern>

=item C<--change>

A regular expression to match against change names.

=item C<--project-pattern>

=item C<--project>

A regular expression to match against project names.

=item C<--committer-pattern>

=item C<--committer>

A regular expression to match against committer names.

=item C<--format>

=item C<-f>

The format to use. May be one of:

=over

=item C<full>

=item C<long>

=item C<medium>

=item C<short>

=item C<oneline>

=item C<raw>

=item C<< format:<string> >>

=back

See L</Formats> for details on each format. Defaults to C<medium>.

=item C<--date-format>

=item C<--date>

Format to use for timestamps. Defaults to C<iso>. Allowed values:

=over

=item C<iso>

=item C<iso8601>

Shows timestamps in ISO-8601 format.

=item C<rfc>

=item C<rfc2822>

Show timestamps in RFC-2822 format.

=item C<full>

=item C<long>

=item C<medium>

=item C<short>

Show timestamps in the specified format length, using the system locale's
C<LC_TIME> category.

=item C<raw>

Show timestamps in raw format, which is strict ISO-8601 in the UTC time zone.

=item C<strftime:$string>

Show timestamps using an arbitrary C<strftime> pattern. See
L<DateTime/strftime Paterns> for comprehensive documentation of supported
patterns.

=item C<cldr:$pattern>

Show timestamps using an arbitrary C<cldr> pattern. See
L<DateTime/CLDR Paterns> for comprehensive documentation of supported
patterns.

=back

=item C<--max-count>

=item C<-n>

Limit the number of events to output.

=item C<--skip>

Skip the specified number events before starting to show the event output.

=item C<--reverse>

Output the events in reverse order. 

=item C<--no-reverse>

Do not output the events in reverse order. 

=item C<--headers>

Output headers describing target. Enabled by default.

=item C<--no-headers>

Do not output headers describing target.

=item C<--color>

Show colored output. The value may be one of:

=over

=item C<auto> (the default)

=item C<always>

=item C<never>

=back

=item C<--no-color>

Turn off colored output. It is the same as C<--color never>.

=item C<--abbrev>

Instead of showing the full 40-byte hexadecimal change ID, show only a partial
prefix the specified number of characters long.

=item C<--oneline>

Shorthand for C<--format oneline --abbrev 6>.

=item C<--registry>

  sqitch log --registry registry

The name of the Sqitch registry schema or database in which sqitch stores its
own data.

=item C<--db-client>

=item C<--client>

  sqitch log --client /usr/local/pgsql/bin/psql

Path to the command-line client for the database engine. Defaults to a client
in the current path named appropriately for the database engine.

=item C<-d>

=item C<--db-name>

  sqitch log --db-name widgets
  sqitch log -d bricolage

Name of the database. In general, L<targets|sqitch-target> and URIs are
preferred, but this option can be used to override the database name in a
target.

=item C<-u>

=item C<--db-user>

=item C<--db-username>

  sqitch log --db-username root
  sqitch log --db-user postgres
  sqitch log -u Mom

User name to use when connecting to the database. Does not apply to all
engines. In general, L<targets|sqitch-target> and URIs are preferred, but this
option can be used to override the user name in a target.

=item C<-h>

=item C<--db-host>

  sqitch log --db-host db.example.com
  sqitch log -h appdb.example.net

Host name to use when connecting to the database. Does not apply to all
engines. In general, L<targets|sqitch-target> and URIs are preferred, but this
option can be used to override the host name in a target.

=item C<-p>

=item C<--db-port>

  sqitch log --db-port 7654
  sqitch log -p 5431

Port number to connect to. Does not apply to all engines. In general,
L<targets|sqitch-target> and URIs are preferred, but this option can be used
to override the port in a target.

=back

=head1 Configuration Variables

=over

=item C<log.format>

Output format to use. Supports the same values as C<--format>.

=item C<log.date_format>

Format to use for timestamps. Supports the same values as the C<--date-format>
option.

=item C<log.color>

Output colors. Supports the same values as the C<--color> option.

=back

=head1 Formats

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

=over

=item C<oneline>

  <change id> <event type> <project name>:<change name> <title line>

This is designed to be as compact as possible.

=item C<short>

  <event type> <change id>
  Name:      <change name>
  Committer: <committer>

  <title line>

=item C<medium>

  <event type> <change id>
  Name:      <change name>
  Committer: <committer>
  Date:      <commit date>

  <full change note>

=item C<long>

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

  <full change note>

=item C<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>
  Committer: <committer>
  Committed: <commit date>

  <full change note>

=item C<raw>

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

  <full change note>

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

=item C<< format:<string> >>

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

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

Would show something like this:

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

The placeholders are:

=over

=item * C<%H>: Event change ID

=item * C<%h>: Event change ID (respects C<--abbrev>)

=item * C<%n>: Event change name

=item * C<%o>: Event change project name

=item * C<%($len)h>: abbreviated change of length C<$len>

=item * C<%e>: Event type (deploy, revert, fail)

=item * C<%l>: Localized lowercase event type label

=item * C<%L>: Localized title case event type label

=item * C<%c>: Event committer name and email address

=item * C<%{name}c>: Event committer name

=item * C<%{email}c>: Event committer email address

=item * C<%{date}c>: commit date (respects C<--date-format>)

=item * C<%{date:rfc}c>: commit date, RFC2822 format

=item * C<%{date:iso}c>: commit date, ISO-8601 format

=item * C<%{date:full}c>: commit date, full format

=item * C<%{date:long}c>: commit date, long format

=item * C<%{date:medium}c>: commit date, medium format

=item * C<%{date:short}c>: commit date, short format

=item * C<%{date:cldr:$pattern}c>: commit date, formatted with custom L<CLDR pattern|DateTime/CLDR Patterns>

=item * C<%{date:strftime:$pattern}c>: commit date, formatted with custom L<strftime pattern|DateTime/strftime Patterns>

=item * C<%c>: Change planner name and email address

=item * C<%{name}p>: Change planner name

=item * C<%{email}p>: Change planner email address

=item * C<%{date}p>: plan date (respects C<--date-format>)

=item * C<%{date:rfc}p>: plan date, RFC2822 format

=item * C<%{date:iso}p>: plan date, ISO-8601 format

=item * C<%{date:full}p>: plan date, full format

=item * C<%{date:long}p>: plan date, long format

=item * C<%{date:medium}p>: plan date, medium format

=item * C<%{date:short}p>: plan date, short format

=item * C<%{date:cldr:$pattern}p>: plan date, formatted with custom L<CLDR pattern|DateTime/CLDR Patterns>

=item * C<%{date:strftime:$pattern}p>: plan date, formatted with custom L<strftime pattern|DateTime/strftime Patterns>

=item * C<%t>: Comma-delimited list of tags

=item * C<%{$sep}t>: list of tags delimited by C<$sep>

=item * C<%T>: Parenthesized list of comma-delimited tags

=item * C<%{$sep}T>: Parenthesized list of tags delimited by C<$sep>

=item * C<%s>: Subject (a.k.a. title line)

=item * C<%r>: Comma-delimited list of required changes

=item * C<%{$sep}r>: list of required changes delimited by C<$sep>

=item * C<%R>: Localized label and list of comma-delimited required changes

=item * C<%{$sep}R>: Localized label and list of required changes delimited by C<$sep>

=item * C<%x>: Comma-delimited list of conflicting changes

=item * C<%{$sep}x>: list of conflicting changes delimited by C<$sep>

=item * C<%X>: Localized label and list of comma-delimited conflicting changes

=item * C<%{$sep}X>: Localized label and list of conflicting changes delimited by C<$sep>

=item * C<%b>: Body

=item * C<%B>: Raw body (unwrapped subject and body)

=item * C<%{$prefix}>B: Raw body with C<$prefix> prefixed to every line

=item * C<%{event}_> Localized label for "event"

=item * C<%{change}_> Localized label for "change"

=item * C<%{committer}_> Localized label for "committer"

=item * C<%{planner}_> Localized label for "planner"

=item * C<%{by}_> Localized label for "by"

=item * C<%{date}_> Localized label for "date"

=item * C<%{committed}_> Localized label for "committed"

=item * C<%{planned}_> Localized label for "planned"

=item * C<%{name}_> Localized label for "name"

=item * C<%{project}_> Localized label for "project"

=item * C<%{email}_> Localized label for "email"

=item * C<%{requires}_> Localized label for "requires"

=item * C<%{conflicts}_> Localized label for "conflicts"

=item * C<%v> vertical space (newline)

=item * C<%{$color}C>: An ANSI color: black, red, green, yellow, reset, etc.

=item * C<%{:event}C>: An ANSI color based on event type (green deploy, blue revert, red fail)

=item * C<%{$attribute}a>: The raw attribute name and value, if it exists and has a value

=back

=back

=head1 Sqitch

Part of the L<sqitch> suite.
