workspace:sync
Table of contents
Introduction
workspace:sync brings the whole workspace up to date in one command. It fast-forwards every checkout at the workspace root, the framework and the CLI included, and clones every feature, product line and product of the marketplace that the workspace does not hold yet.
splent workspace:sync
workspace:sync
────────────────────────────────────────────────────────────
workspace /workspace
Updating 9 checkout(s)
updated toolchain splent_framework 8c3783b → 2aeed48 (175 commit(s))
updated feature splent_feature_accounts ef88c6e → fdac4b6 (67 commit(s))
skipped feature splent_feature_notes uncommitted changes; 3 upstream commit(s) waiting
updated toolchain splent_cli c47f51b → ed665ad (371 commit(s))
Looking for what the workspace lacks
index https://git.splent.io/splent-io/splent_index/raw/branch/main/index.json
org splent-io
Cloning 3 repository(ies)
cloned feature splent_feature_reports ssh://git@git.splent.io:2223/splent-io/splent_feature_reports.git
cloned spl splent_spl_cms ssh://git@git.splent.io:2223/splent-io/splent_spl_cms.git
cloned product diversolab_app ssh://git@git.splent.io:2223/splent-io/diversolab_app.git
Summary
3 updated, 3 cloned, 5 current, 1 skipped, 0 failed
Run it whenever you come back to a workspace after a while. It is safe to run at any time: what it cannot update without risk, it leaves alone and tells you.
Updating the checkouts
Every git repository at the workspace root is fetched and, when it is behind its upstream, fast-forwarded. That covers the toolchain (splent_framework, splent_cli, splent_docs, splent_claude), the editable features, the product line working copies, the products, and any other repository you cloned there.
A checkout is left exactly as it was, and reported, when
| Shown as | Because |
|---|---|
skipped, uncommitted changes |
A tracked file has changes. Untracked files do not count |
skipped, diverged |
It has commits of its own and the upstream has others |
skipped, HEAD is not on a branch |
The checkout is on a tag or a commit, not a branch |
skipped, tracks no remote branch |
The branch has no upstream |
ahead |
It has commits of its own that are not pushed, and nothing to pull |
Nothing is merged, rebased, reset or stashed. A checkout that cannot fast-forward is yours to sort out, with git as usual.
splent_cli goes last, on its own, so a failure anywhere else never leaves a half-updated CLI behind. The CLI is installed in editable mode from the workspace, so the next splent command already runs the new version.
When the toolchain changes its dependencies
If the fast-forward of splent_cli or splent_framework changes its pyproject.toml, the command says so and prints how to install the new dependencies inside the container.
cd /workspace/splent_cli && uv pip install --system -e ../splent_framework -e ".[dev,uvl]"
Rebuilding the container from the host, with make setup-rebuild, does the same from scratch.
Cloning what is missing
Each repository the workspace lacks is cloned into the workspace root with its whole history, so it is ready to work in.
| Kind | Where the list comes from |
|---|---|
| Features | Every feature of the marketplace index, from the host each entry names |
| Product lines | The splent_spl_<name> repositories of the organisation whose <name>, or <name>_spl, is a product line of the index |
| Products | The repositories of the organisation whose pyproject.toml declares [tool.splent] features |
The index is read from SPLENT_INDEX_URL, or from SPLENT’s published index when that is unset, and refreshes the workspace copy, .splent_cache/marketplace/index.json. When it cannot be reached, the workspace copy is used. With neither, features and product lines are not looked for and the summary says so.
The index does not list products, so they are found by reading the organisation: one request per repository that is not a feature, a product line or part of the toolchain. Archived repositories are left out, and so is a feature or a product line that is on the forge but not in the index yet.
A private repository needs the token of its host in the workspace .env. See Tokens setup.
Doing less
splent workspace:sync --dry-run # fetch and report, change nothing
splent workspace:sync --no-clone # only update what is here
splent workspace:sync --no-pull # only clone what is missing
splent workspace:sync --only feature # features only
splent workspace:sync --only product --only spl
| Option | What it does |
|---|---|
--dry-run |
Fetches every checkout and reports what is behind and what is missing, without fast-forwarding or cloning. Fetching updates the remote-tracking branches, never your files |
--no-clone |
Updates the checkouts that are here and clones nothing |
--no-pull |
Clones what is missing and leaves the checkouts as they are |
--only KIND |
Limits both halves to toolchain, feature, spl or product. Repeatable. Without it, repositories of no kind are updated too |
--org ORG |
Reads product lines and products from this organisation instead of SPLENT_DEFAULT_ORG (splent-io). Repeatable. Write github.com/acme for one on another host |
--jobs N, -j N |
Repositories handled at once, 8 by default |
--verbose, -v |
Lists the checkouts that were already up to date too |
--no-clone and --no-pull together leave nothing to do, so the command refuses them.
Exit status
The command exits with 1 when a fetch, a fast-forward or a clone failed, for example because a host was unreachable. A skipped checkout is not a failure: it exits with 0.
See also
feature:pull, the same update for the editable features only.feature:clone, to put one released version of a feature in the cache.- Installing features, for installing a feature into a product.