Committing .idea directory

I never bothered committing .idea files before. Actually, I very much preferred treating it as a scary black box full of XML gibberish that I’d rather not touch.

It was fine back in the days when I had a stable set of projects, each configured once in PyCharm, and that was it. Adopting git worktrees changed my workflow: every worktree is a new directory, and PyCharm treats it as a new project that needs to be configured from scratch. So I decided to finally look inside and see what can be committed.

Turns out, the directory splits into shareable and local files. The shareable ones use $PROJECT_DIR$ and $MODULE_DIR$ variables, making them portable:

• modules.xml is the entrypoint, listing which .iml files to load
• The .iml file is the main module config: Django project configuration, source roots, test runner settings
• codeStyles/ and inspectionProfiles/ for code style and inspection settings
• IDE’s own and plugin-specific configs like vcs.xml, prettier.xml, GitLink.xml, misc.xml. All of them seem to be portable.

PyCharm generates a sensible .idea/.gitignore out of the box, excluding local state. I found it safe to rely on as-is.

SDK reference

The SDK reference in misc.xml and the .iml is something that breaks the portability. In misc.xml it looks like this:

<component name="ProjectRootManager" version="2"
    project-jdk-name="Python 3.14 (my-project)"
    project-jdk-type="Python SDK" />

The “Python 3.14 (my-project)” name here is a lookup key into a global SDK table at ~/Library/Application Support/JetBrains/PyCharm*/options/jdk.table.xml, where it resolves to a hardcoded path like <project-root>/.venv/bin/python. The same named reference appears in the .iml file as jdkName.

I know that PyCharm treats Python environments with a lot of ceremony involving parsing and indexing. Apparently, they can’t just be picked up on the fly from a new worktree’s .venv (maybe I am wrong, though). I decided to let all worktrees share the main virtualenv managed by uv, which is good enough since I rarely diverge dependencies across branches.