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

What is misc.xml? What sort of config does IDEA stores in it?

and why does it get changed every time i rebase the source base from remote GIT repo.

Could you please point a doc where we can read more about what files needs to be shared across VCS


IDEA changes paths in compiler.xml for sourceOutputDir and sourceTestOutputDir under windows to use backward slash and on Mac to use forward slash. Why?


Jimmy, it looks like a bug. Please report at .


We have a problem with the PHP module in IntelliJ: the php.xml contains the PhpUnit load_method, which differs from developer to developer (especially with different platforms):

<component name="PhpUnit">
<PhpUnitSettings load_method="PHPUNIT_PHAR" configuration_file_path="$PROJECT_DIR$/src/tests/php/phpunit.dist.xml" custom_loader_path="" phpunit_phar_path="/usr/local/bin/phpunit" use_configuration_file="true" />

Is that a known issue?


@Patrick Do you mean that there are different PHPUnit's setup options (through phar or composer) or that there are different paths to PHPUnit?


@Liubov Melnikova Exactly. The load_method differs from device to device (some users have phpunit in their PATH, some have it in an arbitrary location). also the exact path (specified in phpunit_phar_path differs on the differing machines.

We considered excluding the php.xml from our VCS, but the version number specified in the PhpProjectSharedConfiguration component is very important, as we do not have the latest PHP version available in our production environment.


A good source for a .gitignore file can be found here:
Nevertheless I miss the exclusion of build artifacts:


Is there a good way to stop IntelliJ from changing the order of the dependency entries in the .iml files? We're using Gradle and the reordering seems especially frequent on buildSrc_main.iml and buildSrc_test.iml, but it happens on the other .iml files too. It means we're constantly having to choose between introducing noise to our version history and discarding the changes, potentially losing significant changes we didn't happen to notice. This is especially irritating for shops that have an "every commit must go through code review" policy.

I'd love some way to, say, always sort the entries alphabetically. If there are legitimate additions or removals, they'll show up as isolated changes rather than half the file changing.

Edited by Steven Grimm

This should not happen, please report a bug at


So I'm using IntelliJ Ultimate 2016.1 + maven + git.  We are managing the project under git with the iml files checked in.  Only problem that we're facing is that iml files always pops up as being modified on git.  So it's annoying that we would have to always filter through all of the iml files and just ignoring them.   Is there a better way to go about this?  We used "skip-worktree" options from git, but that's a temp band aide that doesn't really solve our problem since it doesn't truly ignore the modified files.  

We tried removing the IMLs and just track the runConfigurations in git, but IntelliJ would lose the project environment of maven between branch switching.  Which forces us to manually re-import maven.  

I made a post about this on Stackoverflow with some more details.


We are using IntelliJ and Webstorm on a project shared in git.  IntelliJ creates a .iml file in the module root directory, while WebStorm creates a .iml in the moduleRoot/.idea directory.  They differ slightly.  Should we keep both?  Git rid of one? Ignore one?  If so, which?


This is what we do in our project ->

* Check in the *.iml, workspace and other "moving parts" in our git repo

* After that we add *.iml, workspace and the other "moving parts to .gitignore and checked in the new .gitignore file at git repo

* Share with others and enjoy

With this steps we are able to open the project in a new place because it will find the iml and other required files but it will not cause noise once used.

IMPORTANT: if you add new modules, remember to include the iml and other required files the first time manually because they will be, of course, ignored as stated at the new .gitignore file.

It's sad IntelliJ had a whole mess in these files but hey, once ready, the rest of the fly with IntelliJ is great.


Several people reference the gitignore file at the gitignore repository. However, I believe this one is still lacking because it also ignores some files that should be shared. For example, the jsLibraryMappings.xml file contains mappings for javascript libraries. If anyone adds a new library and wants code navigation (e.g. F12), he/she might add the library to this file (via Settings). In that case, the rest of the team shouldn't have to perform this manual step too.

According to this article, these files shouldn't be ignored either. I've created a pull request to change this.


When using clion, the project iml file contains local paths, in the "Header Search Paths" section. This means this file should be ignored, right?

Edited by Martin Fredriksson

I just want to echo the feedback of this being a hot mess. Why on earth would you intertwine personal, often secret settings, with global ones in not only the same folder, but often in the same files? Please figure out a better way to do this. The default JetBrains .gitignore does not ignore .idea/workspace.xml files in nested folders, for instance.

Please separate personal files from non-personal and make the default ignore rules a one- or at most two-liner that is fail-safe. The current situation is horrible.

Edited by Asbjørn Ulsberg

Any chance of a review of the .idea directory layout and its contents? I want to move shared settings under version control, but at this point it's still less problematic and error-prone to just import Gradle build files and hand-customize from there. It just doesn't scale, as we move to smaller microservice projects, composite Gradle builds, and more engineers.


It'd be even greater if a preset gitignore file was created alongside the project.


I am quite confused what are you all discussing about. Isn't it enough to store just the Maven configuration file POM.XML to the Version Control System and ignore ALL the IDE specific files? Isn't it exactly what Maven (or Gradle etc.) is for???


@Jan Zidek there are IDEA-specific configuration properties, such as Data Sources and Run Configurations that aren't covered by Gradle build scripts and Maven POM files that are worth sharing in source control.


Should I ignore misc.xml since it contains quite weird information, like "project sdk name" and "dictionary name"?


<component name="ProjectDictionaryState">
<dictionary name="mydict" />
Edited by Kruglov Sam

Hope it's resolved soon, thanks


I just updated the Go plugin in IDEA to 171.4694.61 and it now stores a local path (component name="GOROOT") in misc.xml. Is that a bug or should I remove misc.xml from version control?


FYI, .iml file contents are still inconsistently ordered as of IntelliJ IDEA 2017.2.5, Build #IU-172.4343.14, causing needless churn when refreshing dependencies via Gradle or Maven. This is the same issue that Steven Grimm mentioned in the comments here back in April 2016.

This issue is being tracked here:

It may be helpful to vote on this issue if you are experiencing this issue as well.


Another issue with putting .iml files under source control is differing IDE versions between users.  If not all developers in the team are on exactly the same revision of the IDE then you get spurious modifications to the project-level .iml file added by one user and then removed by the other, which pollutes the code change history.

For instance, in PhpStorm the latest version of the IDE adds an "orderEntry" section for a module library, and when other developers who are not quite up-to-date with the IDE open the file it gets removed.  It sure would be nice if the IDE ignored but preserved sections it didn't know about.

Edited by Thomas Smith

Is .idea/modules.xml now not necessary to version control since 2017.3.1?

I use gradle and "Store generated project files externally" and IntelliJ removed this file when I exited after upgrading to 2017.3.1.


Wouldn't it be better to ignore the .idea/ directory completely, and let every developer to import the project into their own IDE? 

Basically my approach would be to just share source code (including build files), while everything else is local to each developer. I am interested on reading your opinions on this


Please sign in to leave a comment.

Have more questions?

Submit a request