/ 
App-karr-0.600
/ App::karr::Cmd::Sync

NAME

App::karr::Cmd::Sync - Sync karr board with remote

VERSION

version 0.600

SYNOPSIS

karr sync
karr sync --pull
karr sync --push

DESCRIPTION

Synchronises the refs/karr/* namespace with the configured remote. Without flags it fetches the remote ref state and then pushes the local ref state back, plus one delete refspec for every ref this clone deleted and has not published yet -- read off the tombstones under refs/karr-local/deleted/ -- so destructive restore operations are mirrored correctly. The push itself does not prune: a remote ref this clone has never seen is another agent's card, not a leftover, and pruning it is how a card was lost outright ("push" in App::karr::Git).

It then does the same for refs/karr-foundation/*, karr-foundation's shared chain, run logs and question mailbox (App::karr::Foundation::ChainStore) -- one command for both, because a second one would be a second thing to forget and forgetting it is silent. The board half runs first and this half never runs alone: the board's identity and wholesale-wipe refusals are what protects the fleet namespace against a swapped remote, since it carries neither of its own ("pull_foundation" in App::karr::Git). --pull, --push and --quiet apply to both halves; --prune and --accept-foreign-board are board-only, because they answer refusals only the board makes. A clone with nothing under refs/karr-foundation/ and no unpublished deletion there pushes nothing, so this costs an ordinary board repository one fetch and no push.

Both halves run through App::karr::Role::SyncLifecycle, so this command retries exactly as every writing command does: up to three attempts each, the first silent and the retries announced from the second, errors always on STDERR, and --quiet silencing the progress lines and the retry announcements but never an error. A push the remote refused ref by ref is not retried -- the far side gave its answer -- unless the refusal was only contention, two pushes racing for the same ref, which the next attempt wins ("push_contention" in App::karr::Git). This is the command karr points every failed sync at, and until #183 it was the only one that pushed once and gave up.

OPTIONS

  • --pull

    Only fetches remote refs/karr/*.

  • --push

    Only pushes local refs/karr/* state to the configured remote.

  • --prune

    Accepts a reconciliation that would delete every remaining board ref. Any other command refuses that and stops, because "the remote deliberately dropped the board" and "the remote is empty for the wrong reason" -- a re-created origin, an edited remote URL, a rolled-back hosting-side restore -- look exactly alike from here. Use it to let a karr destroy performed on another clone take effect on this one; check git remote -v first.

  • --accept-foreign-board

    Accepts a pull whose remote presents a different board identity than the one this clone has been syncing with. Any other pull refuses that before reconciling anything, because a swapped remote -- a re-initialised origin, an edited remote URL, a stale clone pointed at the wrong repository -- would otherwise replace this board with a stranger's, silently and totally. Use it when the remote's board really is the one you want from now on; check git remote -v first.

SEE ALSO

karr, App::karr, App::karr::Cmd::Board, App::karr::Cmd::Backup, App::karr::Cmd::Restore

SUPPORT

Issues

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

IRC

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

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

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

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)