git add .idea/
Sharing the .idea Directory in Version Control
Many projects keep the .idea/ in the ignore list, but it's just as valuable to share the settings here
as it is for any other configurations for code quality tools, formatters, or build configuration. It
is supported and encouraged by IntelliJ.
That said, the reasons why many projects have historically ignored it are real, and it will take a little attention from you and reviewers to decide what to do when a change in this directory shows up in your git status.
Questions to ask are:
- Does this change provide something all the project's contributors will want?
- Does this change contain anything specific to my installation?
- Is this diff flipping the order of some lines, but not changing their values?
Useful to All
We share configurations to stay in sync with others working on the project. Some things are critical and the project won't build if we have different settings. Some things are less critical but still important to have for smooth collaboration, like agreeing on star-imports or which types of warnings are necessary to fix.
You'll also want to share when you've come up with easier way to do things. Maybe you made a template for a kind of file that always starts with the same parts. Or a run configuration with a specific set of parameters that helps you debug a certain kind of issue. Neither is required for work on the project, but you'd like to make it easy for others to use this thing that's been helpful to you.
Not everything that ends up in the .idea/ directory is like that. All projects will have ignore entries like this:
workspace.xml
*.iws
They exclude IntelliJ's workspace files. Those contain things like which tool windows you have open and what sizes they were last.
IntelliJ's "shelf" is another example. If you know about git stash, know shelve and stash serve much
the same use case. When you've made changes and you're not ready to commit them, but you need to get
them out of the way for some reason, you can put them on a shelf and come back for them later.
/shelf
IntelliJ has been making progress on providing clear labels for which things are shared with everyone on the project and which are not, but they haven't yet made it as easy as “commit everything in the Shared directory, ignore everything in the Private directory” so we look at new files on a case-by-case basis.
Installation-Specific Values
Say, for example, that your java installation is in /usr/lib/openjdk-11.
Someone else has theirs in C:\Program Files\Java\jdk1.11.0_07,
or /Users/Fernanda/Library/JavaVirtualMachines/liberica_1.8.0_252.
Clearly there's no way that a configuration that references any one of those values is going to be useful for all of you. Worse, it's likely to actively conflict and break their development environment. That's a file you should not commit and push to the shared repository.
Does that mean you should “Add to .gitignore” and forget about it?
If the entire file is like this and it will be only useful to you, yes. But if it sets a standard for the project or it's something you'd like to share so others don't have to duplicate your efforts, there are a few things to try.
Is it a label or a name?
Any time you make a new configuration that can be picked from a list, it gets a name. Sometimes a name gets a default value like "System JDK 1.11.0(07) in /usr/lib", but all the real details about the path and version are saved somewhere else. See if you can change the name to something more generic. For this example that could be "Java 11." That might be enough, or maybe other people will have to configure what "Java 11" means in their environment.
Is it a path to a file?
You may see a value like /Users/Fernanda/IdeaProjects/Terasology/config.cfg
and think “that's wrong, I don't want that to be Fernanda's copy of config.cfg, it should just be the config.cfg
in the current project.”
IntelliJ is usually good at catching those by itself, but sometimes you might have to help. Many values may use path variables.
That value could be $PROJECT_DIR$/config.cfg and it would work for everyone.
$PROJECT_DIR$ is the most commonly used, but if necessary you can add custom path
variables to your project to be set by each person to match their local environment.
It may take a little experimenting. Sometimes what you'll see in the user interface shows a full path, but it really uses a variable when it saves it. You can try editing the xml directly instead of using the configuration interface. Be sure to test any changes, as not all types of values recognize these variables.
Meaningless Re-ordering of Lines
Hopefully they've fixed all of these by now and you will never run in to this. But it happened enough before that I feel like I should mention it.
When lines like this:
<env name="PROFILING" value="1" />
<env name="PATH" value="…" />
Change to this:
<env name="PATH" value="…" />
<env name="PROFILING" value="1" />
It doesn't matter what order those values are in, so it doesn't break anything. If it happens once, maybe that means IntelliJ changed its serializer so they're always written in alphabetical order or something. In that case, great, go ahead and commit the new ordering.
But if it keeps flipping around, or it's one way when you make a commit but another contributor keeps seeing it flip back the other way, then there's a problem. Nobody wants to see that in every one of your pull requests.
In that case, revert the change to the file instead of committing it, and make sure a bug about it is filed with JetBrains.
Good Things to Share
Notably absent are Live Templates. There are ways to share them but not as easily adding a file to the project repository. Give a 👍 to IDEABKL-5033.
and yes, dictionaries
/dictionaries is often ignored because people see a file show up in there and they think,
as I did, “that file has my local username! It must not be something for everyone on the project.”
JetBrains product manager Dmitry Jemerov explains:
The dictionary is not in fact per-user; the spellchecker uses words from all users' dictionaries for checking the spelling.
If you don't want your local username leaking in to the public git repository, feel free to rename the file to something else before committing it. Or add the words to another file already in the directory; they'll never notice. Just be aware that so far (2020.1) there is no configuration option for that, so you'll be doing that step before you commit every time you add another dictionary word.
Give Feedback
I know some of you are skeptical because you've tried this before and it didn't go so well. I admit: If it always went smoothly, I wouldn't have had reason to write a thousand words to explain it. But if it's been a few years, consider giving it another shot. JetBrains has made a lot of improvements in this area.
If you try this and something doesn't work that seems like it really should, do go ahead and use that Report Problem action in the help section. If you find your issue or feature request has already been reported with enough information to reproduce the problem, you don't need to file another issue or leave a comment. Hitting the thumbs-up icon 👍 (it's up near the issue title) is enough to show your interest in seeing that issue resolved and to receive updates on its progress.
Having visibility in to other projects' issue trackers is definitely a mixed bag. Good old 5033 up there just had its 13th birthday — welcome to your teens! 🥳 — but they can't fix problems they don't know about or can't reproduce. When you do contribute to the issue tracker, remember as you do with any feedback form, to make your comments in the style that you like to see when people report issues in your own projects.
(I know you probably didn't need to be told that, but any time I publicly say “you should tell X about this,” I feel like I need to include a “and don't spam them!” disclaimer.)
JetBrains has both Onboarding and Environment Setup and a Project Model Redesign in the works for IntelliJ this year. I hope that means it's a good time to share all our carefully-tuned projects!