untaped-workspace

Install it as part of untaped: uv tool install 'untaped[workspace]' or pip install 'untaped[workspace]'. To add it to an existing install, see Getting started.

workspace is experimental and may change in a minor release.

A workspace is one directory per task. It holds a git worktree for each repo you need, all on the same branch, so you (or an agent) can change several repos for one ticket and archive the lot when the work is pushed. Worktrees share a bare cache of each repo, so creating a workspace is fast and cheap, and parallel tasks get isolated checkouts of the same repos.

Commands never discard local work: archiving refuses while a repo has uncommitted, stashed or unpushed work. The packaged skill and its references hold the per-command detail; --help lists the options, and --columns '?' lists a command's fields after it runs (use it on a read command, or add --dry-run to a write).

Create, work, archive

untaped workspace create PROJ-123 --repo acme/api --repo acme/web
cd "$(untaped workspace path PROJ-123)"
# commit and git push in each repo, then:
untaped workspace status PROJ-123 --check
untaped workspace archive PROJ-123

create prints one row per repo: a new branch from the base, or an existing branch resumed. status --check exits 3 while anything would block archiving; archive removes the worktrees and keeps a record. The branches stay in the repo cache and on the remote, so creating a workspace on the same branch later resumes the work.

Add repos later

untaped workspace add PROJ-123 --repo acme/infra

add also reads repos from a pipe, for example a GitHub repo listing:

untaped github repos list --team acme/platform --format pipe | untaped workspace add PROJ-123 --stdin

Pick repos interactively

In a terminal, untaped workspace create [NAME] and untaped workspace add [NAME] open a picker when you give no --repo, --read-only or --stdin. Without a terminal they exit 2 and name those flags. On create, an omitted NAME is asked first; the field refuses invalid names, active workspace names and directories that exist and are not empty.

The picker lists the GitHub inventory (github.inventory; it opens from the cache and refreshes when stale), repos already in the local repo cache (shown by their cache path, host/[owner/]name, checked out from their cached URL), and any git URL you type or paste. add leaves out repos already in the workspace.

Each selected repo has a mode (write or read-only), a base (completes from cached branches) and a branch (empty uses workspace.branch_template). --branch and --base without repo flags prefill these defaults.

Read-only repos

--read-only checks a repo out at its base branch, detached, for reference code you will not change. Archiving still refuses while it has local changes or commits of its own.

Jump in

cd "$(untaped workspace path PROJ-123)"

untaped workspace list shows active workspaces (--archived the rest). Inside a workspace directory, the name may be left out.

Run a command in every repo

untaped workspace status PROJ-123   # check the selection first
untaped workspace run PROJ-123 'git push -u origin HEAD'

run also takes a script file or a script on stdin, runs in the writable repos, and exits 1 if any repo failed. Forms, environment variables, selection and timeouts are in the run reference. The UNTAPED_* variables it sets are in environment.

Settings

workspace.cache_dir, workspaces_dir, parallel, branch_template and protocol are in the configuration reference. OWNER/NAME and bare names are looked up in the GitHub inventory, scoped by github.inventory orgs and teams.

Output

Every command prints rows you can reshape with --format and --columns; see Scripting and Exit codes.

See also

• Configuration and the configuration reference.
• GitHub, to find repos to add, and Recipes, to change files across a workspace.