Git Workspace
@twonines/git-workspacev2026.07.22.1
01README
Local git operations model — clone, branch, read, commit, push. Designed for agent-driven development workflows where code changes are authored locally and pushed to a remote forge. Supports a configurable workspace layout (default: $HOME/{host}/{group}/{project}) and commit message format enforcement.
02Release Notes
Add forge ref fetching to the branch method. GitLab MR refs (merge-requests/N/head) and GitHub/Forgejo PR refs (pull/N/head) are now explicitly fetched and checked out in detached HEAD mode. Previously these refs were silently missed by the default fetch refspec, causing the method to fall through to creating a new branch from default. Output schema adds optional 'detached: true' field when on a forge ref.
03Models
@twonines/git-workspacev2026.07.20.1mod.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host | string | Git remote host (e.g. gitlab.example.com, codeberg.org). Used to construct clone URLs and workspace paths. |
| baseDir? | string | Base directory for workspaces. Default: $HOME. Repos are placed at {baseDir}/{host}/{group}/{project}. |
| defaultBranch? | string | Default branch name (default: main). Used as the base for new branches. |
| commitFormat? | string | Commit message format hint for the agent. Example: 'leading-verb, 50 char title, blank line, body explains why'. |
| protocol? | enum | Clone protocol. 'ssh' (default) uses git@host:project.git; 'https' uses https://host/project.git. |
fn ensure(project: string, localPath?: string, protocol?: enum, ref?: string)
Clone the repo if it doesn't exist locally, or fetch + pull if it does.
| Argument | Type | Description |
|---|---|---|
| project | string | Project path (e.g. myorg/my-repo, team/infra-dns). |
| localPath? | string | Override the computed local path. |
| protocol? | enum | Override the global clone protocol for this project. |
| ref? | string | Checkout this branch/tag after clone or fetch instead of the default branch. |
fn branch(project: string, branch: string, localPath?: string)
Switch to a branch. If it exists on the remote, tracks it.
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| branch | string | Branch name to switch to or create (e.g. feat/add-txt-record). |
| localPath? | string | Override the computed local path. |
fn read_file(project: string, path: string, localPath?: string)
Read a file from the workspace. Run ensure first to clone.
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| path | string | File path relative to repo root. |
| localPath? | string | Override the computed local workspace path. |
fn list_files(project: string, pattern?: string, localPath?: string)
List tracked files matching a pattern (via git ls-files).
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| pattern? | string | Glob pattern or directory (e.g. 'terraform/**/*.tf'). Default: all tracked files. |
| localPath? | string | Override the computed local workspace path. |
fn commit(project: string, message: string, files?: array, amend?: boolean, localPath?: string)
Stage files and commit. Message should follow commitFormat if set.
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| message | string | Commit message. |
| files? | array | Files to stage (relative to repo root). Omit to stage all changes. |
| amend? | boolean | Amend the last commit instead of creating a new one. Default: false. |
| localPath? | string | Override the computed local workspace path. |
fn push(project: string, force?: boolean, localPath?: string)
Push the current branch to origin with -u tracking.
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| force? | boolean | Force push (--force-with-lease). Default: false. |
| localPath? | string | Override the computed local workspace path. |
fn rm(project: string, files: array, localPath?: string)
Stage file deletions via git rm. Files are removed from the working
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| files | array | Files to remove (relative to repo root). |
| localPath? | string | Override the computed local workspace path. |
fn status(project: string, localPath?: string)
Show workspace status: current branch, clean/dirty, modified files, ahead/behind remote.
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| localPath? | string | Override the computed local workspace path. |
fn diff(project: string, ref?: string, nameOnly?: boolean, localPath?: string)
Show diff output. Defaults to working tree diff; provide a ref to diff against (e.g. origin/main, HEAD~3).
| Argument | Type | Description |
|---|---|---|
| project | string | Project path. |
| ref? | string | Ref to diff against (e.g. origin/main, HEAD~1). Default: working tree diff. |
| nameOnly? | boolean | Only list changed file names, no patch content. Default: false. |
| localPath? | string | Override the computed local workspace path. |
Resources
workspace(1h)— State of a cloned/updated workspace
branch(1h)— Created branch metadata
file(30m)— Contents of a file read from the workspace
files(30m)— File listing from the workspace
commit(infinite)— Result of a git commit
push(infinite)— Result of a git push
rm(30m)— Result of staged file removals
status(5m)— Current workspace status (branch, clean/dirty, ahead/behind)
diff(10m)— Diff output between refs or working tree
04Previous Versions
2026.07.21.1
Modified 1 models
2026.07.20.1
Add rm method: stage file deletions via git rm for subsequent commit.
Modified 1 models
2026.07.16.1
2026.07.15.3
2026.07.15.2
Modified 1 models
2026.07.15.1
2026.07.14.3
Fix instance name sanitization (slashes in project paths and branch names caused writeResource failures). Add test coverage for the bug. 12 tests passing.
2026.07.14.2
Auto-detects default branch from remote HEAD. Sanitized resource instance names. Generic docs.
2026.07.14.1yanked
05Stats
A
100 / 100
Downloads
12
Archive size
15.8 KB
- 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
06Platforms
07Labels