Sharing IntelliJ IDEA Project Files in Version Control

There are quite a few benefits to having IDE project files properly stored under version control:

• most people want to use an IDE and will need to configure the project somehow
• a shared environment reduces costs within a corporate workplace
• a VCed project means that the project file branches with your codebase. Need to work on an old branch? No problem, the project file already exists.
• casual contributors will have an easier time making patches for your project
• an IDE can provide checkstyle and coding standards to your code
  

And when the files are stored improperly in version control, you create a nice changelist headache for yourself and turn away the casual contributor.

Here are three simple rules on how to properly share an IntelliJ IDEA project file in version control:

Rule #1 - Check-in the .ipr and .iml files
Rule #2 - Set an ignore flag for the .iws file (your workspace file). All proper VCSs allow you to do this.
Rule #3 - Make IDEA Project Variables for all the variables that vary (it's kinda the definition of variable, you know). Some common variables you'll probably need are "Tomcat Home", "Groovy Home", and "JDK Version".

Creating variables is really easy. Open the .ipr/.iml in a text editor and scan for hardcoded paths or values. When you find one just replace it with $variable_name$. Now when IDEA starts, it prompts you for those variables if they are not defined. These are IDEA variable stored in your HOME directory; they have nothing to do with your operating system environment variables. Here's what a prompt looks like:

See that red dialog? Clicking it opens a screen where you can add values to the variables:


Adding a value should be pretty self-explanatory.

The Gotchas - There are a few gotcha's to be aware of...

Using multiple versions of IDEA is not well supported. Most new versions, even minor releases, try to write some extra info to the project files. Not a problem in the corporate world, but more so in the OS one. You might try checking in a backup copy when the project lead upgrade.

Making the JDK Name variable can be somewhat confusing, as it is not a path on your disk. IDEA keeps track globally (for all projects) of your installed JDKs, and each one is given a name. It is easy to find the place in the .ipr where this is specified, but it is not easy to explain to users what their's should be set to. It needs to be the name of an entry from your SDKs in Settings:

Also, changing the inspection profiles can modify the project. The inspections are the codestyle to the project, so it may make sense to have them baked into the .ipr. However, this is an optional place to put them. An inspection profile can be shared or not. If it is shared then it is written to the .ipr, otherwise it is an external file. The Settings screen should be self-explanatory once you understand the Shared checkbox.


Lastly, adding words to the spell checker will add the word to the .ipr file, with a key of your username. I opened a bug for this, as I feel a user's name should never go in the project file, but the JetBrains guys feel that this is OK considering that switching to the ".idea" alternate project layout will separate the files out and avoid the issue. For now, I guess the best advice is to spell words correctly and, if you're not a committer, live with the fact that your project file may be checked out because of this issue.

Is all this worth it? I recently opened the GPars project files, defined an SDK and a Groovy 1.6.7 library, and ran the tests successfully. For me, it was great.

Rule #4 - Profit!