/ 
Skilletor-0.001
/ Skilletor::Source::Git

NAME

Skilletor::Source::Git - A git source: shallow fetch into the shared cache, refs, SHA pins, offline reuse

VERSION

version 0.001

SYNOPSIS

use Skilletor::Source::Git;
use Skilletor::Cache qw( cache_root );

my $src = Skilletor::Source::Git->new(
  url        => 'https://github.com/Getty/skills',
  ref        => 'main',                 # optional: the remote's HEAD without
  cache_root => cache_root( $ENV{HOME} ),
);
my $loc = $src->resolve;     # { dir => '…/cache/d2425b64323b2f4a', version => 'git:ab12cd3' }
my $moved = $src->check( $loc->{version} );

DESCRIPTION

The reference's sources/git.ts (spec §4.4), down to the git commands it runs, so a cache one implementation made the other takes as is.

"resolve" shallow-fetches into <cache_root>/<16 hex> – the directory named by Skilletor::Cache – and hard-resets to what it fetched: ref, or the remote's HEAD. A SHA pin that the remote will not hand out shallowly falls back to a full fetch and a reset to the pin. A cache a killed run left half-made is repaired first, keeping its objects. Unreachable remote, existing cache: the cache is served with a warning – after its checkout is brought back to exactly its HEAD, and, for a SHA pin, only if HEAD is the pin. No cache, or a refused one: Skilletor::Error::Source.

Every git runs without a shell, with "git_env" in Skilletor::GitEnv and GIT_CEILING_DIRECTORIES above the cache; the address and the ref always follow --. Messages are the reference's, git's stderr included.

url

The git address, as configured; it reaches git after --.

ref

A branch, tag or commit; a 7 to 40 digit hex ref is a SHA pin.

cache_root

Where the caches live ("cache_root" in Skilletor::Cache).

timeout_ms

Per git run (default 60000); the child gets SIGTERM after it.

cache_dir

This source's cache directory ("git_cache_dir" in Skilletor::Cache).

resolve

{ dir, version => 'git:<short sha>', warning? }.

cached

{ dir, version } of the cache without touching the network – what "resolve" serves when its fetch fails, minus the warning (a Perl addition for offline callers; the reference has no such call). Throws Skilletor::Error::Source when there is no cache or it does not hold the pinned commit.

check

$src->check($cached_version);

A SHA pin already in $cached_version is unchanged without asking the remote; anything else compares the commit git ls-remote names for the ref (git's own ranking, annotated tags peeled) with the cached one.

remote_commit

$src->remote_commit( $ls_remote_output, $ref );

is_commitish

True for 7 to 40 hex digits: a SHA pin.

sweep_cache

Skilletor::Source::Git->sweep_cache($cache_root);

Removes stale git lock files from every git cache; only while holding the sync lock.

SUPPORT

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; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.