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 the .idea directory in the project root except the workspace.xmlusage.statistics.xml, and tasks.xml files and the shelf directory which store user-specific settings
  • All the .iml module files that can be located in different module directories (applies to IntelliJ IDEA)

Starting with the 2019.1 version,  IntelliJ can automatically add to Version Control everything that needs sharing 

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.

85 comments
Comment actions Permalink

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
1
Comment actions Permalink

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.

0
Comment actions Permalink

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

 

.idea/caches/
.idea/caches/build_file_checksums.ser
0
Comment actions Permalink

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.

0
Comment actions Permalink

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?

0
Comment actions Permalink

usage.statistics.xml should not be shared, I've updated the document. See also https://youtrack.jetbrains.com/issue/IDEA-192913.

0
Comment actions Permalink

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.

0
Comment actions Permalink

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.

0
Comment actions Permalink

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?

0
Comment actions Permalink

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.

0
Comment actions Permalink

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
0
Comment actions Permalink

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

0
Comment actions Permalink

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

0
Comment actions Permalink

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

0
Comment actions Permalink

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.

0
Comment actions Permalink

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.

0
Comment actions Permalink

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.

0
Comment actions Permalink

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

0
Comment actions Permalink

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

0
Comment actions Permalink

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.

0
Comment actions Permalink

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?

Thanks

0
Comment actions Permalink

Make the run configuration shared, see https://stackoverflow.com/a/3136255/104891 .

0
Comment actions Permalink

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.

0
Comment actions Permalink

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
0
Comment actions Permalink

As for

{quote}

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

{quote}

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?

1

Please sign in to leave a comment.

Have more questions?

Submit a request