How no-mistakes Uses Disposable Git Worktrees for Pipeline Execution

no-mistakes isolates CI-style pipeline steps by creating temporary, detached Git worktrees that are automatically cleaned up after execution, ensuring the main repository remains untouched.

The open-source tool no-mistakes (available at kunchenguid/no-mistakes) implements a daemon-based continuous integration system that leverages disposable Git worktrees to execute lint, test, and build operations in complete isolation. By utilizing temporary worktrees created from a bare repository, the system guarantees that pipeline execution never pollutes the developer's local working directory or interferes with ongoing work.

Why Disposable Git Worktrees?

A Git worktree provides a clean copy of the repository at a specific commit without affecting the main working directory. This architecture offers several advantages for pipeline execution:

• Isolation: Each pipeline runs in its own directory, preventing cross-contamination between concurrent jobs
• Speed: Worktrees can be created and deleted quickly compared to full clones
• Safety: Operations occur in a detached state, eliminating the risk of accidentally pushing changes upstream
• Resource efficiency: Worktrees share the same underlying Git object database while maintaining separate working trees

Creating Isolated Execution Environments

The daemon's manager, located in internal/daemon/manager.go, orchestrates worktree creation by calling git.WorktreeAdd with three critical parameters: the repository's bare directory (gateDir), a fresh temporary directory (wtDir), and the target commit SHA.

The WorktreeAdd Implementation

In internal/git/git.go, the WorktreeAdd function executes the Git command to create a detached worktree:

// WorktreeAdd creates a detached worktree at wtPath checked out to the given SHA.
func WorktreeAdd(ctx context.Context, repoDir, wtPath, sha string) error {
    // `git worktree add --detach` guarantees the worktree is not linked to any branch.
    return Run(ctx, repoDir, "worktree", "add", "--detach", wtPath, sha)
}

The --detach flag ensures the worktree operates in a detached HEAD state, making it read-only for the pipeline and preventing any branch-based operations from affecting the main repository.

Pipeline Execution Against Worktrees

Once the worktree is established, pipeline steps execute against the worktree path exclusively. All step implementations receive a gitRoot parameter pointing to the worktree location, ensuring that commands like git diff, git ls-files, or git checkout only affect the isolated copy.

The integration pattern in internal/daemon/manager.go follows this structure:

// internal/daemon/manager.go (excerpt)
gateDir := filepath.Join(tmpRoot, "gate")
wtDir   := filepath.Join(tmpRoot, "wt")
if err := git.WorktreeAdd(ctx, gateDir, wtDir, headSHA); err != nil {
    return err
}
defer git.WorktreeRemove(ctx, gateDir, wtDir)  // clean up afterwards

This approach allows the pipeline to perform destructive or modifying operations safely, as the worktree exists solely for the duration of the execution.

Automatic Cleanup and Resource Management

Resource leakage prevention is handled through the WorktreeRemove function in internal/git/git.go. This utility executes git worktree remove --force followed by directory deletion:

// WorktreeRemove force-removes the worktree and deletes the directory.
func WorktreeRemove(ctx context.Context, repoDir, wtPath string) error {
    // The `--force` flag works even if the worktree has uncommitted changes.
    if err := Run(ctx, repoDir, "worktree", "remove", "--force", wtPath); err != nil {
        return err
    }
    return os.RemoveAll(wtPath)
}

The function is typically invoked via defer immediately after creation, ensuring that even if pipeline steps panic or return errors, the cleanup routine executes and frees disk space.

Safety Guarantees and Isolation

The disposable worktree architecture provides multiple safety layers:

• Bare repository origin: Worktrees are created from the bare repository (.git data only), meaning the daemon never mutates the user's working tree
• Detached state: The worktree is always detached, preventing inadvertent pushes to remote branches
• Immediate removal: Errors in any step trigger immediate worktree removal through deferred cleanup
• Filesystem isolation: All Git operations are constrained to the temporary directory, protecting the host environment

Summary

• no-mistakes uses disposable Git worktrees to create isolated, temporary execution environments for CI pipelines
• The WorktreeAdd function in internal/git/git.go creates detached worktrees using git worktree add --detach
• Pipeline steps operate exclusively within the worktree directory, receiving the path via the gitRoot parameter
• WorktreeRemove ensures automatic cleanup via git worktree remove --force and directory deletion
• This architecture guarantees that the main repository remains untouched while providing a clean slate for each pipeline run

Frequently Asked Questions

What is a Git worktree and why use it for CI pipelines?

A Git worktree is a linked working directory that allows multiple branches or commits to be checked out simultaneously while sharing the same repository database. For CI pipelines, worktrees provide lightweight isolation without the overhead of full repository clones, enabling rapid creation and destruction of clean execution environments.

How does no-mistakes ensure the main repository stays clean?

The system creates worktrees from a bare repository copy (not the user's working directory) using the --detach flag, which places the worktree in a detached HEAD state. This ensures all Git operations occur in a temporary directory that is physically separate from the main working tree and automatically deleted after execution.

What happens if a pipeline step fails in no-mistakes?

Error handling triggers the deferred git.WorktreeRemove call immediately, executing git worktree remove --force followed by os.RemoveAll. This ensures that failed pipelines do not leave orphaned worktrees consuming disk space, regardless of whether the failure occurs during linting, testing, or build phases.

Can multiple pipelines run simultaneously using this approach?

Yes, because each pipeline invocation creates a unique temporary directory (typically using os.MkdirTemp with a pattern like "nm-wt-*"), multiple worktrees can exist concurrently without conflict. Each worktree maintains its own working directory while sharing the underlying Git object database from the bare repository.

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