Knowledge Base/Version Control

How to manage projects under Version Control Systems

Serge Baranov
posted this on March 19, 2013, 05:03

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.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:

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


User photo
David Perez Ingeniero

What about .idea/libraries?

Should I store them in the source control repository?

There are many *.xml that change frequently.

December 27, 2013, 14:14
User photo
Serge Baranov

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.

December 27, 2013, 14:17
User photo
David Perez Ingeniero

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

December 27, 2013, 14:22
User photo

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

January 6, 2014, 18:41
User photo

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?

February 12, 2014, 07:23
User photo
Serge Baranov

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.

February 12, 2014, 07:27
User photo

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

February 13, 2014, 06:00
User photo

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

February 14, 2014, 19:56
User photo

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?

February 14, 2014, 20:08
User photo

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?
May 9, 2014, 09:24
User photo

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

August 26, 2014, 15:49
User photo
Ozkaynak D

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/)?

September 30, 2014, 09:31
User photo

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

October 1, 2014, 11:21
User photo
Eric Hubbard

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

November 13, 2014, 03:36
User photo

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

November 18, 2014, 17:17
User photo
Tom Eskridge

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.

November 20, 2014, 02:18
User photo

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

December 30, 2014, 10:05
User photo

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

February 25, 2015, 02:08
User photo
David Perez Ingeniero

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.

February 25, 2015, 10:47
User photo

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?

February 26, 2015, 19:12
User photo
Serge Baranov

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.

February 26, 2015, 19:15
User photo

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" />

February 26, 2015, 19:17
User photo
Serge Baranov

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

February 26, 2015, 19:18
User photo

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?


February 26, 2015, 19:25
User photo

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.

April 4, 2015, 19:20
User photo
Serge Baranov
April 5, 2015, 01:17
User photo
Ron Smith

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.

April 17, 2015, 22:21
User photo
Serge Baranov

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:


April 18, 2015, 00:14
User photo
Guy Levy

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.

April 24, 2015, 01:02
User photo
Stephen Ash

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:

May 20, 2015, 23:51
User photo
Tarun Bafna

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

June 7, 2015, 15:05