Aider Git Commit Error: Fix Worktree and Detached HEAD Issues

April 18, 2026 · Editorial Team · 6 min read · aider troubleshooting error-fix

Aider is one of those tools that works beautifully in a clean repo on the main branch, and then starts throwing confusing errors the moment you use any of Git's more advanced features. The commit error in a worktree or detached HEAD state is particularly disorienting because it happens after Aider has already made edits to your files. You've got the right changes written to disk, and then the commit step fails with something like fatal: not a git repository or error: failed to commit because head is detached. Your changes are there, the commit isn't, and now Aider's internal state about what it has and hasn't committed is out of sync.

What this error actually means

Aider manages its own git workflow. When it makes changes to files, it expects to immediately commit them using the git repository it detected at startup. In a standard worktree, the .git entry in the worktree directory is a file (not a directory) that contains a pointer back to the main repository's git dir. Older versions of Aider's git library, particularly versions of gitpython below 3.1.42, don't always handle this correctly and treat the worktree as "not a git repository."

In a detached HEAD state, git doesn't have a branch to commit to. Aider's default commit logic creates a regular commit on whatever branch is checked out. When HEAD is detached, there's no branch, so the commit either fails with an error or succeeds but immediately becomes unreachable the moment you switch away, which Aider doesn't handle gracefully.

Quick fix (when you need it working in 60 seconds)

Check your git state first:
```
git status
git branch
```
If git branch shows * (HEAD detached at abc1234), you're in a detached HEAD. If it shows a branch name but you're in a worktree, look for * [worktree: ../other-dir] output.
For detached HEAD: create a branch before running Aider:
```
git checkout -b fix/my-feature
```
For worktree issues: run Aider from the main repository root, not from the worktree path.
If you already have Aider's uncommitted changes on disk, commit them manually:
```
git add -A && git commit -m "aider: manual commit after worktree error"
```

Why this happens

Worktrees were added to Git specifically to allow multiple checked-out branches from one repository without cloning. They're excellent for working on a hotfix while your main feature branch stays intact. Aider started supporting worktrees properly in version 0.35, but there are still edge cases in the path detection logic.

The most common failure in a worktree happens because Aider tries to find the git directory by looking for .git/ as a directory. In a worktree, .git is a file containing the path to the actual git directory. Aider's git library then needs to parse that file and follow the reference, which requires the file to be correctly formatted and the referenced path to exist. If you created the worktree with a non-standard path or moved directories around after creating it, the reference can break silently.

Detached HEAD state happens in a few common scenarios: checking out a specific tag (git checkout v2.3.1), pulling a CI pipeline's commit reference directly, or using git bisect. When Aider encounters HEAD detached, its commit function calls repo.index.commit(message) via gitpython, which works but creates a commit with no branch reference. The next thing Aider does is try to get the current branch name for its internal tracking, which fails. That failure cascades into the error you see.

There's also a race condition in Aider's file watching. When it writes changes and then immediately tries to commit, if another process (like a file watcher or your editor) has the file open for writing, gitpython can't create a clean commit. This shows up as error: Entry ... not uptodate. Cannot merge. or similar.

The --no-git flag is sometimes suggested as a fix but it disables all git integration, meaning Aider won't track changes at all. That's not a real solution for most workflows.

Permanent fix

Update Aider to 0.53+ and gitpython to 3.1.43+:
```
pip install --upgrade aider-chat
pip install --upgrade gitpython
```
These versions have the worktree detection fixes.
When using worktrees, always launch Aider with the explicit --git-root flag pointing to your main repo:
```
aider --git-root /path/to/main-repo --model gpt-4o src/myfile.ts
```

For detached HEAD workflows (like bisect or tag checkout), create a temporary branch first:

git checkout -b temp/aider-session
aider ...
# When done, cherry-pick or squash into your real branch
git checkout main && git cherry-pick temp/aider-session
git branch -d temp/aider-session

Add a pre-session check to your shell or a wrapper script:

#!/bin/bash
# check-git-state.sh
if git rev-parse --abbrev-ref HEAD | grep -q "HEAD"; then
  echo "Warning: detached HEAD. Creating a temp branch."
  git checkout -b temp/aider-$(date +%s)
fi
aider "$@"

If you're in a worktree and can't change the worktree setup, use --no-auto-commit and commit manually after each Aider session:
```
aider --no-auto-commit src/myfile.ts
```
Then commit with standard git commands when you're happy with the result.

Check that your worktree reference is intact:

cat .git  # In a worktree this is a file, not a directory
# Should show: gitdir: /path/to/main-repo/.git/worktrees/name
ls /path/to/main-repo/.git/worktrees/
# Your worktree name should be listed here

If it's not listed, the worktree metadata is broken. Fix it with git worktree repair.

If the worktree metadata is corrupt, remove and recreate:

git worktree remove --force /path/to/worktree
git worktree add /path/to/worktree branch-name

Prevention

Get into the habit of checking your git state before starting an Aider session. A quick git status && git branch takes five seconds and tells you immediately if you're in a state that will cause problems. I have this aliased as gs and I run it automatically before any AI coding session.

If your workflow regularly involves worktrees (for example, working on multiple features simultaneously), configure your worktree structure once and keep it stable. Don't move worktree directories after creation. Git's worktree references use absolute paths, so moving a worktree without running git worktree repair breaks the reference silently.

For CI and automation workflows where Aider runs in detached HEAD state by design, always pass --no-auto-commit and handle commits in your pipeline script. Auto-commit in detached HEAD creates unreachable commits that will eventually be garbage collected.

When the fix doesn't work

If git worktree repair doesn't fix the reference and the worktree commit error persists, the safest path is to copy your changes out, remove the worktree, and recreate it from scratch. Your working files aren't lost but the git metadata needs rebuilding.

For bugs that aren't covered by the worktree repair command, report them at github.com/paul-gauthier/aider. Include your Aider version (aider --version), gitpython version (pip show gitpython), and the exact error output. The maintainer is active and worktree issues tend to get fixes in the next release.

If you're using Aider in a workflow where detached HEAD is unavoidable and the temp-branch workaround is too disruptive, consider using aider --no-auto-commit as a project default via the .aider.conf.yml config file so you don't have to remember to pass the flag.