Skip to main content

gws fork

Create an isolated git worktree for parallel development with AI agents or feature branches.

Usage​

gws fork <worktree> [options]

Output:

✔ Worktree created in all 2 repos

ℹ ✨ Worktree Created:

ℹ    Project: myapp
ℹ    Worktree: feature-auth
ℹ    Namespace: myapp-feature-auth
ℹ    Branch: env/feature-auth
ℹ    Repositories: 1

Next steps:
  gws up -w feature-auth    # Deploy and start services

Note: If -p option is not specified, this command must be run from within your project directory.

Arguments​

ArgumentDescriptionRequired
<worktree>Worktree name (3-40 chars, lowercase, alphanumeric + hyphens)Yes

Options​

OptionDescriptionDefault
-p, --project <name>Project name to fork fromAuto-detected from current directory
--branch <name>Branch name to create (passed to git worktree -b)env/{worktree_name}

Examples

# Create worktree for current directory project
gws fork feature-payments

#Create worktree for a specific project
gws fork feature-payments -p myapp

Next Commands

  • Deploy: gws up -w feature-payments
  • Status: gws status -w feature-payments
  • Logs: gws logs api -w feature-payments
  • Stop: gws down -w feature-payments

Multirepo Behavior​

When running gws fork in a multirepo setup (parent directory containing multiple git repositories), all worktrees are created together under a single .worktrees/<worktree-name>/ folder at the parent level, with one subdirectory per repository.

Before Running gws fork​

myapp/                          # Parent directory (not a git repo)
├── api/                        # Git repo 1
│   ├── .git/
│   ├── src/
│   └── package.json
└── app/                        # Git repo 2
    ├── .git/
    ├── src/
    └── package.json

Running the Command​

cd myapp
gws fork feature-auth

After Running gws fork​

myapp/                          # Parent directory
├── .worktrees/                 # Shared worktrees folder (at parent level)
│   └── feature-auth/           # One folder per worktree name
│       ├── api/                # Worktree for api repo
│       │   ├── src/
│       │   └── package.json
│       └── app/                # Worktree for app repo
│           ├── src/
│           └── package.json
├── api/                        # Git repo 1 (unchanged)
│   ├── .git/
│   ├── src/
│   └── package.json
└── app/                        # Git repo 2 (unchanged)
    ├── .git/
    ├── src/
    └── package.json

Key Points:

  • All worktrees live under <parent>/.worktrees/<worktree-name>/<repo-name>/ — not inside each repo
  • Each repository still gets its own git worktree with the same branch name
  • The .worktrees/ folder is added to the parent .gitignore automatically
  • Deploy with: gws up -w feature-auth (deploys all repos together)

Troubleshooting​

Git Not Initialized​

Make sure you run the command from a git repository OR from the parent directory of a multi-repo project. Othrewise, initialize git:

git init
git add .
git commit -m "Initial commit"
git remote add origin <your-remote-url>
git push -u origin main

# Try again
gws fork feature-auth

Worktree Already Exists​

# Option 1: Use different name
gws fork feature-auth-v2

# Option 2: Delete existing
gws delete -w feature-auth
gws fork feature-auth

Name Too Long​

# Use shorter name (max 40 chars)
gws fork feature-auth-authz  # ✅ 19 chars

See Also​