Skip to content

submodules.md

Latest commit

 

History

History
101 lines (73 loc) · 3.1 KB

submodules.md

File metadata and controls

101 lines (73 loc) · 3.1 KB
Raw

Submodules

This repo tracks the project repos as submodules. That gives one place to see everything, at the cost of the usual submodule sharp edges.

Nothing here duplicates control-template — a project repo bootstrapped from the template already contains its own layout, standards, and docs. This page covers only the hub-specific mechanics.

Day-to-day

./tools/sync-all.sh

Run it after every git pull in this repo. A pull here moves the pointers; only this script moves your working copies.

If a submodule shows a + in git submodule status, its checked-out commit differs from the pointer recorded here. Common, usually harmless during local work. Commit the work in the submodule, then update the pointer here.

Adding a project

  1. Create the repo from control-template (see its README) and push it.

  2. Register it here:

    ./tools/add-submodule.sh \
    git@github.com:Hyperloop-UPV/<project>.git \
    src/algorithms/<project> main

  3. Add a row to the project table in the root README.

  4. Commit .gitmodules and the new path together — the pointer and the registration are one change.

Mount points are grouped by kind: src/algorithms/ for controllers, src/models/ for system models, src/libraries/ for shared Simscape or function libraries. add-submodule.sh rejects any target outside src/, because MATLAB sources do not belong in the hub.

Publishing a change

The order matters. In the submodule:

cd src/algorithms/<project>
git commit && git push

Then in the hub, point at the new commit:

cd -
git add src/algorithms/<project>
git commit -m "point <project> at <short-sha>"
git push

Two pushes, in that order. If the hub pointer is pushed first, CI-less teammates pull a pointer to a commit their clone cannot fetch, and sync-all.sh fails with a confusing error.

Removing a project

git rm src/algorithms/<project>

Then remove the row from the README table in the same commit. Do not delete the upstream repo while a pointer still references it.

Interpreting git submodule status

Prefix Meaning Action
(space) Checked out, matches the pointer Nothing
- Not initialised ./tools/sync-all.sh
+ Different commit from the pointer Intentional local work, or stale
U Merge conflict on the pointer Resolve in this repo, then git add the path

Why submodules, not a monorepo

Simulink .slx files are zip archives. They do not diff, they merge badly, and they bloat history. Splitting by project keeps those files in small repos where history stays navigable, and lets a project be cloned on its own. The cost is the bookkeeping on this page, which is what the scripts are for.

Hygiene

./tools/check-repo.sh

Fails if MATLAB sources have been committed to the hub, if submodules are uninitialised or diverged, or if doc index files are missing. Run it before pushing here. It is deliberately not wired into CI — the team has decided against CI on these repos for now, and there is no MATLAB licence in CI anyway.