App::S...matter(3pm)

📦
version 1.6.1 · 6 versions
, in ubuntu stonking

🎀 NAME

Bestie, meet App::Sqitch::ItemFormatter — she formats events and changes so your command output looks cute and readable. This page lives in the User Contributed Perl Documentation corner of the manual, filed under App::S...matter(3pm) because the header ran out of room to spell her whole name. Rude, honestly.

✨ SYNOPSIS

my $formatter = App::Sqitch::ItemFormatter->new(%params);
say $formatter->format($format, $item);

💖 DESCRIPTION

Okay so picture this: commands need to turn raw items into pretty strings for output, and this class is the girl doing it. For example, log uses her to format all the events it digs up. Under the hood she's using String::Formatter for the actual formatting work, but she's pre-configured it for literally all the things you'd typically want to show — change names, IDs, event types, the whole vibe. And that's what makes her so easy to work with: all you have to hand format() is a format plus a hash reference of values to plug in. Simple. Iconic. Periodt.

🌸 INTERFACE

Constructor

new

my $formatter = App::Sqitch::ItemFormatter->new(%params);

Builds a formatter object and hands it right back to you. The params she accepts:

  • abbrev — instead of the full 40-byte hexadecimal change ID, show just a partial prefix that many characters long.
  • date_format — the format used for timestamps. Defaults to iso. Your allowed values, bestie:
    • iso
    • iso8601 — ISO-8601 format.
    • rfc
    • rfc2822 — RFC-2822 format.
    • full
    • long
    • medium
    • short — a format length you pass to the system locale's LC_TIME category.
    • raw — raw format, which is strict ISO-8601 in the UTC time zone.
    • strftime:$string — an arbitrary strftime pattern. Peep "strftime Paterns" in DateTime for the full rundown of supported patterns.
    • cldr:$pattern — an arbitrary cldr pattern. And "CLDR Paterns" in DateTime for that one's full rundown.
  • color — controls whether ANSI color formatting happens. One of:
    • auto (the default, queen of not making a scene)
    • always
    • never
  • formatter — a String::Formatter object. You lowkey probably don't want to pass one of these, because the default one already understands every value Sqitch is likely to want formatted.

Instance Methods

format

$formatter->format( $format, $item );

Formats an item into a string and returns it. The item gets formatted using the first argument. Scroll down to Formats for the gory details, iykyk.

The second argument is a hash reference defining the item to format. Just simple key/value pairs — usually attribute names and their values. Supported keys:

  • event — the type of event, which is one of:
    • deploy
    • revert
    • fail
  • project — the name of the project the change is associated with.
  • change_id — the change ID.
  • change — the name of the change.
  • note — a brief description of the change.
  • tags — an array reference of the names of associated tags.
  • requires — an array reference of the names of any changes required by the change.
  • conflicts — an array reference of the names of any changes that conflict with the change.
  • committed_at — an App::Sqitch::DateTime object representing the date and time the event was logged.
  • committer_name — name of the user who deployed the change.
  • committer_email — email address of the user who deployed the change.
  • planned_at — an App::Sqitch::DateTime object representing the date and time the change was added to the plan.
  • planner_name — name of the user who added the change to the plan.
  • planner_email — email address of the user who added the change to the plan.

🔥 FORMATS

The format argument you pass to format() is what decides which item info makes it into the resulting string. She's giving a lil bit of printf format, a lil bit of Git log format. Like, check this format out:

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

Would show you something like:

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

Now the placeholders, all of them, no skips:

  • %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: Event committer name and email address
  • %{name}c: Event committer name
  • %{email}c: Event committer email address
  • %{date}c: commit date (respects --date-format)
  • %{date:rfc}c: commit date, RFC2822 format
  • %{date:iso}c: commit date, ISO-8601 format
  • %{date:full}c: commit date, full format
  • %{date:long}c: commit date, long format
  • %{date:medium}c: commit date, medium format
  • %{date:short}c: commit date, short format
  • %{date:cldr:$pattern}c: commit date, formatted with custom CLDR pattern
  • %{date:strftime:$pattern}c: commit date, formatted with custom strftime pattern
  • %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
  • %{committer}_ Localized label for committer
  • %{planner}_ Localized label for planner
  • %{by}_ Localized label for by
  • %{date}_ Localized label for date
  • %{committed}_ Localized label for committed
  • %{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
Not me pointing out that %c shows up twice in that list — once as committer, once as planner. That's exactly how the original rolls, so we keep both, bestie. No cap.

👑 SEE ALSO

  • sqitch-log — documentation for the log command of the Sqitch command-line client.
  • sqitch — the Sqitch command-line client.

💜 AUTHOR

David E. Wheeler <david@justatheory.com>

🌈 LICENSE

Copyright (c) 2012-2026 David E. Wheeler, 2012-2021 iovation Inc.

And now the legal bit — lights dim, lawyers enter, and yes it has to be pasted exactly, no editing, no vibes, no cuts:

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

And that's the whole page, bestie 🫶 — this little icon was brought to you by perl v5.40.1, dated 2026-07-26, and she ate, fr fr. Go format something cute. 💅✨

📦 where this page comes from