Understanding `safe.bareRepository` Mode and Its Impact on Git Operations

When safe.bareRepository is set to explicit, Git refuses to automatically discover bare repositories through the current working directory, requiring explicit --git-dir flags for all operations targeting bare repos.

The no-mistakes project runs pipeline steps inside a gate repository—a bare Git repository that receives pushes from the user’s working tree. In hardened CI and agent environments where safe.bareRepository=explicit is enforced, standard Git commands fail unless explicitly told where the repository lives. The project handles this constraint through a specialized wrapper in internal/git/git.go that automatically injects --git-dir when operating on bare repositories, ensuring compatibility with security-hardened environments.

What is safe.bareRepository?

safe.bareRepository is a Git configuration variable that controls how Git discovers bare repositories. When set to explicit, Git disallows automatic discovery of a bare repository through the current working directory (cwd). This means any Git command that would normally rely on the process’s cwd (or the -C flag) to locate a .git directory must instead be given the repository path explicitly via the --git-dir flag.

According to the no-mistakes source code documentation in AGENTS.md and docs/src/content/docs/concepts/gate-model.md, this setting is common in hardened CI systems, agent harnesses, and the Claude Code harness to prevent accidental operations on untrusted repositories.

The Gate Repository Architecture

no-mistakes utilizes a gate repository—a bare Git repository that acts as a controlled entry point for code changes. Because the gate is a bare repo (lacking a working tree), standard Git commands executed from within its directory structure will fail under safe.bareRepository=explicit without proper handling.

The project implements a deterministic repository layout by intercepting all Git calls through a central wrapper, avoiding cwd-based discovery pitfalls that would otherwise cause fatal errors such as "fatal: cannot use bare repository without specifying --git-dir".

Automatic --git-dir Injection in internal/git

All Git operations in no-mistakes that touch the gate repository route through internal/git/git.go, specifically the Run function. This wrapper enforces the --git-dir requirement automatically:

1. Detection: Run checks whether the supplied directory is a bare Git repository using isBareGitDir.
2. Injection: If the target is bare, the arguments are prefixed with --git-dir=<dir> before invoking the git binary.
3. Execution: The command runs with explicit repository context, bypassing cwd-based discovery.

This guarantees that the tool works correctly even when the environment forces safe.bareRepository=explicit.

Detecting Bare Repositories

Before issuing commands, the system validates the repository type:

// Detecting a bare repository before issuing a command.
if git.IsBareGitDir(gatePath) {
    // Custom logic if needed; otherwise just call Run().
    fmt.Println("Running against a bare repo")
}

The IsBareGitDir function inspects the directory structure to determine if it represents a bare Git repository, allowing the wrapper to decide whether to apply --git-dir prefixes.

Impact on Specific Git Operations

The safe.bareRepository=explicit setting fundamentally changes how common Git commands behave when targeting bare repositories:

• git rev-parse --show-toplevel: Under normal discovery, Git uses cwd to locate the repo root. With explicit, this is refused—Git will not search upward. no-mistakes handles this via FindGitRoot, which invokes Git directly with an explicit directory.

• git remote add: Normally runs in the repo’s working tree. With explicit, it is refused if cwd points to a bare repo. The AddRemote function routes through Run, which adds --git-dir when isBareGitDir is true.

• git push: Implicit cwd-based pushes from the gate repo are disallowed. The Push implementation (via Run) explicitly names the bare repo using --git-dir.

• Daemon operations: Any git sub-command executed by the daemon (e.g., init, fetch, checkout) that relies on cwd may fail with an "unsafe repository" error. The Run wrapper automatically prefixes --git-dir for bare directories to prevent this.

Practical Implementation Examples

When working with the no-mistakes codebase, you interact with bare repositories through the abstracted git package:

// Example: Running a Git command on a gate (bare) repository.
ctx := context.Background()
gatePath := "/path/to/gate-repo" // a bare repository

// `Run` will detect the bare repo and prepend `--git-dir`.
out, err := git.Run(ctx, gatePath, "rev-parse", "--git-dir")
if err != nil {
    log.Fatalf("git failed: %v", err)
}
fmt.Println("Git dir:", out) // prints the absolute path of the bare repo

Adding remotes requires no manual flag management:

// Adding a remote to the gate repo – no need to manually add `--git-dir`.
func addRemote(ctx context.Context, repoPath, name, url string) error {
    return git.AddRemote(ctx, repoPath, name, url) // internally uses Run
}

Summary

• safe.bareRepository=explicit prevents Git from discovering bare repositories through the current working directory, requiring explicit --git-dir flags.
• no-mistakes operates on gate repositories (bare repos) and uses a centralized wrapper in internal/git/git.go to handle this constraint.
• The Run function automatically detects bare repositories via IsBareGitDir and prefixes commands with --git-dir=<path>.
• This abstraction supports hardened CI environments and agent harnesses that enforce safe.bareRepository=explicit for security (see issue #362).
• Manual Git commands on bare repositories without --git-dir will fail with "fatal: cannot use bare repository without specifying --git-dir".

Frequently Asked Questions

What error does Git throw when safe.bareRepository=explicit is set but --git-dir is missing?

Git aborts with the error: "fatal: cannot use bare repository without specifying --git-dir". This occurs because Git refuses to infer the repository location from the current working directory when operating in explicit safety mode.

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

The system uses the IsBareGitDir function defined in internal/git/git.go to inspect the directory structure. When Run is called, it checks this condition and automatically prefixes --git-dir=<dir> to the Git arguments if the target is bare, ensuring commands execute correctly regardless of the safe.bareRepository setting.

Why do CI environments set safe.bareRepository to explicit?

Hardened CI and agent environments set this variable to prevent accidental operations on untrusted bare repositories that might be present in the file system. It forces explicit repository declaration via --git-dir, eliminating ambiguity about which repository Git should operate on and preventing potential security issues (as documented in AGENTS.md).

Does this affect normal (non-bare) repositories?

No. The safe.bareRepository=explicit setting only impacts the discovery of bare repositories. Regular repositories with working trees are still discovered through standard .git directory traversal. However, no-mistakes applies the --git-dir pattern universally for bare repos while maintaining normal behavior for standard repositories.

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