How to Set Up no-mistakes for Fork Contributions on GitHub: A Complete Guide

Initialize your local clone with no-mistakes init --fork-url <your-fork> to route all pushes to your fork while automatically opening pull requests against the upstream repository.

no-mistakes is a Go-based CLI tool that prevents accidental data loss by orchestrating a background daemon, CI pipelines, and intelligent agents. When contributing to open-source projects via a fork, you must configure the tool to distinguish between the upstream repository and your personal fork to ensure branches push to the correct remote and PRs target the proper destination.

Understanding the Fork Routing Architecture

The fork-routing logic documented in AGENTS.md separates your workspace from the upstream project by maintaining two distinct remote URLs. At the core of this system is the Repo.PushURL() method (implemented in internal/git/repo.go), which dynamically selects the appropriate remote during Git operations. When you initialize the repository with a fork URL, the daemon intercepts all push commands and redirects them to your fork while preserving the upstream repository as the PR target.

Step-by-Step Setup for Fork Contributions

1. Initialize the Repository with Your Fork URL

Run the initialization command once per clone to record both the upstream origin and your fork:

no-mistakes init --fork-url https://github.com/<your-username>/no-mistakes.git

The init command parses the --fork-url flag (see the flag handling at lines 36–37 of internal/cli/init.go) and validates that the URL is non-empty, throwing init: --fork-url must not be empty if omitted. This value is persisted in the repository’s configuration file alongside other settings.

2. Verify the Fork Configuration

After initialization, the CLI stores your fork URL in the repository configuration. The daemon reads this value on every subsequent operation to determine remote routing. You do not need to manually configure Git remotes; the tool abstracts this through the Repo.PushURL() abstraction layer.

3. Push Branches to Your Fork

Create your feature branch and push using the axi command:

git checkout -b my-feature
git add .
git commit -m "Add new feature"
no-mistakes axi push

The axi push command invokes Repo.PushURL() to direct the push to your fork URL rather than the upstream origin. This prevents accidental writes to the main repository while ensuring your changes are available on your fork for PR creation.

4. Open Pull Requests Against Upstream

Create the pull request using the dedicated PR command:

no-mistakes axi pr

This command constructs the gh pr create invocation with --head <fork-owner>:<branch> while keeping --repo pointed at the upstream repository. The result is a PR opened against the upstream project that references your fork’s branch as the source, exactly as required by the Fork Routing section of AGENTS.md.

Safety Guarantees and Validation

The fork-routing implementation includes multiple safeguards to prevent accidental pushes to upstream. The code never attempts to push directly to the origin repository when a fork URL is configured. All push operations are mediated by Repo.PushURL(), which abstracts the remote selection logic and prevents force-pushes to the upstream repository. The integration tests in internal/e2e/fork_routing_test.go verify that the init --fork-url configuration correctly routes both pushes and PRs throughout the entire workflow.

Key Implementation Files

File	Purpose
internal/cli/init.go	Parses --fork-url and validates the fork remote configuration (lines 36–37).
internal/git/repo.go	Contains Repo.PushURL() which determines the correct remote for Git push operations.
internal/scm/gitlab/gitlab.go	Implements remote-specific handling logic (GitHub uses similar patterns).
internal/e2e/fork_routing_test.go	Integration tests verifying fork routing and PR creation against upstream.
AGENTS.md	High-level design documentation for the fork routing and safety guarantees.

Summary

• Initialize once with no-mistakes init --fork-url <url> to record your fork destination (validated in internal/cli/init.go).
• Push safely using no-mistakes axi push, which routes branches to your fork via Repo.PushURL().
• Target upstream automatically with no-mistakes axi pr, creating PRs against the origin repository while using your fork as the head.
• Stay protected by the built-in validation that prevents direct pushes to upstream when a fork URL is configured.

Frequently Asked Questions

What happens if I don't specify --fork-url during init?

Without the --fork-url flag, the CLI defaults to treating the origin remote as both the source and target for all operations. This means no-mistakes axi push will attempt to write directly to the upstream repository, which will fail if you lack write permissions or could accidentally modify the main branch if you do have access.

Can I change the fork URL after initialization?

Yes, you can re-run no-mistakes init --fork-url <new-url> to update the configuration. The validation logic in internal/cli/init.go will overwrite the existing fork URL in the repository settings, and subsequent axi commands will immediately route pushes to the new remote without requiring a fresh clone.

How does no-mistakes prevent accidental pushes to upstream?

The tool uses the Repo.PushURL() abstraction (implemented in internal/git/repo.go) to select remotes. When a fork URL is present in the configuration, this method always returns the fork URL for push operations, ensuring the Git commands never target the upstream origin. This is enforced by the daemon and validated through the test suite in internal/e2e/fork_routing_test.go.

Does fork routing work with GitLab or other Git providers?

Yes, the fork routing logic is provider-agnostic. While the examples reference GitHub, the underlying implementation in internal/scm/gitlab/gitlab.go and related packages handles remote URL construction for multiple providers. The --fork-url flag accepts any valid Git URL, and the PR creation logic adapts to the specific SCM provider detected in the repository configuration.

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