Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

submodule-pin

/submodule-pin

Pilnuje, żeby nadrzędne repozytorium zapisywało właściwy commit submodułu, i naprawia klon z błędnym drzewem.

Repozytorium
Drift ↗
Licencja
MIT
Ostatnia zmiana repozytorium
07.11.2026

Ocena i bezpieczeństwo

95/ 100Klasa: dobry
Format20 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 07.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pilnuje, żeby nadrzędne repozytorium zapisywało właściwy commit submodułu, i naprawia klon z błędnym drzewem.

Oryginalny opis (EN)

Use when a parent records a submodule commit, or a clone checks out the wrong tree.

Jak działa

  1. The invariant
  2. The failure it prevents
  3. The probe
  4. The repair
  5. Pitfalls
  6. Claim-to-test
Sekcje z nagłówków SKILL.md, w oryginale · 122 linii, 880 słów
Podgląd SKILL.md
---
name: submodule-pin
description: "Use when a parent records a submodule commit, or a clone checks out the wrong tree."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [macos, linux]
category: Git
metadata:
  hermes:
    tags: [git, submodule, gitlink, pin, phantom]
    related_skills: [branch-invariant, remote-identity]
---

# Submodule Pin

A parent repository records, for each submodule, one commit ID. That ID is the
reference. Two things must agree with it: the submodule's remote must serve it,
and the submodule's checkout must sit on it.

## The invariant

**A recorded submodule commit is a commit the remote serves, and the checkout is
on it.**

## The failure it prevents

The two halves fail differently, and neither is visible in a diff.

**A phantom pin** is a recorded commit the remote does not serve. Nothing is
wrong locally - the object is in the local store, the build passes - and the
failure appears on someone else's clone as `upload-pack: not our ref`. It happens
when a submodule commit is made on a detached HEAD, or on a branch that was later
rewritten or deleted, and then recorded by the parent.

**A stale pin** is a recorded commit the submodule has moved past. `git submodule
status` prefixes the entry with `+`. A fresh clone checks out the recorded tree,
so a file that exists only in the newer commit is simply absent, and the build
failure that follows names the absent file rather than the pin.

## The probe

Three questions, in increasing cost. Ask only the one you need.

**Local - is each checkout on its pin?** No network.

```sh
git submodule status --recursive
```

A line beginning with `+` is a stale pin: the checkout is ahead of or diverged
from the record. A line beginning with `-` means the submodule is not
initialised, which is not drift. A leading space is agreement.

**Reachable - does the remote serve the recorded commit?** One fetch per pin.

```sh
git ls-files -s | awk '$1 == "160000" { print $2, $4 }'
```

Then, for each `<sha> <path>`, read the URL from `.gitmodules` and fetch the exact
object:

```sh
git fetch --quiet <url> <sha>
```

Exit `0` proves some advertised ref reaches the commit. A non-zero exit with
`not our ref` is a phantom pin.

**Current - is the pin the remote's default-branch tip?**

```sh
git ls-remote --symref <url> HEAD
```

The first field of the line whose second field is `HEAD` is the tip. Compare it
with the pin. This is the question a release repository asks; a library that pins
a dependency deliberately asks the first two and not this one.

## The repair

A phantom pin is repaired by making the commit real - push the branch that
contains it, then re-record the pin - or by re-recording the pin to a commit the
remote already serves. Which one is right is a decision about what the submodule
was supposed to contain, so there is no command here.

A stale pin is repaired by recording the checkout:

```sh
git add <path>
git commit -m "chore: bump submodule gitlinks: <path>@<sha>"
```

That commit is mechanical, so it belongs in a hook rather than in a habit.
`Documentation/Hook/Lib/bump-submodule-gitlinks.sh` is the one that runs in a
parent repository; `Documentation/Hook/Index.md` names it and the hooks that call
it.

## Pitfalls

- **`git submodule status` reports the record, not the remote.** It cannot see a
  phantom pin, because the object exists locally. Only a fetch answers that
  question.
- **A fetch of the exact SHA succeeds for any commit the remote serves, on any
  ref.** That is the point - it answers reachability, not intent. Do not read a
  successful fetch as "this pin is correct", only as "this pin is real".
- **`git merge-base --is-ancestor <pin> origin/<branch>` is an optimisation, not
  a substitute.** It answers only after the parent's default branch is fetched,
  and it answers about one branch. Use it to skip a network call, never to
  conclude a pin is unreachable.
- **A submodule is advanced by committing inside the parent's checkout, not in
  the repository it was cloned from.** `Parent/Sub` and the source `Sub` are two
  repositories with two `HEAD`s; a commit in the source moves neither the
  parent's index nor the checkout, so `git submodule status` correctly reports
  in-sync while the source has moved on. A probe that advances the source and
  then expects `+` is measuring the wrong repository, and it will pass or fail
  for a reason unrelated to the guard.
- **`ignore = all` in `.gitmodules` hides a dirty submodule, not a moved one.** A
  pointer update still appears; a modified worktree does not. That is why the
  bump hook compares with `git diff HEAD -- <path>` rather than reading status.
- **A submodule that is itself a parent must not run the bump.** The hook checks
  `git rev-parse --show-superproject-working-tree` and exits when it is non-empty;
  without that, a nested bump commits inside `vendor/` and the outer parent never
  sees it.

## Claim-to-test

| Claim | Probe | Pass condition |
| --- | --- | --- |
| No checkout has moved past its pin | `git submodule status --recursive` | no line begins with `+` |
| Every pin is served by its remote | `git fetch --quiet <url> <sha>` per pin | exit 0 |
| Every pin is current | `git ls-remote --symref <url> HEAD` | tip equals pin |
| The bump is automatic | `git config --get core.hooksPath` | names the directory holding the hooks |

Wersje

W bazie nie ma innych skilli o nazwie submodule-pin.

Migawka bazy z 13.11.2026 · wersja paczki 4f293632390b (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100submodule-go
    Pomaga pisać kod w Go z biblioteką submodule.go do wstrzykiwania zależności, w tym przy testach i typach Submodule[T].
  • 95submodule-links
    Podpowiada, jak linkować submoduł w dokumentacji, używając nazwy jego własnego repozytorium.
  • 95git-submodule
    Wyznacza, kiedy użyć submodułów Git i prowadzi bezpieczne operacje: dodawanie, przypinanie wersji, synchronizację, edycję i usuwanie.
  • 95cmux-ghostty
    Pilnuje zasad pracy z submodułem ghostty, przebudowuje GhosttyKit.xcframework i aktualizuje wskaźnik submodułu.
  • 95cmux-ghostty
    Pilnuje zasad pracy z submodułem ghostty i GhosttyKit w cmux: przebudowa xcframework, wskaźnik submodułu i konflikty forka.
  • 100submodule-setup
    Konfiguruje submoduły gita i migruje gałęzie do submodułów z automatyzacją synchronizacji między wieloma repozytoriami przez GitHub Actions.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.