How to manage projects under Version Control Systems

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

Default project format (.idea directory)

Directory-based. The default format used across all present-day versions of Intellij-based 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.

270 out of 365 found this helpful

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 Sascha Sanches

@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?



These instructions are far from complete. What should I do with all the folders like shelf etc? How on earth it can be so difficult to share IntelliJ configs in git? VSCode has made good job on this front.


workspace.xml contains many useful components like FileColors, Scopes, PhpServers, RunManager. At the same time it has too much user specific garbage like tasks (even if I don't work with tasks specially), changeList. These two points crossing out possibility to put this XML under version control. Even there is no possibility to expel some settings into separate file. Or I don't know how?

Edited by Alexandr Skrashuk

As for


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


but .iml files contain many other useful stuff that is not generated by Maven, for example, the facet configuration. So how can I share the facet configuration and still ignore the library entries (e.g. <orderEntry type="library" name="Maven...) that are updated by Maven.

I assume it is an oversight of the format and the library entries should be extracted to separate configuration files that can be ignored separately?


Noticing some local change in .iml files that seem like they shouldn't be in VCS:

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

Any advice?


I love Erez idea of a separate local directory under .idea, but that doesn't seem to be on the way.  We have a team of 6 people of widely varying skill levels using pycharm, and the .idea directory caused us never-ending headaches, so our solution was to leave it out of version control completely (everybody creates the project locally from the files pulled from git).  Not an ideal solution by a long shot, but easier for this type of team than trying to share select files that are constantly changing and contain a mix of shared and local information.

Jetbrains: it sure would be nice to have a comprehensive solution to this some day.


It would be super helpful (and avoid general confusion), if you could state at the very beginning of this article that no IDE files should be vital for a minimal project setup and the ability to build it on command line/CI.

You could the go on explaining the exact reasons and benefits why one may consider sharing specific files inside of `.idea` with other people.

Instead of having a long list of files on the ignore list, please consider a simpler `.gitignore` file that optionally whitelists certain files that should be in source control, e.g.




!.idea/foo.xml   # do not ignore foo.xml because of bar



Can the following files safely be excluded through .gitignore when using a Gradle project?

  • .idea/compiler.xml: to me it seems this file is automatically generated and updated based on the compiler configuration in a Gradle build
  • .idea/artifacts: this also seems like something that I never defined in my project and was taken from the Gradle model

What do you think?


The files generated on import and not having any manual customizations can be safely excluded from the version control.


Please sign in to leave a comment.

Have more questions?

Submit a request