IntelliJ IDEAs new directory-based project format

I am currently playing with the EAP-Version (Early Access Program) of my favorite IDE IntelliJ IDEA. Since the new version is not that far away it is time to learn the new features and I discovered one that surprised me. A small but pretty nice change.

(Update: Thanks to Strug I have realized that this feature is already present in Idea 8, you can use the action “Open in New (Directory based) format” to convert your project. Fortunately they renamed it to “Save as Directory-Based Format …” in Maia. )

IDEA has a new format to store the project files. It is called directory-based. Instead of using the three famous files .ipr .iml and .iws IDEA will now store all information into a directory, which is simply called .idea. It is located in the root folder of the project. This seems to be somewhat similar to eclipse’s .project folder. In a small example project I created the content of the new directory looks like this:

-rw-r--r--  1 joerg  joerg    163 17 Okt 09:53 ant.xml
-rw-r--r--  1 joerg  joerg   2107 17 Okt 09:53 compiler.xml
drwxr-xr-x  3 joerg  joerg    102 17 Okt 09:53 copyright
drwxr-xr-x  3 joerg  joerg    102 17 Okt 09:53 dictionaries
-rw-r--r--  1 joerg  joerg    277 17 Okt 09:53 encodings.xml
-rw-r--r--  1 joerg  joerg    170 17 Okt 09:53 fileColors.xml
-rw-r--r--  1 joerg  joerg   1595 17 Okt 09:53 misc.xml
-rw-r--r--  1 joerg  joerg    258 17 Okt 09:53 modules.xml
-rw-r--r--  1 joerg  joerg    207 17 Okt 09:53 templateLanguages.xml
-rw-r--r--  1 joerg  joerg    169 17 Okt 09:53 vcs.xml
-rw-r--r--  1 joerg  joerg  38245 17 Okt 10:21 workspace.xml

The files included in this directory depend on the settings you change in the IDE. So, if you would for instance set the SQL dialect for your project there will be another file called sqldialects.xml containing all settings about this.

There is one special file in there, which is workspace.xml. This file contains individual settings for the workspace, which are definitely not intended to be shared via version control. This is equivalent to the .iws file of the old format. IDEA will put this file automatically on the ignore list of your version control.

I see some advantages of the new format.

  • First of all it is easier to find specific settings. The filenames are meaningful and the files are small.
  • The new structure allows a very detailed control of which settings you want to share with your colleagues. If you don’t want to share e.g. your file coloring (another new feature of Maia) just put the file on the ignore list.
  • Directories of the projects saved in the new format will be recognized as projects in the open-project dialog. In the past this was one annoying additional click as you had to choose the .ipr file before.

The new directory based format is a small change but a very good one. It is often a sum of little detail-improvements that save a lot of trouble in daily work. So I am looking forward to the other details to be discovered.

By the way JetBrains released an open source version of IDEA two days ago. So if you want to try this just go to and download the Community Edition.

Be Sociable, Share!
  1. strug says:

    did you know if you can now easily share settings – e.g. encodings.xml – by committing them into your vcs?

    ps: the feature is already part of 8.x. but you remind me to better know my ide. i’m a happy monkey now, thanks:)

  2. Joerg says:

    As far as I know you can share more settings this way than with the old files. Encodings are part of it. You can also share Run-Configurations this way. There is one file per configuration.

    You are right there is an action “Open in New (Directory based) format” in 8.1.3. It is a bit misleading, as this action converts the project and then opens it.

    Thanks for the tip.

  3. Jaime says:

    Versioning workspace.xml was bringing me problems, now I know it haven’t to be under vcs

  4. How can I open a directory-based IDEA project from Windows Explorer? Sometimes I prefer to just “click a project to open it”, as I could do with the .ipr file. It seems that now I need to first open IDEA, then open the project.

  5. Bryce Griner says:

    I guess I’m not quite understanding the true value of this feature. I always add the .ipr, iws, etc files to SVNs ignore list and when I noticed the .idea folder I added that to the ignore list as well. It seems to me like there will always be a chance for conflicts if I commit that folder and its contents, even if I leave out the workspace.xml file.

    Are there no developer specific settings in any of the other files?

    Any example of a problem might be that I don’t want to share some config so I leave it out of source control, then another develoepr adds it. The next time I update I will get some kind of tree conflict.

    I use the pom.xml file to create my Intellij projects so it is possible that I don’t have a need to commit the .idea folder as most of the common configuration between developers and environments is defined in there. I’m curious however if there are some benefits that I am losing out on because I am not using this feature.

  6. says:

    Neat blog! Is your theme custom made or did you download it from somewhere?

    A design like yours with a few simple tweeks would really
    make my blog jump out. Please let me know where you got your theme.

    Many thanks

  7. Aaron says:

    Correction regarding “Instead of using the three famous files .ipr .iml and .iws . . .”:

    Tried it, and it looks like you still need the IML files. Directory-based project format still creates and uses IML files outside of the .idea directory. If you delete the IML files the project won’t run.

  1. There are no trackbacks for this post yet.

Leave a Reply