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 about .idea/libraries?

Should I store them in the source control repository?

There are many *.xml that change frequently.


David Perez, it would depend on the project you are using. If the project is Maven or Gradle based and these library files are generated automatically on import, you can exclude them from the version control. When the libraries are configured manually by the user, they should be shared.


Thanks for the very quick and clarifying reply.  In my case they are managed by Maven and SBT, so I can remove them.


This is so wrong... A whole lot of files inside .idea store user-specific settings, depending on a variety of different things like the set of installed plugins. Also, in practice, not all project settings can be shared among all developers. (My personal favorite -- spell checking. I always turn it off as it is rather distracting, the negative is that it's a change inside .idea that I have to deal with.)


We do also have a similar problem about having personal/custom project settings. Especially regarding including/excluding certain parts of large modules with a lot of css/javascript. Without excluding stuff, intellij slows down a lot. Is there a way to include other xml files from within .iml files? So maybe we can place a file that would have what is going to be included/excluded in each users home folder and import that file from the main module .iml file that is in version control?


Erdinc, it's not possible. Your use case and the feature request is welcome at Please describe what configuration files are different between the users and how you want to share them.


Here's my current issue with checking in *.iml:


if dataSources.xml is supposed to be excluded, should sqlDataSources.xml also be excluded?


Actually I don't think you can ignore dataSources.xml, because if you have configured some JPA/ORM persistence checking in your project, then the .iml file will contain those references, which appear to reference structures in sqlDataSources.xml which reference structures in dataSources.xml. Does that sound right?


I am trying to set up a shared dev environment for MediaWiki / Vagrant as described in

There are a number of questions that are unclear when doing it for the latest PhpStorm EAP (138.84):

  • Shared dictionary: It would be better to share a file in the .dic format - easier to compare and work with from other systems. Yet, the reference to the directory is contained inside workspace.xml, which should not be shared, hence everyone need to set it up manually, or share the dictionaries\user.xml
  • Database connections:  The mysql database is inside Vagrant instance, and can be accessed via SSH to localhost with a private key file, which is also stored in the repository. There are no security issues with sharing private key or passwords in the project files, as this is locally-accessible vagrant instance. If I add all values from <data-source source="LOCAL"...> in dataSource.xml to dataSource.local.xml, phpStorm moves them back to the local file, and I suspect local file should not be shared. Also, I suspect it does not save user's password. Is there a way to all for the CSS-style cascading of values, so that dataSources.xml provides needed values with possible override by .local.xml?
  • Would it be possible to dynamically discover the SSH port of the vagrant instance, so that in case multiple vagrants are running at the same time, and their SSH ports auto-increment, phpStorm would know where to connect?

Here's a pretty well thought-out .gitignore for you to try:


Thanks Raveren, a very useful .gitignore example.

Novice question here: if I've got no plugins (not using Maven or Gradle or anything) and simply using intellij and GitHub to develop with a team of others that may or may not be using intellij as well (they might be using Eclipse, NetBeans, or some other IDE) how should I be configuring my .gitignore?

Should I simply be ignoring everything generated by intellij (such as the entire .idea/)?


Short answer, it won't hurt to add the .idea folder to git and there could be benefits sooner or later.


misc.xml is killing me.    We check our intellij project into source control.   There are some shared config options in there for plugnins... like an eclipse code EcliipseCodeFormatter, CheckstyleConfigurable, FindBugsConfigurable....  all good shared thingies... but this dang value also keeps getting added:

<component name="ProjectKey">

      <option name="state" value="ssh://" />



it makes me sad...  its clearly 'per developer' information..    


Is it possible to share version controlled configuration between different JetBrains products - IDEA, AndroidStudio, etc. ? I want to include it in my dotfiles.


I can understand not checking in user-specific information from workspace.xml, but having the application target configurations as something that is shared among team members would be very useful.  This is a constant source of problems when sharing project code among several team members.


Almost all the benefits you state are provided by using Maven as the build system. IDEA will import a Maven POM, often completely seamlessly and without intervention. Why duplicate that information in project files.

Netbeans also integrates seamlessly with the Maven POM.

The only IDE project files I ever see in VCS are for Eclipse. I think this speaks more of the failings of Eclipse than it does any merit in versioning IDE project files.

Send from: VigRx Plus


Would it make sense to have a separate directory for files that shouldn't be shared (local)?  Maybe something like:

.idea <-- don't ignore

.idea/local <-- add to .gitignore

so things like workspace.xml could go into .idea/local


I like this idea.


As different people may have different versions of IDEA, and if your project imports cleanly from SBT, Maven or Gradle, another approach is not to have any.idea/ files under version control.


My teammate and I keep conflicting over the "Project Interpreter" setting in <project\_name>.iml.  It seems to me like this should be a local setting.  The issue is that he is installing the necessary libraries on his laptop, and I'm using a VirutalEnv.


Is there some way to prevent this setting from being in conflict?


For the Python interpreter you have to rename it when adding so that it's stored in the project under the same name for all the users, the actual location would be stored locally and you will not have any conflicts, same as for JDK.


Serge, thanks for the quick response.  I'm not sure I follow though.  Here is the conflict:

me:  <orderEntry type="jdk" jdkName="Python 2.6.8 virtualenv at ~/dev/cti-virtualenv" jdkType="Python SDK" />

him: <orderEntry type="inheritedJdk" />


"Python 2.6.8 virtualenv at ~/dev/cti-virtualenv" can be renamed to "Python 2.6" in the settings for both machines.


Hmm... I'll try it, but I don't really see how its going to change things.  All that did was change the line for me, when he loads it, I think it complains that the path isn't found (because it isn't).

It shouldn't be the case that we have to share this setting.  Also, this line is always in conflict from misc.xml:

me (now renamed my virtualenv):   <component name="ProjectRootManager" version="2" project-jdk-name="Eds CTI Python 2.6.8 VirtualEnv" project-jdk-type="Python SDK" />

him: <component name="ProjectRootManager" version="2" project-jdk-name="Python 2.6.7 virtualenv at ~/work/cti/envs/cti" project-jdk-type="Python SDK" />

It seems like the design is that all team members have to locate their VirtualEnv in the same place and give it the same name?



Can you add some clarity on this line: "All the .iml module files that can be located in different module directories (applies to IntelliJ IDEA)"?

As a newbie to IntelliJ, I have no idea what that means so I don't know what I should be ignoring.


In the latest version of PyCharm, I am not able to check in the .iml file because it contains the full path to the virtualenv directory which, in our case, is located in each user's home directory so the path is different for each user.


Ron Smith, rename your virtualenv in PyCharm. By default Python interpreter name contains the full path, but you can remove it and leave only Python 2.7 or Virtualenv 2.7 in the name:



What about app/build?

The default .gitignore lists /build but this doesn't take into account the app module's build directory

which also contains generated, intermediates, and outputs folders, that change frequently.


In 14.1.1 with IDEA + Gradle - the iml for the buildSrc folder contains paths relative to my machine, but I'm just excluding that one iml file.  See issue:


Please sign in to leave a comment.

Have more questions?

Submit a request