How to manage projects under Version Control Systems

To share IDE project files with other developers, follow the guidelines below.

Active project format (.idea directory)

Directory-based. The default format used across all recent versions of IDEs.

What needs to be shared:

  1. All files under the .idea directory in the project root except the items that store user-specific settings:
    • workspace.xml
    • usage.statistics.xml
    • shelf directory
  2. All the .iml module files (can be located in different module directories) -> applies to IntelliJ IDEA

Note that starting with version 2019.1, IntelliJ is capable of adding everything that needs sharing to Version Control automatically.


Items you need to be cautious about:

  • Android artifacts that produce a signed build (will contain keystore passwords)
  • In IDEA 13 and earlier, the dataSources.ids and datasources.xml files can contain database passwords. IDEA 14 solves this problem.

Items you may want to exclude from sharing:

  • .iml files and .idea/modules.xml file for the Gradle or Maven based projects since these files will be generated on import
  • gradle.xml file, see this discussion
  • user dictionaries folder (to avoid conflicts if other developer has the same name)
  • XML files under .idea/libraries in case they are generated from Gradle or Maven project

Legacy project format (.ipr/.iml/.iws files)

File-based. Outdated and not recommended for use.

  • Share the project's .ipr file and all the .iml module files.
  • Do not share the .iws file as it stores user specific settings.


For Git, you can use this .gitignore as the starting point.

Comment actions Permalink

Just thought I'd comment I'm having problems with misc.xml as well. My main reason for including .idea into VCS is so that other developers can clone the project and open up PyCharm with all the default configs set without headache and can start developing right away. I also like the idea of having a .idea/local so we know exactly what can be put into .gitignore. Serge Baranov, is there a list of files that are generated upon import that we can exclude from VCS?

Edited by Rlele5
Comment actions Permalink

I somhow changed the vcs root to the folder I have all my projects in and some of the files are marked red, I am guessing I did something wrong by changing the root can someone help me restore the default settings


Comment actions Permalink

Seems that this approach is not fully mature: in `compiler.xml` I get conflicts about different JDK versions, in misc.xml the JDK version name is also user specific. Also if team mates do use different plugins there will also be conflicts. I wonder if that will be fixed some time...

Comment actions Permalink

In our project we also notice that jrebel seems to add an regularly changing entry into the .iml files

<entry key="lastExternalPluginCheckTime" value="1583916902974" />

this messes up the git changes, since people keep committing  .iml files where only this line changed.

Can we somehow get rid of this behaviour be jrebel?

Comment actions Permalink

I created a support ticket with ZeroTurnaround

Comment actions Permalink

Thanks T Zillinger! Let me know what you find. We have the exact same issue with that attribute and version control.

Edited by Bradley Wagner
Comment actions Permalink

What about other jetbrain tools. In there is a section about ignoring .idea/modules and iml files if gradle autoimport is enabled. But i you use teamcity inspection the gradle build type seams not to work if iml-files are missing. It just dropps to 0 inspection errors.



Comment actions Permalink

This page seems out of date with respect to IDEA 2020, and could stand to be re-written.

Comment actions Permalink

sounds like this is broken by design. obviously jetbrains devs don't use their own products or don't have enough testing to understand the variety of needs for different teams. I wonder what VSCode looks like in this space.

Comment actions Permalink

If you are developing with Java and Maven then you can argue that any IDE specific file checked into VCS is a smell. Luckily these days you see very few OSS projects where you can spot IDE specific files in their Git repo. And thank you for that!

It seems in particular Eclipse users have a hard time understanding that if you are using Maven then the pom is the project definition. Intellij IDEA users to some extend too as IDEA has this idea that a Maven project needs to be "imported" and it does a fair amount of duplicating stuff into files in .idea folder which can already be found in the pom.

If your project is Maven-based and if developers use the IDE of their choice (let them!) then a decent .gitignore file would look like this:

# Ignore Maven stuff

# Ignore Eclipse stuff

# Ignore IntelliJ IDEA stuff

# Ignore NetBeans stuff


Edited by lbruun
Comment actions Permalink

Well, in a perfect world Maven and IntelliJ would be feature complete and share the same set of functionalities. But we are not yet there (and we will never get there?). So in practice we need to configure things both in IntelliJ and in Maven. I.e., we need such configuration files for IntelliJ and it would be helpful if we can put some of them (that are project dependent) into VCS and those that are user dependent in ignore files. But IntelliJ still mixes up those different file types (for quite some years now).


Please sign in to leave a comment.

Have more questions?

Submit a request