Vetvy a commity

Vetvy sa vrátia ako Page s názvami vetiev:

$branches = Git::github()->repo('acme/api')->branches()->items; // ['main', 'dev']

Head vetvy podľa presného názvu

branch() vráti head jednej vetvy — Branch s jej názvom a sha — na GitHube, GitLabe aj Bitbuckete. Na rozdiel od commit($ref), ktorý preloží čokoľvek, čo ukazuje na commit, odpovie len na presný názov vetvy: tag, sha alebo len začiatok názvu vetvy skončí bežnou RequestException 404, nikdy iným commitom — deploy, ktorý ide podľa názvu vetvy, tak nemôže dostať commit tagu:

$branch = Git::github()->repo('acme/infra')->branch('main'); // Branch — by its exact name

$branch->name;   // "main"
$branch->sha;    // the commit the branch points at

• GitHub sa číta cez /git/ref/heads/{branch}, nie cez /branches/{branch}, ktorý na premenovanú vetvu odpovie presmerovaním 301 a doviedol by k inému headu.
• Odpoveď, ktorá nie je presne head danej vetvy — na GitHube čokoľvek iné než refs/heads/<name> ukazujúce na commit so 40-znakovým sha —, vyhodí UnexpectedValueException.
• Názov pred odoslaním požiadavky prejde kontrolami refov (žiadny prechod mimo, žiadne medzery). Token GitHub App potrebuje contents: read.

Dopyt na commity

commits() vracia reťaziteľný CommitQuery. Každý filter je voliteľný a URL kódovanie zariadi balík:

$repo = Git::github()->repo('acme/api');

$commits = $repo->commits()               // CommitQuery
    ->branch('feature/new ui')            // properly URL-encoded
    ->author('jane-doe')
    ->path('src/')
    ->since(now()->subWeek())             // Carbon or an ISO 8601 string
    ->until(now())
    ->perPage(50)
    ->get();                              // Page<Commit>

$repo->commits()->get(page: 2);             // a specific page
$repo->commits()->collect();                // Collection<Commit>
$repo->commits()->branch('main')->first();  // ?Commit

foreach ($repo->commits()->branch('main')->lazy() as $commit) {
    // auto-paginated stream
}

• branch(), author(), path() — zúženie podľa refu, autora a cesty k súboru.
• since() / until() — inštancia Carbon alebo reťazec ISO 8601.
• perPage() — veľkosť stránky; get($page) — jedna Page<Commit>; collect($page) — tá istá stránka ako Collection.
• first() — prvý vyhovujúci commit alebo null; lazy() — LazyCollection cez všetky stránky.

GitHub a GitLab uplatnia všetky filtre. Endpoint commitov na Bitbuckete filtruje len podľa branch() a path(), preto na Bitbuckete author(), since() a until() pri spustení dopytu vyhodia FeatureNotSupportedException, namiesto toho, aby vrátili nefiltrované commity.

Jeden commit

$commit = Git::github()->repo('acme/api')->commit('6dcb09b...');

$commit->sha;
$commit->message;
$commit->author->name;   // Author: name, email, avatar
$commit->author->email;
$commit->url;            // ?string
$commit->commitAt;       // Carbon

Aktivita repozitára

activity() číta prehľad aktivity repozitára na GitHube od najnovšieho — pushe, vynútené pushe, vytvorenie a zmazanie vetiev, mergy pull requestov aj merge queue — pre celý repozitár alebo jeden ref (main či refs/heads/main):

$page = Git::github()->repo('acme/infra')->activity('refs/heads/main', perPage: 50); // Page<Activity>

foreach ($page as $activity) {
    $activity->type;          // ActivityType::Push, ForcePush, BranchCreation, BranchDeletion, …
    $activity->ref;           // e.g. "refs/heads/main"
    $activity->before;        // ?string — null for a branch creation
    $activity->after;         // ?string — null for a branch deletion
    $activity->actor?->name;  // who did it, or null
    $activity->occurredAt;    // Carbon
}

$next = $page->hasMore ? Git::github()->repo('acme/infra')->activity('main', 50, $page->nextCursor) : null;

• Stránkuje sa kurzorom: GitHub tu číslo stránky neprijíma, preto nextCursor zo stránky odovzdajte späť ako tretí argument, kým je hasMore true. perPage je obmedzené na 100.
• before je null pri vytvorení vetvy a after pri jej zmazaní (nulové sha z GitHubu); actor je null, keď GitHub nikoho neuvádza; typ, ktorý GitHub pridá neskôr, sa prečíta ako ActivityType::Unknown.
• 403 alebo 404 — inštalácia, ktorá prehľad čítať nesmie — zostáva RequestException, takže sa môžete vrátiť ku commits(). Token, ktorý smie čítať obsah repozitára, prečíta aj tento prehľad.
• Len GitHub (Feature::RepositoryActivity); GitLab a Bitbucket vyhodia FeatureNotSupportedException.