Documentation

Learn how to use the Git Bisect Tool to find and fix bugs in your codebase.

Overview

The Git Bisect Tool helps you identify the exact commit that introduced a bug by automatically testing commits in your git history using binary search. Instead of manually checking each commit, the tool guides you through the process and can even generate fixes automatically.

Start Git Bisect

1. Set Up Your Repository

Click "Start Bisect" and enter either a GitHub or GitLab repository URL, or a local file path to your repository.

2. Identify Good and Bad Commits

You need to know two commits:

  • Bad commit: A commit where the bug exists (usually the latest commit or HEAD)
  • Good commit: A commit where the bug doesn't exist (an older commit)

Commit hashes can be found in your git log or on GitHub/GitLab.

3. Test Commits

The tool will show you a commit to test:

  1. Click "Launch App" to run your app at that commit
  2. Test if the bug is present
  3. Click "Mark as Good" if the bug is NOT there
  4. Click "Mark as Bad" if the bug IS there

The tool automatically picks the next commit to test. Repeat until it finds the bug.

4. Fix the Bug

Once the bug-introducing commit is found, you can use AI to automatically generate a fix and create a pull request.

AI Features

Smart Commit Analysis

Before manually testing commits, let AI analyze all the commits and tell you which ones are most likely to have caused the bug.

How it works:

  1. Describe the bug (what's broken, error messages, etc.)
  2. Enter your good and bad commit hashes
  3. Click "Analyze Commits with AI"
  4. Review results sorted by likelihood
  5. Use the results to narrow down your search faster

Automatic Fix Generation

After finding the bug-introducing commit, the AI can automatically create a fix and open a pull request.

How it works:

  1. After bisect finds the bug, click "Create Fix"
  2. Describe the issue (or use the same description from analysis)
  3. The AI analyzes the buggy commit and generates a fix
  4. A new branch is created with the fix
  5. If configured, a pull request is created automatically

You can always review and modify the fix before merging.

Testing Your App

When the tool shows you a commit to test, you need to run your app at that commit and check if the bug is present.

Launch App

Click the "Launch App" button and the tool will:

  • Install dependencies for that commit
  • Start your development server
  • Open your app in a new browser tab

The tool automatically detects if you use npm, yarn, or pnpm.

Environment Variables

If your app needs environment variables (like API keys or database URLs), you can configure them:

  • Click "Environment Variables (Optional)" to expand
  • Enter one variable per line: KEY=value
  • Variables are saved per repository and reused for all launches

Best Practices

  • Use AI Analysis First: Before manually testing commits, try the AI analysis feature to narrow down the search faster.
  • Be Specific with Issue Descriptions: The more details you provide about the bug, the better the AI can help you find and fix it.
  • Test Thoroughly: Make sure you actually test each commit before marking it as good or bad. The tool is only as accurate as your testing.
  • Review AI-Generated Fixes: Always review the fix the AI creates before merging. It's usually good, but you know your codebase best.

Troubleshooting

App Won't Launch

Try these steps:

  • Make sure your package.json has a "dev" script
  • Check the server console for error messages
  • Try running the dev command manually in your repo

AI Features Not Working

Make sure you:

  • Added OPENAI_API_KEY to .env.local
  • Restarted your dev server after adding the key
  • Have credits in your OpenAI account

Can't Find Repository

Check that:

  • The repository URL is correct
  • You have access to private repositories
  • Local paths are absolute (start with /)