How the no-mistakes Bare Repository Safety Feature Works with safe.bareRepository=explicit

The no-mistakes tool prevents gate operation failures in hardened CI environments by automatically prepending --git-dir to Git commands when operating on bare repositories, bypassing the safe.bareRepository=explicit restriction that blocks cwd-based discovery.

The no-mistakes repository provides hardened Git automation designed for agent harnesses and CI pipelines. When security configurations enable safe.bareRepository=explicit, Git refuses to automatically discover bare repositories from the current working directory, causing standard gate operations to fail. The codebase solves this through explicit bare repository detection in internal/git/git.go and centralized command execution via the git.Run helper.

Understanding the safe.bareRepository=explicit Restriction

Git's safe.bareRepository=explicit configuration is a security feature that prevents accidental operations on bare repositories by forbidding automatic discovery via the process's working directory. When this setting is injected by agent harnesses like Claude Code or hardened CI environments, any Git command relying on cmd.Dir or the -C flag to locate a repository will fail with a safety error. This behavior breaks pipelines that attempt to execute Git commands while positioned inside a bare gate repository, as documented in issue #362.

Bare Repository Detection in internal/git/git.go

The no-mistakes codebase implements robust bare repository detection to identify when explicit path handling is required. The helper function isBareGitDir implements Git's own heuristic to distinguish bare repositories from standard working trees.

The Detection Logic

Located at lines 55-71 in internal/git/git.go, the detection logic verifies three conditions:

func isBareGitDir(dir string) bool {
    if dir == "" { return false }
    if _, err := os.Stat(filepath.Join(dir, ".git")); err == nil { return false }
    if fi, err := os.Stat(filepath.Join(dir, "HEAD")); err != nil || fi.IsDir() { return false }
    fi, err := os.Stat(filepath.Join(dir, "objects"))
    return err == nil && fi.IsDir()
}

This function identifies a bare repository when the directory contains a HEAD file and an objects subdirectory, but no .git folder. This matches Git's internal structure for bare repositories.

The git.Run Helper and Explicit --git-dir Injection

All gate-related Git interactions route through the git.Run function in internal/git/git.go, which automatically handles the safe.bareRepository=explicit compatibility layer.

Automatic Flag Prepending

When git.Run detects a bare repository, it prepends --git-dir=<path> to the argument slice before execution:

// internal/git/git.go (lines 31-40)
func Run(ctx context.Context, dir string, args ...string) (string, error) {
    if isBareGitDir(dir) {
        args = append([]string{"--git-dir=" + dir}, args...)
    }
    // ... execution continues
}

This explicit path declaration tells Git exactly where the repository resides, eliminating the need for cwd-based discovery and rendering the safe.bareRepository restriction irrelevant for these operations.

Practical Implementation Examples

The following patterns demonstrate safe Git operations on bare gate repositories under safe.bareRepository=explicit:

Verifying a Bare Repository

ctx := context.Background()
gateDir := "/path/to/bare/gate" // a bare repository
out, err := git.Run(ctx, gateDir, "rev-parse", "--is-bare-repository")
// Run automatically adds "--git-dir=/path/to/bare/gate"
if err != nil {
    log.Fatalf("git error: %v", err)
}
fmt.Println("Result:", out)

Adding Remotes Safely

err := git.AddRemote(ctx, gateDir, "origin", "git@github.com:example/repo.git")
// Internally uses Run, which adds --git-dir when needed.

Fetching Branches

err := git.FetchRemoteBranch(ctx, gateDir, "origin", "main")
// The underlying Run call is safe under safe.bareRepository=explicit.

Documentation and Agent Hardening

The implementation is enforced through documentation mandates in AGENTS.md (lines 56-59):

"Agent harnesses and hardened CI inject safe.bareRepository=explicit, which forbids cwd‑based discovery of bare repositories. Route every gate git call through git.Run, which detects a bare git dir and prepends --git-dir=<dir>; never shell out to git in a bare gate repo relying on cmd.Dir or -C discovery (issue #362)."

This policy ensures that developers do not inadvertently bypass the safety mechanism by shelling out directly to Git commands.

Summary

• no-mistakes detects bare repositories using the isBareGitDir function, which checks for HEAD and objects subdirectories while confirming the absence of a .git folder.
• The git.Run helper in internal/git/git.go automatically prepends --git-dir=<path> when operating on detected bare gate repositories.
• This explicit path injection bypasses the safe.bareRepository=explicit restriction that blocks cwd-based repository discovery.
• All gate-side Git interactions must route through git.Run to maintain compatibility with hardened CI environments and agent harnesses.

Frequently Asked Questions

What is safe.bareRepository=explicit and why does it break Git commands?

safe.bareRepository=explicit is a Git configuration setting that forbids the automatic discovery of bare repositories from the current working directory. It breaks commands that rely on cmd.Dir or the -C flag to locate repositories because Git refuses to identify the bare repo context when the working directory is inside or near a bare repository, treating such discovery as a potential security risk.

How does no-mistakes detect if a directory is a bare Git repository?

The isBareGitDir function in internal/git/git.go (lines 55-71) implements Git's standard heuristic by verifying that the directory contains a HEAD file and an objects subdirectory while explicitly confirming that no .git folder exists. This distinguishes bare repositories from standard working trees or non-Git directories.

Can I use standard os/exec to run Git commands in a bare repository with no-mistakes?

No. You must use the git.Run helper which handles the --git-dir injection automatically. Shelling out directly to Git via os/exec while relying on working directory discovery will fail under safe.bareRepository=explicit, potentially breaking the pipeline as noted in issue #362.

Where is the bare repository safety logic documented in no-mistakes?

The design is documented in AGENTS.md at lines 56-59, which mandates that all gate-side Git calls route through git.Run. This documentation specifically references issue #362 and instructs developers to avoid shelling out to Git in bare gate repos relying on cmd.Dir or -C discovery.

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