How to manage projects under Version Control Systems

If you decide to share IDE project files with other developers, follow these guidelines:

Directory based project format (.idea directory)

This format is used by all the recent IDE versions by default. Here is what you need to share:

  • All the files under .idea directory in the project root except the workspace.xmlusage.statistics.xml, and tasks.xml files which store user specific settings
  • All the .iml module files that can be located in different module directories (applies to IntelliJ IDEA)

Be careful about sharing the following:

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

You may consider not to share the following:

  • .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)

  • Share the project .ipr file and all the .iml module files, don't share the .iws file as it stores user specific settings


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


Visiedo, I think it's better to use one IDE for the whole team. Because each developer would need to adjust if they wanted to look at the project they don't work on. Also, for IDEA, there are a lot of nice things you may share in .idea folder like a dictionary (may include product-specific vocabulary so that IDE won't complain about spellchecking), data sources (configured databases, where you may look and edit the tables right from the IDE), inspection profiles (what IDE should check and highlight -- from possible bugs like a boolean expression is always true, to antipatterns like violating the Law of Demeter), and coding style (IDEA can automatically format the code like wrap long method parameters list or align local variables' equals sign; this also helps a lot with VCS differences since you will only see relevant changes, because all spaces and stuff will be consistent).

Edited by Kruglov Sam

Is it a good idea to check-in `.idea/modules.xml`? A developer could clone a repository to a custom named folder (`git clone <repository> <directory>`), which means the root `.iml` will change, and `.idea/modules.xml` will show as modified in git.


What about this directory, surely a cache shouldn't be shared with Git?



Would be lovely if this really worked in practice, but I must say this is one of the very old issues with JetBrains IDEs... Settings sharing.

As mentioned before, I've had several issues with another coworker regarding interpreter path on PyCharm. Also, I'm giving this another try right now with PHPStorm and noticed it doesn't share server information - but does share deployment settings, what means it shares a reference to something that might not be set in the other IDE (especially as the Server is referenced by display name...). Also, it does the same for code styling - which would be the biggest win of sharing settings... It references the configuration by name, but the actual configuration is not there - what means that even if we export and import settings at the beginning, later on, someone might change something in the current style profile and it won't be re-shared with the others.


In the latest EAP (2018.2 EAP), there is a new file in th .idea directory named usage.statistics.xml.  That appears to be user specific.  Should it be excluded from VCS?


usage.statistics.xml should not be shared, I've updated the document. See also


I still haven't gotten any answer about modules.xml.

Shouldn't this be on the list to ignore when using external modules from gradle?

I can't see anything in that file that is unique any it changes a lot when we add new projects/sourcesets.


In the recent IntelliJ IDEA versions there is an option to store generated project files externally (available for Gradle and Maven projects):

With this option enabled you will no longer see any generated files in .idea directory, including modules.xml. So, if you are not using this option, it's safe to exclude modules.xml from version control for the Maven/Gradle based projects.


I guess you mean:  "So, if you are using this option" (removed not)

 Well then it should probably go into the above guide under the headline "You may consider not to share the following:" , right?


No, if you have this option enabled, there will be no modules.xml in .idea directory, so there is nothing to exclude. If you are not using this option, you can exclude this file.


So, the .idea/runConfigurations has been removed in one of the latest updates. Its contents have been moved to workspace.xml. At the same time, workspace.xml should be (and is) excluded from version control... Right now, I've temporarily lost all my run configurations because of this, and we kind of lost the ability to share run configurations because workspace.xml is not supposed to and should not be shared. I've recently changed them, they were ignored by git because of the change, which is kind of an inconvenience since I am at another location for the next few days. Why keep us from sharing run configurations? Differences between machines should be solved by path variables anyway. Can this please be changed back?

At the same time: path.macros.xml is included in the settings repository. It should not, in my opinion. Paths are often local to a machine. Or: give us the possibility to exclude it. I've tried that with a .gitignore file, but IDEA updates it periodically anyway. Seems like a bug?

Update: I've now tried to make git ignore the path.macros.xml via .git/info/exclude, and that is being ignored as well. A.k.a. it does not work.

I might have found a solution: add an applicable .gitignore file in the root of the settings repo. Add it to git with git add. Remove the files you intend to ignore from git with git rm --cached. Manually commit and then push the settings repository. The reason: .gitignore will be ignored itself when it has not been committed... I forgot about that.

Edited by Saschasanches

@Saschasanches, as of IntelliJ IDEA 2018.2 Build #IU-182.3684.40 (built on July 17, 2018), .idea/runConfigurations appears to continue to be working as expected. workspace.xml is used to store user-specific (non-shared) run configurations. Have you enabled the "Share" checkbox in the run configurations that you wish to store in VCS?

Our team uses shared run configurations and have not run into any issues. I am able to add an additional run configuration to the .idea/runConfigurations directory by creating a new run configuration and enabling its "Share" option.


@Mhill, yes, thank you for responding. Both issues have been resolved now. I mistakenly thought that I had enabled it already. My bad.


I agree on problem of misc.xml with the

<component name="ProjectRootManager" version="2"

  project-jdk-name="Python 3.6 (pfe-F1u9w4Ou)"  <--- This is user dependent.

project-jdk-type="Python SDK" />


project-jdk-name can be the same for all the users if you rename SDKs on all the machines to be the same. The difference for Python is that SDK name can be different by default, while for Java it's the same by default (1.8, 1.9, etc). If you agree with all the developers to have the same SDK name for Python, your project can be shared with no issues.


In case you ever arrive this post and is puzzled on why there's no Code Style setting on your .idea folder* (besides the reference to the Code Style name you're using), I've found the problem. 

You must copy your current group of settings into the project, so they stop being a single group shared among projects, and start to live inside the .idea folder. Kudos!

*And, of course, if you bother to read through pages of comments, because they probably won't be indexed by google or found through a page search.


Should the file compiler.xml really be included in VCS?

We have a Gradle project and as far as I can tell, compiler.xml only changes when the Gradle build changes.


@David Kron, our team does include compiler.xml in VCS. The file rarely changes for us. Right now the only option that it includes is to use the Eclipse compiler (for its handy incremental compilation and "Proceed on errors" features).

There are a number of files that are regenerated with Gradle imports. We've run into a couple files that we've unversioned for that reason, too. We haven't run into that with compiler.xml, but if you are then you might want to do the same.


How about ignoring target/*? For Java projects you don't want to checking your class files. 


target/* files are not part of the .idea project files. They are generated by your build. I suggest checking for standard ignores for your build system and add them to your gitignore file.


In WebStorm the configurations for the project are stored in workspace.xml.

The configurations are needed to start, build, debug and test the project (among others). 

And, in my opinion, belong to the project not to the singledeveloper.


How can I share the configurations without sharing other users setting?



Please sign in to leave a comment.

Have more questions?

Submit a request