Introduction

This Git warning means Git tried to remove or replace a working-tree file during checkout, but the operating system refused. The problem is not really with git checkout itself. It is almost always a file permission, ownership, lock, or external-process issue. Git needs to unlink the old file before writing the version from the target branch, and the OS said no.

What "Unable To Unlink" Means

When Git checks out another branch, it may need to:

• delete files that should not exist on the target branch
• overwrite files with the target branch's version
• replace tracked content with different content

To do that, Git asks the operating system to unlink, or remove, the existing file. If the OS reports permission denied, Git cannot continue cleanly.

That usually points to one of these causes:

• the file is read-only or owned by another user
• another process has the file open or locked
• antivirus, indexing, or sync software is interfering
• directory permissions do not allow modification

First Check What Is Holding The File

On macOS or Linux, inspect permissions and open handles:

ls -l path/to/file
lsof path/to/file

If lsof shows an editor, watcher, or another tool holding the file, close that process and retry the checkout.

On Windows, the equivalent issue is often:

• a locked file in an editor or IDE
• a read-only attribute
• antivirus or sync software such as OneDrive

The root problem is the same even if the tools differ.

Fix Permissions Or Ownership

If the file is owned by the wrong user or the directory is not writable, correct that before retrying.

Example on Unix-like systems:

chmod u+w path/to/file

If ownership is wrong:

sudo chown "$USER" path/to/file

You may also need to fix the containing directory, not just the file itself, because Git needs permission to modify directory entries too.

Watch For Generated Files And Tools

This warning often appears in repositories that contain generated artifacts, build outputs, or files manipulated by external tooling. Typical examples include:

• IDE-generated files
• Docker bind-mounted outputs
• files created by a different user or container
• watcher processes continuously rewriting files

If a container or root-owned build step generated the file, Git may no longer have permission to replace it from your normal shell user.

Protect Your Local Changes First

If you also have local modifications, do not start randomly deleting things. First inspect the state:

git status

If the changes matter, stash or commit them before solving the permission issue.

git stash

Then fix the file permission or lock problem and retry the checkout.

The warning is about file access, but careless cleanup can still lose local work.

A Practical Recovery Flow

A safe sequence is usually:

1. run git status
2. close editors or processes using the file
3. inspect permissions with ls -l
4. fix ownership or write permission if needed
5. retry git checkout

Only after those checks should you consider more aggressive cleanup.

Platform-Specific Notes

On Windows, file locking is stricter and more visible. Even a preview pane, search indexer, or virus scanner can hold a file long enough to cause checkout failures.

On macOS and Linux, the more common causes are:

• wrong ownership after sudo or container activity
• directory write permission problems
• editor or watcher processes with unexpected locks

The warning text is similar, but the dominant cause often differs by platform.

Avoid Causing The Problem Again

A few habits reduce recurrence:

• do not run build steps as root inside your working tree unless you really mean to
• keep build outputs out of tracked source paths when possible
• avoid checking in generated files that external tools rewrite constantly
• configure sync or antivirus exclusions if a repository is being scanned aggressively

That turns this from a recurring workflow interruption into a rare repair task.

Common Pitfalls

• Retrying git checkout repeatedly without checking who owns or locks the file.
• Using sudo git checkout, which can create even worse ownership problems later.
• Deleting files blindly before confirming whether local changes need to be saved.
• Fixing the file permission but ignoring that the directory permission is the actual problem.
• Forgetting about editors, IDEs, sync tools, or containers that keep rewriting the same path.

Summary

• Git shows this warning when the OS refuses to remove or replace a file during checkout.
• The real causes are usually permissions, ownership, or file locks.
• Check git status, open handles, and file permissions before doing anything destructive.
• Fix the underlying OS-level access problem, then retry the checkout.
• Avoid running build or generation steps as the wrong user inside the repository.