How to Create Worktrees for Exploratory Work in Gas Town: A Complete Guide

Gas Town developers use the gt worktree <rig> command to create isolated Git worktrees that share the underlying bare repository, enabling fast experimental development without full clones.

Gas Town is an open-source framework designed to manage multi-tenant development environments where teams need isolated workspaces without the overhead of multiple repository clones. When you need to create worktrees for exploratory work in Gas Town, the system leverages Git's native worktree functionality to provide lightweight, attributed sandboxes perfect for experimentation, bug fixes, or prototyping across different rigs.

Understanding Gas Town Worktrees

A Gas Town worktree is a separate checkout of your repository that shares the same underlying bare Git repository (.repo.git). Unlike traditional clones that duplicate the entire .git directory, worktrees maintain a single object database while providing distinct working trees for different branches or experiments.

This architecture ensures that developers can spin up new environments in approximately five seconds, as documented in the persistent polecat pool design documents (docs/design/persistent-polecat-pool.md). The shared history means disk usage remains minimal while still providing complete isolation between experimental efforts.

The Architecture Behind Worktrees

According to docs/design/architecture.md, worktrees relate to the mayor-rig base through a specific hierarchy. When you create a worktree, Gas Town establishes a directory structure under ~/gt/<rig>/crew/<your-id>/, where the identity preserves your agent credentials across the isolated environment. This ensures that even though you're working in a separate checkout, commits maintain proper attribution to your original identity (e.g., gastown/crew/joe).

How to Create a Worktree for Exploratory Work

Creating an exploratory worktree in Gas Town requires specifying the target rig—the named environment or project context you want to work within. The process preserves your agent identity while providing a clean slate for development.

Step 1: Choose Your Target Rig

Identify which rig (project context) you want to explore. Common rigs might include beads, core, or custom team rigs. The rig name follows the gt worktree command directly.

Step 2: Execute the Creation Command

Run the worktree creation command in your terminal:

gt worktree beads

Gas Town immediately creates a new directory structure under ~/gt/beads/crew/gastown-joe/ (where gastown-joe derives from your agent identity). This directory contains the standard project layout—including .git, source folders like beads/, and doc/—but the .git file points to the shared bare repository rather than containing a full .git directory.

Step 3: Develop in Isolation

Move into your new worktree and begin exploratory development:

cd ~/gt/beads/crew/gastown-joe/
make test
git commit -am "experiment: try new feature"

All commits made in this worktree retain your original agent identity (BD_ACTOR = gastown/crew/joe), ensuring proper attribution even though you're working within the beads rig context. Changes in this worktree never interfere with other developers' environments or the main working tree.

Optional: Create with a Named Branch

If you need a specific branch name for organization, Gas Town supports the -b flag, mirroring the underlying git worktree add -b behavior:

gt worktree beads -b feature/exploration-2024

Internally, Gas Town implements this through the WorktreeAdd function in internal/git/git.go, which executes:

git worktree add -b polecat/<name>-<timestamp> polecats/<name>

This branch naming convention helps the Witness system track exploratory worktrees for automatic pruning later.

Implementation Details in the Gas Town Source Code

The worktree functionality is implemented in internal/git/git.go (lines 2215-2247), which contains the Go helpers WorktreeAdd and WorktreeAddFromRef. These functions wrap the native Git worktree commands while ensuring proper path resolution and branch naming conventions.

As shown in docs/design/polecat-self-managed-completion.md (lines 300-310), the same mechanism that creates worktrees for automated polecats is available to developers for manual exploratory work. The docs/overview.md (lines 123-129) provides high-level documentation confirming that gt worktree <rig> is the standard interface for this operation.

The implementation ensures that:

• Speed: New worktrees surface in approximately five seconds
• Isolation: Each worktree maintains its own branch independent of other developers
• Attribution: All commits, beads, and events preserve the original actor identity

Cleaning Up Worktrees

When your exploratory session concludes, you have two options for cleanup:

Manual removal using the CLI:

gt worktree rm beads

Automatic pruning by the Witness system, which monitors inactive worktrees and removes them according to the persistent polecat pool policies defined in docs/design/persistent-polecat-pool.md.

Summary

• Gas Town worktrees provide isolated development environments that share a single bare repository, eliminating clone overhead
• Create worktrees using gt worktree <rig>, which generates directories under ~/gt/<rig>/crew/<your-id>/
• The internal/git/git.go file contains the core implementation through WorktreeAdd and WorktreeAddFromRef functions
• All commits maintain original agent attribution via BD_ACTOR even when working across different rigs
• Worktrees can be removed manually with gt worktree rm <rig> or automatically pruned by the Witness
• Performance impact is minimal—approximately five seconds per worktree creation

Frequently Asked Questions

What is the performance impact of creating a Gas Town worktree?

Creating a Gas Town worktree takes approximately five seconds, as documented in docs/design/persistent-polecat-pool.md. Because worktrees share the underlying bare repository (.repo.git) rather than duplicating it, you avoid the network transfer and disk overhead of a full clone. The system only creates a new checkout with its own branch pointer, making it significantly faster than traditional repository cloning.

How does Gas Town handle git attribution across different worktrees?

Gas Town preserves your original agent identity across all worktrees through the BD_ACTOR environment variable. Even when you create a worktree in a different rig (e.g., moving from the main rig to beads), commits are attributed to your canonical identity (e.g., gastown/crew/joe). This attribution consistency is maintained by the directory structure under ~/gt/<rig>/crew/<your-id>/, which maps to your persistent agent credentials.

Can I specify a custom branch name when creating a Gas Town worktree?

Yes, you can specify a custom branch name using the -b flag, similar to standard Git worktree commands. When you run gt worktree <rig> -b <branch-name>, Gas Town's internal implementation in internal/git/git.go invokes the underlying Git command with the -b parameter. If you don't specify a name, the system generates one following the polecat/<name>-<timestamp> pattern used for automated worktree tracking.

Where are Gas Town worktrees physically stored on the filesystem?

Gas Town worktrees are stored under ~/gt/<rig>/crew/<your-id>/, where <rig> is the target project context and <your-id> derives from your agent identity (e.g., gastown-joe). Each worktree contains a standard checkout with a .git file (not directory) that points back to the shared bare repository. This location is derived from your agent identity to maintain consistent paths across sessions while keeping experimental work isolated from your main working directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}