# How no-mistakes Uses Disposable Git Worktrees for Pipeline Execution

> Learn how no-mistakes uses disposable Git worktrees to isolate pipeline steps. Ensure your main repo stays clean with automatic cleanup after execution for robust CI.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-06-25

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go), the `WorktreeAdd` function executes the Git command to create a detached worktree:

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/daemon/manager.go) follows this structure:

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/git/git.go). This utility executes `git worktree remove --force` followed by directory deletion:

```go
// 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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.