What Is the .idea Directory?

 1. Overview

JetBrains IntelliJ IDEA is a popular choice among Java developers, and while working with it, we’ll encounter the .idea folder in our project structure.

In this article, we’ll explore this directory’s purpose and how to manage it effectively in real-life projects.

2. IntelliJ IDEA Configuration Methods

IntelliJ IDEA offers multiple configuration options to customize project settings. We can define global, project-level, and module-level settings.

While exploring the project structure, apart from the mentioned .idea directory, we’ll notice the .iml file. Both the .idea directory and .iml file are used for configuration and are automatically generated when we start a new project or open an existing one. We can find them in the project’s root directory, alongside our pom.xml (or other build files).

In some cases, a single project can combine multiple technologies and distribute logical components across modules. Consequently, a project can consist of multiple modules, and each module can require a different configuration.

For example, a module might require a different Java version and language level compared to the project-level configuration. IntelliJ IDEA uses the .idea directory for project-level settings and .iml files for module-level settings to facilitate required granular configuration.

3. Content of the .idea Directory

Inside the .idea directory, we’ll find various files and directories. JetBrains’ developers have tried to distribute configurations across different files to prevent potential merge conflicts when version control systems index this directory. As the IDE evolves and developers introduce new features, this can lead to changes in the contents of these files, as well as the addition of new files.

3.1. Files and Directories Overview

Let’s review the files and directories we can typically find inside .idea:

• workspace.xml – this file serves as a central repository for user-specific project-level configurations, for example, change list information, run configurations, updated run configuration templates, some Maven settings, breakpoints, and more
• modules.xml – inside this file, IntelliJ IDEA stores the locations of .iml files for each module
• vcs.xml – this file stores version control system (VCS) settings and configurations, playing a pivotal role in integrating our project with source control tools like Git, SVN, and others
• codeStyles – stores code style settings tailored to the project, including information about the currently used formatter and additional configured properties
• dataSources – when the project has configured data sources, their settings are here
• shelf – this directory temporarily stores code changes when using the Shelf feature for version control in IntelliJ IDEA

The contents of the .idea folder can vary from project to project. The IDE may add additional directories or files based on our project’s configuration and the tools in use.

3.2. Is the .idea Directory Always There?

IntelliJ IDEA automatically generates the .idea folder and .iml files in all projects. The folder is usually visible on Windows systems.

However, it’s usually hidden on macOS and Linux systems. This might lead to confusion, but we can see them with ls -a.

4. Working with the .idea Directory

As we saw earlier, the .idea folder is created and managed by the IDE.

Some teams prefer to commit these files and others prefer not to. Let’s review both approaches.

4.1. When We Commit the .idea Directory

IntelliJ IDEA can easily regenerate some files inside the .idea folder, but some files require additional manual configuration.

When the project setup is complex, we might want to share local configuration with teammates to make bootstrapping smoother. The easiest way to achieve this is by committing the .idea directory along with the .iml files from all modules. We should be careful and avoid sharing user-specific settings, such as workspace.xml, usage.statistics.xml, and the shelf directory.

We can resolve this by adding some exclusions to our .gitignore file:

### IntelliJ IDEA User-specific stuff ###
.idea/**/workspace.xml
.idea/**/tasks.xml
.idea/**/usage.statistics.xml
.idea/**/dictionaries
.idea/**/shelf

JetBrains suggests committing the .idea folder and provides its own gitignore example. However, adopting this approach ties our project to a particular IDE, which is generally discouraged in distributed teams with multiple developers, for several reasons:

• Other team members may use different IDEs or configurations.
• The IDE-specific configuration will clutter the repository with files that are not related to the project source code and run configurations.
• Teammates can use different IDE versions and this can lead to merge conflicts or incompatible configurations.

4.2. When We Do Not Commit the .idea Directory

For seamless collaboration across multiple teams, especially when members are using different IDEs, it’s advisable to gitignore IDE-specific files and refrain from committing them to the shared repository. Let’s take a look at what the .gitignore file should include:

### IntelliJ IDEA ###
.idea
*.iws
*.iml
*.ipr
/out/
.DS_Store
src/.DS_Store

With this approach, we can keep our source code clean and project independent. The main disadvantage here is the necessity to perform project setup for every new team member.

This issue is usually resolved via onboarding documents that include info about the required IDE project configuration.

4.3. When Should We Directly Access the .idea Directory?

We might need to interact with .idea directory when the project unexpectedly stops working. In such cases, developers typically use the “Invalidate caches / Restart” IntelliJ option. If that doesn’t help, we can entirely delete the .idea directory and all .iml files, and thus completely reboot our project.

We should note that that if we delete the IntelliJ IDEA files, we will lose all shelved changes and we’ll need to set up our project preferences again.

5. Conclusion

In this article, we explored IntelliJ IDEA’s configuration, delved into the essence of the .idea folder, and examined the role of .iml files.

We discussed what resides within the .idea folder and how our source control might handle this directory, and we looked at the pros and cons of sharing its contents across developer workstations.