Relationships
#2297 git: idempotent clone-or-update (ensure_checkout), and an idempotent branch option
Opened by usefulish · 9/20/2026· Shipped 9/26/2026
The gap
clone fails when the destination path already exists. That makes any
re-runnable workflow awkward: the first run clones, and every run after it
fails unless something clears the workspace first. There is no supported way to
express "make sure a checkout of this repo is at this ref, whatever state the
path is in."
The same applies to branch. With create: true it runs git checkout -b <name>, which fails when the branch already exists, so a workflow that creates
a working branch is also single-use.
Why it matters
This bites any workflow that operates on a checkout it manages itself — CI-style pipelines, scheduled jobs, and especially fan-out over many repositories, where clearing a workspace per repo before each run is both extra machinery and a destructive operation the workflow author has to get right.
Guards are not a clean fix here. A guard keyed on prior clone data skips the clone, but it cannot tell whether the directory still exists or has drifted, so it silently skips when it should re-clone.
What we ended up doing
We extended the type locally with export const extension, adding a single
method. It works well and has been running against real repositories, but it
reimplements logic that belongs upstream — and it means every consumer of the
workflow needs our extension alongside @swamp/git.
Proposed shape
ensure_checkout(url, path, ref?, depth?, reset?, branch?, token?)
- Path absent: clone (honouring
depthandref). - Path present and a checkout of the same repository:
fetch --prune, then whenresetis on,checkout --force -B <ref> origin/<ref>andclean -fdso the tree matches the remote exactly. - Path present but a checkout of a different repository: refuse.
resetdiscards local changes, so this guard matters — comparing owner/name across the various remote spellings (https, scp-style, ssh://) is enough. - Path present, non-empty, and not a git checkout: refuse rather than clone over it.
branch: create or move a working branch withcheckout -B, so re-running is a no-op instead of a "branch already exists" failure.- Output: a resource carrying
path,url(credentials scrubbed),ref,branch,sha, and anactionofcloned/updated/reused, so a later step can tell what actually happened.
A smaller alternative, if a new method is unwanted: an ifExists option on
clone (fail | update | reuse), and a force option on branch that
selects checkout -B. That would cover most of it, though without the
different-repository safety check, which we would not want to lose.
Happy to contribute
We have a working implementation and would be glad to turn it into a PR against
@swamp/git if the shape above looks right — or to adjust it to whatever
shape you prefer.
Upstream repository: https://github.com/swamp-club/swamp-extensions
Environment
- Extension:
@swamp/git@2026.09.15.1 - swamp:
20260918.211634.0-sha.bcaa9695 - OS:
darwin(aarch64) - Deno:
2.9.7 - Shell:
/bin/zsh
Shipped
Click a lifecycle step above to view its details.
stack72 commented 9/26/2026, 12:40:03 AM
Thanks @usefulish for reporting this! We shipped: Add an idempotent ensure_checkout method to @swamp/git (clone when absent or empty, fetch and optionally force-reset when the path is a checkout of the same repository, refuse on a different repository, a non-checkout directory, or a subdirectory of an enclosing repo; optional working branch via checkout -B; outputs path, scrubbed url, ref, branch, sha and action cloned/updated/reused). Tokens travel per-invocation via origin-scoped http.extraHeader in GIT_CONFIG_* env, never in argv or .git/config. Ref switching in single-branch clones widens the fetch refspec so upstream tracking is preserved. Also add force to the branch method so create is re-runnable via checkout -B.. The fix has been merged and a release is on its way. We appreciate your contribution to swamp.
Sign in to post a ripple.