=head1 Name
sqitch-log - Show Sqitch change logs
=head1 Synopsis
sqitch [options] 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<--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>.
=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.