WSM (workspace-manager) orchestrates multi-repository development. If you work on features that span two or more Git repositories at once, WSM keeps them aligned under a single workspace: same branch name, shared status view, coordinated commits and rebases.

This tutorial walks you through the core loop: discover your repositories, create a workspace, work in it, and clean up when you are done.

Prerequisites

WSM should be installed and on your $PATH. Confirm with:

wsm --help

Your repositories must already be cloned somewhere on disk. WSM does not clone for you -- it discovers existing repositories and creates lightweight git worktrees to avoid duplicating them.

Step 1: Discover repositories

Before WSM can manage your repos, it needs to know where they are. Point wsm discover at one or more parent directories:

wsm discover ~/code ~/projects

Discovery walks each path recursively (up to depth 3 by default) looking for .git directories. Found repositories are recorded in a local registry at ~/.config/workspace-manager/registry.json.

You can tune the scan:

After discovery, verify your registry:

wsm list repos

This prints a table of repository name, path, current branch, tags, and remote URL. If a repository is missing, re-run discovery with a wider path or higher --max-depth.

Step 2: Create a workspace

A workspace ties together a set of repositories under a common branch. To create one, name it and list the repos:

wsm create my-feature --repos workspace-manager,geppetto

WSM will:

1. Create a date-stamped workspace directory (e.g. ~/workspaces/2026-02-28/my-feature/).
2. Set up a git worktree for each named repository inside that directory.
3. Create or check out a branch in each worktree.

If you do not supply --branch, WSM generates one automatically as <prefix>/<workspace-name>. The default prefix is task, so the branch above would be task/my-feature. You can change this:

If you are not sure which repos to include, try --interactive to get a selection prompt, or --dry-run to preview the result before committing to it.

After creation, cd into the workspace and start working:

cd ~/workspaces/2026-02-28/my-feature

Step 3: Check status

wsm status gives you a consolidated view of git state across every repository in the workspace. Run it from inside the workspace:

wsm status

Or pass the workspace name explicitly from anywhere:

wsm status my-feature

The output shows a per-repository table with columns for branch, status, changes, sync state, merge state, and rebase state. Below the table, modified and staged files are listed per repository.

Useful flags:

Use --short for a quick glance and --untracked when you want to see new files that have not been added yet.

Step 4: Clean up when done

Once your feature branches are merged upstream, delete the workspace:

wsm delete my-feature

WSM will show you the current workspace status, then ask for confirmation before proceeding. It removes git worktrees and the workspace configuration file.

Key flags:

Without --remove-files, WSM removes worktree registrations and config but leaves the directory on disk. Add --remove-files for a full cleanup. Use --force-worktrees only when you are certain that any uncommitted work can be discarded.

What to do next

Now that you have the basic workflow, explore these areas:

• Commit across repos: wsm commit -m "your message" stages and commits changes across all workspace repositories at once. See wsm help wsm-command-reference.

• Rebase all repos: wsm rebase rebases every repository against a target branch (default main). If conflicts arise in one repo, the others still proceed, and you can resolve conflicts per-repo with wsm rebase status and wsm rebase continue.

• Fork a workspace: wsm fork new-name creates a new workspace from an existing one, preserving the same repository set but creating fresh branches.

• Script with JavaScript: wsm runner script.js executes JavaScript with the full WSM API available via require("wsm"). See wsm help wsm-js-api-and-runner.

Troubleshooting

See Also

• wsm help wsm-command-reference
• wsm help wsm-persistence-and-state
• wsm help wsm-troubleshooting