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:
- 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
- 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.
Please sign in to leave a comment.
Just thought I'd comment I'm having problems with misc.xml as well. My main reason for including .idea into VCS is so that other developers can clone the project and open up PyCharm with all the default configs set without headache and can start developing right away. I also like the idea of having a .idea/local so we know exactly what can be put into .gitignore. Serge Baranov, is there a list of files that are generated upon import that we can exclude from VCS?
I somhow changed the vcs root to the folder I have all my projects in and some of the files are marked red, I am guessing I did something wrong by changing the root can someone help me restore the default settings
Seems that this approach is not fully mature: in `compiler.xml` I get conflicts about different JDK versions, in misc.xml the JDK version name is also user specific. Also if team mates do use different plugins there will also be conflicts. I wonder if that will be fixed some time...
In our project we also notice that jrebel seems to add an regularly changing entry into the .iml files
<entry key="lastExternalPluginCheckTime" value="1583916902974" />
this messes up the git changes, since people keep committing .iml files where only this line changed.
Can we somehow get rid of this behaviour be jrebel?
I created a support ticket with ZeroTurnaround
Thanks T Zillinger! Let me know what you find. We have the exact same issue with that attribute and version control.
What about other jetbrain tools. In https://github.com/github/gitignore/blob/master/Global/JetBrains.gitignore there is a section about ignoring .idea/modules and iml files if gradle autoimport is enabled. But i you use teamcity inspection the gradle build type seams not to work if iml-files are missing. It just dropps to 0 inspection errors.
This page seems out of date with respect to IDEA 2020, and could stand to be re-written.
sounds like this is broken by design. obviously jetbrains devs don't use their own products or don't have enough testing to understand the variety of needs for different teams. I wonder what VSCode looks like in this space.
If you are developing with Java and Maven then you can argue that any IDE specific file checked into VCS is a smell. Luckily these days you see very few OSS projects where you can spot IDE specific files in their Git repo. And thank you for that!
It seems in particular Eclipse users have a hard time understanding that if you are using Maven then the pom is the project definition. Intellij IDEA users to some extend too as IDEA has this idea that a Maven project needs to be "imported" and it does a fair amount of duplicating stuff into files in .idea folder which can already be found in the pom.
If your project is Maven-based and if developers use the IDE of their choice (let them!) then a decent .gitignore file would look like this:
Well, in a perfect world Maven and IntelliJ would be feature complete and share the same set of functionalities. But we are not yet there (and we will never get there?). So in practice we need to configure things both in IntelliJ and in Maven. I.e., we need such configuration files for IntelliJ and it would be helpful if we can put some of them (that are project dependent) into VCS and those that are user dependent in ignore files. But IntelliJ still mixes up those different file types (for quite some years now).
How about runConfigurations? Can it be shared?
Yes. In the run configuration, you can check the "Store as project file" option. (This use to be a "Share" checkbox, but was changed at some point, in v2020.1 I believe.) See the Common Options section of the Run/debug configurations dialog page in the IDEA Help documentation.
In the past, this would (always) put the shared run configuration file in the .idea/runConfigurations directory. However, as of v2020.1, while you can still save it there, you can choose to save it in a different project directory. The UI will suggest {projectRoot}/.run as the "default". Each config is saved as a *.run.xml file. This allows you to share run configurations without having to share the .idea directory at all.
This was a nice change in v2020.1 as run configs were the only thing we wanted to share (and I think this is a common desire/use-case). But sharing just the .idea/runConfigurations directory caused some issues when people went to first load the project. Since we switched to using the new {projectRoot}/.run directory, those hassles have vanished.
Mark Vedder I've discovered the change concerning the separate .run folder in v2020.1 as well and I welcome the change very much. But what I don't understand is, how does IntelliJ determine the "default" when I click on "Store as project file"? We have had projects where it pre-assigned .run as the value and others where .idea/runConfigurations was chosen. To me the behavior looks completely random currently, as I don't understand it yet. Also a fresh Maven project I just created also did pre-assign the old location instead of the new one. Where does the "default" come from? Is it configurable?
I am using the newest IntelliJ version 2021.1.1
From personal experience I can say that we tried to store the whole .idea/ folder in Git and ignore the generated files based on the template from https://github.com/github/gitignore/blob/master/Global/JetBrains.gitignore. In the end the management overhead for us was too big, even with the gitignore template, as every developer can have a different environment and every little plugin or even a different IDEA version can change or add stuff in the .idea folder.
We have now changed our .gitignore file to exclude everything in .idea/ and explicitely enable the files we are interested in sharing like this:
@... If the project is under version control and the .idea directory (or the .idea/runConfigurations directory) is ignored, it will suggest the {projectRoot}/.run Otherwise it will suggest the .idea/runConfigurations This blog post discusses the behavior. Unfortunately, if you are not under version control or the directory is not ignored, even if you have a {projectRoot}/.run directory with stored configs (say from a previous save), it will not default to suggesting the {projectRoot}/.run directory. But it will be listed in the drop down of potential save locations.
To the best of my knowledge -- and after having looked through the actual source code in IntelliJ IDEA when implementing the saving of run configurations for a new project wizard in the plugin I write -- no it is not configurable.
In the end, I think that is the best strategy. It is what we do as well in the rare cases we want to share any IDE configs (although most of the time we do not). This is especially useful since plugins can add files to the .idea folder. This can cause issues if one dev has a plugin installed, and another does not. Or if it is a plugin that is best to not share configs for. And it is much easier to later enable the sharing of something when it is determined it is best to do so then to try and add a file to the ignore list after its been shared, because inevitably some dev goes to delete it from their local workspace, but deletes it from git and causes issues for the other dev(s) that need/use it.
How about jetbrains publishes a few versions of gitignore.. from basic android to some of the more exotic requirements. There's a few floating out there, but none are official from jetbrains that i could find.
The first item of the article should be less categorical and include the caveat from the .gitignore mentioned at the end:
Hi, could you please update this article? What I'm seeing missing here is:
- sshConfigs.xml - should be carefully considered, may be added, but doesn't have to. In my example, I have a private key with my name in it, so that definitely wouldn't work for other members
- mongoSettings.xml - contains db passwords
- dataSources.xml and dataSources.local.xml - contains db access data sources - not everyone in the team should know this information, especially not juniors
- dataSources/ - this folder should most probably also be excluded
- httpRequests/ - this looks like a history of all requests and responses I made - not everyone needs to know this, nor everyone will have the same requests and responses at their local machine
I'm using WebStorm with the database plugin, maybe some other information from other IDEs/plugins should also be added. Would you be kind to consider adding those? (Though, I may not be entirely right about all of them; but please let me know where I'm wrong).
My 2c:
For any open source project or any other type of project where you don't know the developer community then ignore everything which is IDE specific. See my answer for a suggestion for a general .gitignore file which will work with most projects.
For an in-house project where you know all your co-workers will be using the same IDE then by all means: go ahead and put IDE specific files under version control. But in my experience it is always a smell. How do you think open source projects survive without having all this "IDE noise" in their Git repos? The answer is that they survive quite well and so can you. From my experience it is better to keep all IDE specific files out of the repo. You risk one day to accidentally commit something with a secret in it. Even .xml files without direct credentials could contain information which you don't want to disclose outside of a narrow circle. What happens if you one day need to share your repo with a partner? (happened where I work). If you really need to share "local development setup" then it is - IMO - better to educate developers via a Wiki. They'll learn from setting up their own datasources for development purpose rather than assuming it is all black magic. I've worked in companies where such information existed in the repo but it has never really helped me ramp up anyway. I still needed to carefully review it as it was either outdated or made assumptions that did not apply to my workstation even if all devs used IntelliJ.
This thread is in itself proof that trying to figure out which IDE files to include in the repo and which to leave out is an endless and fruitless journey. Don't waste time on it, is my advice.
Feel free to disagree. :-)
Link here is wrong:
Should be this: https://www.jetbrains.com/help/idea/configure-project-settings.html#share-project-through-vcs
My .idea/misc.xml is under version control keeps getting overwritten by intellij. Any advice?
What are the specific changes that occur to this file?
Is it a Maven or Gradle project? What Java language level is set for the project in the build file?
Gradle with build.gradle.kts
tasks.withType<JavaCompile> {sourceCompatibility = "17"
targetCompatibility = "17"
}
So it's expected that it changes to languageLevel="JDK_17". Just commit this change and it should not be an issue again.
Could we have some clarification on the Gradle files? Specifically this line:
Is this still accurate? What if you need to mark a directory as source or generated source or something like that and need to share that with your team?
Timothyfroehlich Current IDE versions do not even save
.imlfiles in the project for Maven and Gradle. Yes, it's still accurate. Source roots are defined via the build file.Serge Baranov Thanks for the quick response! That's what I'm confused about. I'm using Android Studio Koala Feature Drop | 2024.1.2 Canary 4, so that's IntelliJ 2024.1.2, and I right-clicked on a directory to mark it as source, and afterwards I had an `.iml` file in my `.idea/modules/` directory that records the directory as source. So for my situation, I needed to include `.idea/modules.xml` and `.idea/modules` in my source control. Even though the directory is included as source in one of my build files I still needed to add it manually. Am I doing the right thing here?