view release on metacpan or  search on metacpan

lib/App/karr/Cmd/Backup.pm  view on Meta::CPAN

# ABSTRACT: Export the ref-backed karr board as YAML

package App::karr::Cmd::Backup;
our $VERSION = '0.600';
use Moo;
use MooX::Cmd;
use MooX::Options (
  usage_string => 'USAGE: karr backup [--output PATH]',
);
use Path::Tiny;
use App::karr::Encoding qw( yaml_dump );
use App::karr::Error qw( user_error clean_error command_hint );
use App::karr::Role::BoardDiscovery;
use App::karr::Role::CliArgs;
use App::karr::Role::SyncLifecycle;

with 'App::karr::Role::BoardDiscovery';
with 'App::karr::Role::SyncLifecycle';
with 'App::karr::Role::CliArgs';


option output => (
  is => 'ro',
  format => 's',
  doc => 'Write YAML snapshot to a file instead of stdout',
);

sub execute {
  my ($self, $args_ref, $chain_ref) = @_;

  # store honours --dir (both call forms) and dies loudly if the target is
  # not a Git repository, instead of hardcoding the current directory.
  my $store = $self->store;

  # Backup is read-only: take the retrying pull half of the sync lifecycle,
  # then mark the guard done so this read path never pushes on exit or on die.
  my $guard = $self->sync_before;
  $guard->done;

  # The one spelling of this sentence, shared with require_board and with
  # destroy/materialize/repair: the way out is a command on its own last line
  # (ticket k263).
  die "No karr board found:\n" . command_hint('init') . "\n"
    unless $store->has_board_refs;

  # Characters all the way: spew_utf8 encodes for the --output file, and the
  # CLI's :encoding(UTF-8) layer encodes for stdout. A Dump() here would emit
  # octets and both paths would encode them a second time (ticket #53).
  my $yaml = yaml_dump( $store->snapshot );

  if ( $self->output ) {
    my $file = path( $self->output );
    # An --output karr cannot write is the user's path, not karr's: Path::Tiny
    # would otherwise report this file and line at them (#77).
    eval { $file->parent->mkpath; $file->spew_utf8($yaml); 1 }
      or user_error( "Could not write $file: ", clean_error($@) );
    print STDERR "Wrote backup to $file\n";
    return;
  }

  print $yaml;
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

App::karr::Cmd::Backup - Export the ref-backed karr board as YAML

=head1 VERSION

version 0.600

=head1 SYNOPSIS

    karr backup > karr-backup.yml
    karr backup --output karr-backup.yml

=head1 DESCRIPTION

Exports the complete C<refs/karr/*> namespace as a YAML snapshot. The default
mode writes the snapshot to standard output so it can be redirected or piped.
Use C<--output> when you want C<karr> to write the file directly.

=head1 OPTIONS

=over 4

=item * C<--output>

Write the YAML snapshot to the given file instead of standard output.

=back

=head1 SEE ALSO

L<karr>, L<App::karr>, L<App::karr::Cmd::Restore>,
L<App::karr::Cmd::Destroy>, L<App::karr::Cmd::Sync>

=head1 SUPPORT

=head2 Issues

Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/karr/issues>.

=head2 IRC

Join C<#langertha> on C<irc.perl.org> or message Getty directly.

=head1 CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

=head1 AUTHOR

Torsten Raudssus <getty@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> L<https://raudssus.de/>.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

=cut