Introduction

The .idea directory is created by JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, etc.) and contains project-specific settings like code style, run configurations, and workspace layout. Committing it to Git causes merge conflicts, repository bloat, and exposes developer-specific settings. To fix this, remove the directory from Git tracking with git rm --cached -r .idea, add it to .gitignore, and commit the changes. The files remain on your local disk but Git stops tracking them.

Why .idea Should Not Be Committed

The .idea directory contains files like:

• workspace.xml — window layouts, open tabs, breakpoints (unique per developer)
• modules.xml — module structure references
• encodings.xml — file encoding settings
• vcs.xml — version control mappings
• *.iml files — module definitions with local SDK paths

These files change frequently based on individual developer actions (opening a file, resizing a panel, adding a breakpoint), generating noisy diffs and merge conflicts that have nothing to do with the actual code.

Step 1: Remove .idea from Git Tracking

1# Remove .idea from Git index (keeps files on disk)
2git rm --cached -r .idea
3
4# Also remove .iml files if they were committed
5git rm --cached -r "*.iml"
6
7# Verify — files should show as "deleted" in staging
8git status
9# deleted:   .idea/workspace.xml
10# deleted:   .idea/modules.xml
11# deleted:   .idea/vcs.xml
12# ...

git rm --cached removes the files from the Git index (staging area) without deleting them from your filesystem. The -r flag handles directories recursively.

Step 2: Add .idea to .gitignore

1# Add to .gitignore
2echo ".idea/" >> .gitignore
3echo "*.iml" >> .gitignore
4
5# Or edit .gitignore to include:
6# .idea/
7# *.iml

1# .gitignore — JetBrains IDEs
2.idea/
3*.iml
4out/
5
6# Other common IDE directories
7.vscode/
8*.swp
9.DS_Store

The trailing / in .idea/ tells Git this is a directory pattern. Without the .gitignore entry, git add . would re-add the files.

Step 3: Commit the Changes

1# Stage the .gitignore and the removals
2git add .gitignore
3git commit -m "Remove .idea directory and add to .gitignore"
4
5# Push to remote
6git push

After this commit, Git no longer tracks .idea. Other developers who pull this change will see the .idea files removed from Git, but their local .idea directory (generated by their IDE) is unaffected.

Remove .idea from Entire Git History

1# If .idea contains sensitive data or you want to reduce repo size,
2# remove it from all historical commits
3
4# Using git filter-branch (older method)
5git filter-branch --force --index-filter \
6  'git rm --cached --ignore-unmatch -r .idea' \
7  --prune-empty -- --all
8
9# Using git-filter-repo (recommended, faster)
10# Install: pip install git-filter-repo
11git filter-repo --path .idea --invert-paths
12
13# After rewriting history, force push
14git push --force --all
15git push --force --tags

Rewriting history is a destructive operation that changes commit hashes. Only do this if the .idea directory contains secrets or the repository is very new. Coordinate with your team before force-pushing.

Set Up a Global .gitignore

1# Create a global gitignore that applies to ALL repositories
2git config --global core.excludesfile ~/.gitignore_global
3
4# Add common IDE files to the global ignore
5cat >> ~/.gitignore_global << 'EOF'
6# JetBrains
7.idea/
8*.iml
9out/
10
11# VS Code
12.vscode/
13*.code-workspace
14
15# macOS
16.DS_Store
17._*
18
19# Windows
20Thumbs.db
21desktop.ini
22
23# Vim/Emacs
24*.swp
25*~
26\#*\#
27EOF

A global .gitignore prevents IDE-specific files from being committed to any repository, without requiring each project to include IDE patterns in its own .gitignore.

Preventing Future Accidents

1# Pre-commit hook to block .idea commits
2# .git/hooks/pre-commit (make executable with chmod +x)
3#!/bin/sh
4
5if git diff --cached --name-only | grep -q "^\.idea/"; then
6    echo "ERROR: Attempting to commit .idea directory files."
7    echo "Run: git reset HEAD .idea"
8    exit 1
9fi

1# Use git check-ignore to verify .gitignore works
2git check-ignore -v .idea/workspace.xml
3# .gitignore:1:.idea/    .idea/workspace.xml
4
5# If a file is already tracked, .gitignore has no effect
6# You must git rm --cached first

Which .idea Files to Share (Optional)

1# Some teams share certain .idea files for consistent project setup
2# In .gitignore, ignore everything except specific files:
3
4.idea/*
5!.idea/codeStyles/
6!.idea/inspectionProfiles/
7!.idea/runConfigurations/
8!.idea/copyright/
9
10# Never share:
11# workspace.xml — personal layout
12# tasks.xml — personal task tracking
13# usage.statistics.xml — telemetry
14# shelf/ — personal shelved changes

JetBrains recommends sharing code style settings, inspection profiles, and run configurations if your team uses the same IDE. But workspace.xml and similar personal files should never be committed.

Common Pitfalls

• Adding .idea/ to .gitignore without git rm --cached: .gitignore only affects untracked files. If .idea is already tracked, adding it to .gitignore does nothing — Git continues tracking changes. You must run git rm --cached -r .idea first to untrack it.
• Using git rm without --cached: git rm -r .idea (without --cached) deletes the files from both Git and your filesystem. Your IDE will regenerate them, but you lose any custom run configurations or code style settings.
• Forgetting *.iml files: .iml files are module definitions that contain local SDK paths. They live alongside your source code (not inside .idea/) and are easily missed. Add *.iml to .gitignore alongside .idea/.
• Force-pushing history rewrites without team coordination: Using git filter-branch or git filter-repo rewrites commit hashes. Other developers must re-clone or carefully rebase their work. Never force-push without notifying your team.
• Not setting up a global gitignore: Relying on each repository's .gitignore to exclude IDE files means every new project starts without protection. Set up core.excludesfile once and IDE files are ignored globally across all repositories.

Summary

• Remove .idea from Git tracking with git rm --cached -r .idea (keeps local files)
• Add .idea/ and *.iml to .gitignore to prevent re-adding
• Commit both changes in a single commit
• Set up a global .gitignore (core.excludesfile) to protect all repositories
• Use git filter-repo if you need to remove .idea from the entire history
• Optionally share specific .idea subdirectories (codeStyles, runConfigurations) while ignoring personal settings