Skip to main content
← back to extensions

Git

@swamp/gitv2026.09.28.1· 8d agoMODELS
01README

Git repository operations for swamp workflows. Wraps the git CLI and returns structured data (file lists, commit objects, status entries) instead of raw text, making git operations composable in swamp workflows.

Designed for CI automation: change detection via diff, dirty-tree checks via status, push/sync verification via upstream_state, bot commits, branch management, re-runnable checkouts via ensure_checkout, and per-work-item worktrees via ensure_worktree and verify_worktree.

Methods

Method What it does
clone Clone a repository with configurable depth, branch, and auth.
ensure_checkout Idempotent clone-or-update: clone when absent, fetch and optionally force-reset a checkout of the same repository, refuse anything else.
diff Show changes between refs — name-only file lists, stat summaries, or full diffs.
worktree_diff Read-only working-tree diff — staged, unstaged, and untracked changes vs a base ref.
status Working tree status with structured entries and clean/dirty flag.
remote_ref Look up the SHA of a named ref on a remote via git ls-remote (read-only).
upstream_state Tracking-branch state: configured upstream, tracking-ref availability, ahead/behind counts, pushed/synced flags.
is_ancestor Check if one commit is an ancestor of another (read-only, via git merge-base --is-ancestor).
log Commit history with structured entries (SHA, author, date, message).
commit Stage files and create a commit, optionally at a chosen author/committer date.
amend Amend the most recent commit — rewrite message, staged content, and/or dates. Records old and new SHA.
push Push commits to a remote (with optional force, force-with-lease, and set-upstream).
pull Pull changes from a remote (with optional rebase and ff-only).
fetch Fetch refs from a remote with optional tag and prune support.
cherry_pick Cherry-pick commits or abort an in-progress cherry-pick.
branch Create, switch, or list branches (supports orphan branch creation; force makes create re-runnable).
config Get or set git configuration values.
ensure_worktree Idempotently prepare one worktree and branch per work item: fetch an exact base, create or safely reuse a verified worktree, refuse unrelated or overlapping paths, keep in-progress rework.
verify_worktree Read-only, fail-closed check of a worktree against branch, base lineage, root, and remote.
remove_worktree Safely remove a registered clean secondary worktree — refuses the primary checkout and dirty worktrees.

Usage

swamp extension pull @swamp/git

swamp model create @swamp/git repo
swamp model edit repo

swamp model method run repo diff \
  --input base=HEAD~1 \
  --input nameOnly=true \
  --input 'paths:json=["*/manifest.yaml"]' \
  --json
02Models1
@swamp/gitv2026.09.28.1git.ts
fn clone()
Clone a git repository
fn ensure_checkout()
Idempotently make sure a checkout of a repository exists at a path: clone when absent, fetch (and optionally force-reset) when it is already a checkout of the same repository, refuse otherwise
fn ensure_worktree()
Idempotently prepare one worktree and branch per work item: fetch an exact base ref, create or safely reuse a verified worktree, refuse unrelated or overlapping paths, and preserve in-progress rework
fn verify_worktree()
Read-only, fail-closed check that an existing worktree matches the expected branch, base lineage, root, and remote — never resets or discards work
fn diff()
Show changes between refs with optional name-only and path filtering
fn worktree_diff()
Read-only working-tree diff: compare a base ref against the working tree including staged, unstaged, and untracked non-ignored files
fn status()
Show working tree status with structured output
fn log()
Show commit history with structured entries
fn commit()
Stage files and create a commit
fn amend()
Amend the most recent commit — rewrite message and/or staged content
fn push()
Push commits to a remote with optional force or force-with-lease
fn branch()
Create, switch, or list branches
fn pull()
Pull changes from a remote into the current branch
fn fetch()
Fetch refs from a remote with optional tag and prune support
fn cherry_pick()
Cherry-pick commits onto the current branch, or abort an in-progress cherry-pick
fn config()
Get or set git configuration values
fn remote_ref()
Look up the SHA of a named ref on a remote via git ls-remote (read-only, no worktree mutation)
fn upstream_state()
Report tracking-branch state: ahead/behind counts, pushed/synced flags
fn is_ancestor()
Check if one commit is an ancestor of another via git merge-base --is-ancestor (read-only)
fn remove_worktree()
Safely remove a registered clean secondary worktree — refuses the primary checkout and dirty worktrees, idempotent when already absent

Resources

cloneResult(ephemeral)— Result of a git clone operation
checkoutResult(ephemeral)— Result of ensure_checkout: path, scrubbed url, ref, working branch, HEAD sha, and whether the checkout was cloned, updated, or reused
worktreeResult(ephemeral)— Result of ensure_worktree: primary and worktree roots, branch, base ref and commits, HEAD, dirty flag, and whether the worktree was created, attached, or reused
worktreeVerification(ephemeral)— Result of a passing verify_worktree: roots, branch, HEAD, verified base commit, dirty flag, and verification time
diffResult(ephemeral)— Changed files and raw diff output from a git diff operation
statusResult(ephemeral)— Working tree status: structured entries, clean/dirty flag, count
logResult(ephemeral)— Commit history with structured entries
commitResult(ephemeral)— Result of a git commit: SHA and message
amendResult(ephemeral)— Result of a git commit --amend: old SHA, new SHA, and message
pushResult(ephemeral)— Result of a git push operation
branchResult(ephemeral)— Branch operation result: current branch, list, or creation status
configResult(ephemeral)— Git config get/set result
pullResult(ephemeral)— Result of a git pull operation
fetchResult(ephemeral)— Result of a git fetch operation
cherryPickResult(ephemeral)— Cherry-pick result: applied commits, conflict status, and conflicting files
remoteRefResult(ephemeral)— Remote ref lookup result: remote name, resolved ref, and SHA
isAncestorResult(ephemeral)— Ancestry check result: ancestor, descendant, and boolean isAncestor flag
removeWorktreeResult(ephemeral)— Worktree removal result: path, removed/alreadyAbsent flags, and reason
upstreamStateResult(ephemeral)— Tracking-branch state: branch, upstream, configuredUpstream, trackingRefAvailable, ahead/behind counts (nullable), pushed/synced flags (nullable)
worktreeDiffResult(ephemeral)— Working-tree diff: tracked changes (staged + unstaged) plus untracked non-ignored files, with reviewable patch output
03Previous Versions10
2026.09.26.1

Modified 1 models

2026.09.15.1

Modified 1 models

2026.08.28.1

Modified 1 models

2026.08.25.1

Modified 1 models

2026.08.18.2
2026.08.18.1
2026.08.17.1
2026.08.13.1

Modified 1 models

2026.08.07.1

Modified 1 models

2026.08.05.1
04Stats
A
100 / 100
Downloads
1,707
Archive size
67.0 KB
Verified by Swamp
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License declared1/1earned
  • Verified public repository2/2earned
Repository
https://github.com/swamp-club/swamp-extensions
05Platforms
06Labels
#git#ci#vcs#automation