fix: Add git worktree support for Docker environments

[philkuz]

Fixes #6455

Proposed Changes

This PR adds support for git worktrees when running MegaLinter in Docker containers. Previously, MegaLinter would crash when running in a worktree because the git fetch operation would fail due to invalid paths inside the container.

1. Add _is_git_worktree() method to detect when running in a git worktree environment
2. Wrap git fetch operation in try-catch to handle GitCommandError gracefully
3. Provide informative warning messages specific to worktree scenarios
4. Update exception handling to catch both InvalidGitRepositoryError and GitCommandError
5. Add comprehensive unit tests for worktree detection and error handling

Technical Details

The Problem:
In a git worktree, the .git directory is replaced with a .git file containing a path like:

gitdir: /home/user/repo/.git/worktrees/worktree-name

When the worktree is mounted in Docker, this absolute host path becomes invalid inside the container, causing git fetch to fail with:

fatal: not a git repository: /home/user/repo/.git/worktrees/worktree-name

The Solution:

• Detect worktrees by checking if .git is a file (not a directory) or if the git directory path contains 'worktrees'
• Catch GitCommandError during fetch operations and log appropriate warnings
• Continue with linting using available refs instead of crashing
• Falls back to scanning all files if git operations fail completely

Testing

Added comprehensive unit tests in megalinter/tests/test_megalinter/worktree_test.py:

• ✅ Worktree detection for regular repos (should return False)
• ✅ Worktree detection via .git file (should return True)
• ✅ Worktree detection via path containing 'worktrees' (should return True)
• ✅ Git fetch error handling in worktrees (should catch and continue)
• ✅ Exception handling in detection logic (should not crash)

Impact

• ✅ Enables MegaLinter to work with git worktrees in Docker
• ✅ Supports modern coding agent workflows (Cursor, Claude Code)
• ✅ Backward compatible - no breaking changes
• ✅ No new dependencies required
• ✅ Clear user feedback with actionable warnings

Readiness Checklist

Author/Contributor

• Add entry to the CHANGELOG listing the change and linking to the corresponding issue
• If documentation is needed for this change, has that been included in this pull request (documentation can be added in a follow-up if needed)

Reviewing Maintainer

• Label as breaking if this is a large fundamental change
• Label as either automation, bug, documentation, enhancement, infrastructure, or performance

---

Note

Adds git worktree detection and handles GitCommandError during fetch to keep diff-based file listing working, plus unit tests.

• Core (megalinter/MegaLinter.py):
  • Add _is_git_worktree to detect worktree environments.
  • Enhance list_files_git_diff:
    • Detect worktrees and log context-specific warnings.
    • Wrap git fetch in try/except git.exc.GitCommandError and continue without fetch.
  • Broaden exception handling in collect_files to catch git.exc.GitCommandError when diffing.
• Tests:
  • Add megalinter/tests/test_megalinter/worktree_test.py with unit tests for worktree detection, fetch error handling, and exception safety.

^{Written by Cursor Bugbot for commit 4d5935a. This will update automatically on new commits. Configure here.}

[echoix]

I'm surprised the git library doesn't have a way to check it for us. Is the bugbot review comment relevant?

I don't really mind that this seems like a AI report, it is very clear, we just need us humans to think about if the way it is done is correct ;)

[philkuz]

I'm surprised the git library doesn't have a way to check it for us. Is the bugbot review comment relevant?

I don't really mind that this seems like a AI report, it is very clear, we just need us humans to think about if the way it is done is correct ;)

I'll remove that, it must have snuck in while I was pushing this PR.

I poked around the git python library a month or so back and didn't find a worktree feature, but can do a quick check.

Separately, what do you think about try/except around git fetch? Are you ok with this change of functionality in the non worktree (default) case?

[philkuz]

The other work-around I've used is to call the docker command directly and mount the absolute path of the original repo at the same absolute path in the container.

However, that's kinda bug prone if a container happens to rely on a path that matches the absolute path.

Let me see if gitpython lets you override the worktree pointer with an env var, that way we can mount the main repo in a well known location and point to it.

[echoix]

I poked around the git python library a month or so back and didn't find a worktree feature, but can do a quick check.

I looked in the code what they had, and something was close. But I saw in their issues a comment that shows a small change that makes it check for work trees.

gitpython-developers/GitPython#719 (comment)

Vs

https://github.com/gitpython-developers/GitPython/blob/271328f01a3725f51415d209bc5d0c0fdb777338/git/repo/fun.py#L57-L77

Separately, what do you think about try/except around git fetch? Are you ok with this change of functionality in the non worktree (default) case?

I reread this and it's very fine, either way explanations in the logs.