Hamlet D'Arcy has been writing software for over a decade, and has spent considerable time coding in C++, Java, and Groovy. He's passionate about learning new languages and different ways to think about problems, and recently he's been discovering the joys of both F# and Scheme. He's an active member of the Groovy Users of Minnesota and the Object Technology User Group, is a committer on the Groovy project, and is a contributor on a few open source projects (including JConch and the IDEA Groovy Plugin). He blogs regularly at http://hamletdarcy.blogspot.com and can be found on Twitter as HamletDRC (http://twitter.com/hamletdrc). Hamlet is a DZone MVB and is not an employee of DZone and has posted 28 posts at DZone. You can read more from them at their website. View Full User Profile

Sharing IntelliJ IDEA Project Files in Version Control

  • submit to reddit

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!

From http://hamletdarcy.blogspot.com

Published at DZone with permission of Hamlet D'Arcy, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)



Christoph Kutzinski replied on Wed, 2010/01/27 - 4:01pm

IMHO it's an absolute no-go to check in IDE configuration files into Version Control. What if some other developer likes to use Eclipse or Netbeans instead?

IDE configurations should be generated from the 'real' configuration which should be something like a Maven POM.

Noah White replied on Wed, 2010/02/17 - 9:50pm in response to: Christoph Kutzinski

Checking in IDE configuration is a great time saver when it comes to bringing new team members up to speed quickly. It also reduces the amount of inconsistency in the project. You get less, "it works for me" excuses. Using multiple IDEs isn't a big deal either, though it does increase a projects overhead even if you don't check in their configurations. With IDEA though, it is easy to work with Eclipse as IDEA can import and export Eclipse project files. IDEA can also auto generate ANT build files based off of the project configuration settings which is really nice and ANT can be easily integrated into any other IDE so that route gives you an IDE agnostic approach if that's your thing. Maven, IMO, is a giant FAIL. It's overly complicated and has a much too steep learning curve. POM files for anything non-trivial become complex nightmares quickly.

Noah White replied on Wed, 2010/02/17 - 9:52pm

Nice article. Do you have any tips for using the new .idea directory structure vs. the old .iws, .iml, .ipr file structure. For example in the new structure there's a separate workspace.xml file in the .idea folder.

Jackson Gibbs replied on Thu, 2011/10/20 - 2:44pm in response to: Noah White

+1 to this comment - anyone know of another article that addresses this?

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.