Anvil

 █████╗ ███╗   ██╗██╗   ██╗██╗██╗     
██╔══██╗████╗  ██║██║   ██║██║██║     
███████║██╔██╗ ██║██║   ██║██║██║     
██╔══██║██║╚██╗██║╚██╗ ██╔╝██║██║     
██║  ██║██║ ╚████║ ╚████╔╝ ██║███████╗
╚═╝  ╚═╝╚═╝  ╚═══╝  ╚═══╝  ╚═╝╚══════╝

Create isolated multi-repository workspaces for engineering tasks.

Installation

From PyPI:

uv tool install git-anvil

From github:

uv tool install git+https://github.com/felixscherz/git-anvil

This installs a git-anvil executable, which Git exposes as the git anvil subcommand. The examples below use git anvil; you can also invoke git-anvil directly.

Getting started

Create a workspace

Provide a target directory and one or more repository specifiers. Each specifier can be a local path to an existing Git repository or any remote URL accepted by git clone.

git anvil create --target /tmp/workspaces/feature-abc \
  ~/repos/my-service \
  git@github.com:org/other-service.git

To override the inferred branch name, pass --branch (-b):

git anvil create --target /tmp/workspaces/feature-abc --branch my-feature \
  ~/repos/my-service

Anvil will:

1. Infer the branch name from the target directory name (feature-abc), or use the value of --branch when provided.
2. For local paths — create a git worktree on a new branch at the tip of the default branch.
3. For remote URLs — clone the repository and check out a new branch.
4. Write a manifest to /tmp/workspaces/feature-abc/.anvil/manifest.json.
5. Write an AGENTS.md at the workspace root describing the workspace layout for coding agents. It points to .anvil/manifest.json as the source of truth for the current repositories, and is removed on clean.

Example output:

Creating Anvil workspace: /tmp/workspaces/feature-abc
Branch: feature-abc
  + my-service -> /tmp/workspaces/feature-abc/my-service
  + other-service -> /tmp/workspaces/feature-abc/other-service

Created Anvil workspace: /tmp/workspaces/feature-abc
Branch: feature-abc
  - my-service -> /tmp/workspaces/feature-abc/my-service
  - other-service -> /tmp/workspaces/feature-abc/other-service

Clean up a workspace

git anvil clean /tmp/workspaces/feature-abc

If you are inside the workspace (or any subdirectory of it), the path can be omitted - Anvil walks up from the current directory until it finds an .anvil/manifest.json:

cd /tmp/workspaces/feature-abc
git anvil clean

Anvil reads the manifest, prints a summary, and prompts for confirmation before removing everything.

Anvil workspace: /tmp/workspaces/feature-abc
Branch: feature-abc
Repositories (2):
  - my-service (worktree) -> /tmp/workspaces/feature-abc/my-service
  - other-service (clone) -> /tmp/workspaces/feature-abc/other-service
Remove Anvil workspace at /tmp/workspaces/feature-abc containing 2 repositories? [y/N]

Skip the prompt with --yes:

git anvil clean /tmp/workspaces/feature-abc --yes

Add a repository to an existing workspace

git anvil add --target /tmp/workspaces/feature-abc ~/repos/another-service

Or, from anywhere inside the workspace:

cd /tmp/workspaces/feature-abc
git anvil add ~/repos/another-service

Anvil reads the branch name from the existing manifest (feature-abc) and creates the new repository on that same branch. The manifest is updated in place with the new entry appended. Rollback applies only to repos added in the current run - existing workspace members are untouched. clean and run likewise discover the workspace from the current directory when the workspace path / --workspace is omitted.

Notes

• The branch name is derived from the basename of --target. /tmp/workspaces/feature-abc → feature-abc. Pass --branch/-b to override it; the value is sanitized the same way as the inferred name.
• git anvil add reads the branch name from the existing manifest - the target directory name is irrelevant.
• add, clean, and run infer the workspace by walking up from the current directory when the workspace path / --target / --workspace is omitted. create always requires --target because it creates a new workspace.
• The same branch name is created in every repository in the workspace - this is expected and correct.
• If any repository fails during create or add, Anvil rolls back only the repos created in that run.
• Anvil will refuse to proceed if the target is non-empty, if a derived branch already exists, or if two repositories share the same derived name.