Complete Android Studio .gitignore Guide

The correct approach for Android Studio .gitignore files varies depending on project structure and team preferences, but the consensus is that .iml files should generally be ignored in .gitignore despite some older documentation suggesting otherwise. Android Studio generates these files automatically from Gradle configuration, making them redundant for source control purposes.

Contents

• Understanding the .iml File Dilemma
• Complete .gitignore Template for Android Studio
• Key Categories of Files to Ignore
• When to Consider Including .iml Files
• Practical Implementation Steps
• Common Gitignore Issues and Solutions

Understanding the .iml File Dilemma

The confusion around .iml files stems from historical IntelliJ documentation that suggested including them in source control. However, the modern consensus among Android developers is different:

You don’t want to commit these because they’re only relevant to your setup and what you’re currently working on. You don’t need any of them - a proper Gradle config will do all the work for you because it’s an opinionated build tool.

According to Reddit discussions, .iml files are IDE-specific and should be ignored because:

• They contain paths specific to your local development environment
• Android Studio generates them automatically from Gradle configuration
• They don’t contain essential project information that Gradle doesn’t already manage
• Sharing them can cause conflicts between different developer setups

However, some teams do choose to share .iml files, particularly for complex multi-module projects where the files contain important module relationships.

Complete .gitignore Template for Android Studio

Based on the research findings, here’s a comprehensive .gitignore template for Android Studio projects:

# Gradle files
.gradle/
build/
app/build
*/build/

# Local configuration file (sdk path, etc)
local.properties

# Android Studio and IntelliJ IDEA files
.idea/
*.iml
*.iws
*.ipr

# Android Studio cache
.idea/caches/
.idea/libraries/
.idea/modules.xml
.idea/workspace.xml
.idea/gradle.xml
.idea/usage.statistics.xml
.idea/dictionaries/
.idea/httpRequests/

# Keystore files
*.jks
*.keystore

# Log files
*.log

# OS-specific files
.DS_Store
Thumbs.db
ehthumbs.db

# Built application files
*.apk
*.ap_
*.aab
*.dex

# Java class files
*.class

# Android NDK
ndkBuild/
local.properties

# Proguard configuration files
proguard-rules.pro

# Crashlytics configurations
com_crashlytics_export_strings.xml

# Navigation editor temp files
.navigation/

# Captures folder
captures/

# Render scripts
*.rs
*.fs
*.vert
*.frag

# CMake
CMakeLists.txt.txt

Key Categories of Files to Ignore

Build Artifacts and Generated Files

# Built application files
*.apk
*.ap_
*.aab
*.dex

# Java class files
*.class

# Generated files
bin/
gen/
out/

These files are automatically generated by the build system and don’t need to be version controlled.

Gradle-Related Files

# Gradle files
.gradle/
build/
app/build
*/build/

The official Android documentation recommends excluding build directories as they contain compiled code that can be regenerated.

IDE Configuration Files

# Android Studio and IntelliJ IDEA files
.idea/
*.iml
*.iws
*.ipr

# Android Studio cache
.idea/caches/
.idea/libraries/
.idea/modules.xml
.idea/workspace.xml
.idea/gradle.xml
.idea/usage.statistics.xml
.idea/dictionaries/
.idea/httpRequests/

As noted in the Stack Overflow discussion, these files contain user-specific settings and IDE configurations that shouldn’t be shared.

Local and Sensitive Configuration

# Local configuration file (sdk path, etc)
local.properties

# Keystore files
*.jks
*.keystore

# Crashlytics configurations
com_crashlytics_export_strings.xml

These files often contain sensitive information like SDK paths and keystore passwords that shouldn’t be committed to version control.

When to Consider Including .iml Files

While most modern Android projects should ignore .iml files, there are specific scenarios where including them might be beneficial:

1. Multi-module projects: When working with complex module dependencies, .iml files can help maintain module relationships
2. Legacy projects: Older projects created before Gradle became the standard might rely on .iml files
3. Team consistency: If your team has established workflows around shared .iml files

However, even in these cases, many teams successfully transition away from relying on .iml files by properly configuring Gradle module dependencies.

Practical Implementation Steps

Creating the .gitignore File

1. Create a .gitignore file in your project root directory
2. Copy the template above or use Android Studio’s built-in generator
3. Commit the .gitignore file to your repository

Removing Existing Files from Git

If you already have files that should be ignored in your repository:

# Remove all .iml files from git but keep them locally
git ls-files | grep "\.iml$" | xargs git rm --cached

# Remove all build directories
git rm -r --cached build/
git rm -r --cached app/build/

# Commit the changes
git add .gitignore
git commit -m "Add comprehensive gitignore for Android Studio"

Using Gitignore Generators

You can also use online generators like gitignore.io to create tailored .gitignore files:

Add Gradle, Intellij and Android and you are good to go. Might have to change to *.iml to ignore all iml files.

Common Gitignore Issues and Solutions

.iml Files Still Being Tracked

If .iml files are still being tracked despite being in .gitignore:

1. Check that the pattern is correct (should be *.iml)
2. Remove existing files from git cache as shown above
3. Verify there are no typos in your .gitignore file

Build Artifacts Still Committed

If build files are still being committed:

1. Ensure .gradle/ and build/ patterns are correct
2. Check for any project-specific build directories
3. Update your .gitignore to include all build-related patterns

IDE-Specific Files Still Tracked

For persistent IDE file issues:

1. Consider using Android Studio’s built-in version control settings
2. Check the “Ignored Files” section in Settings > Version Control
3. Ensure all .idea/ subdirectories are properly ignored

Sources

1. What should be in my .gitignore for an Android Studio project? - Stack Overflow
2. What Should Be in My .Gitignore for an Android Studio Project? - Better Stack Community
3. Keep iml files in source control? - Reddit r/androiddev
4. Perfect .gitignore for Android Studio Projects - Medium
5. Android.gitignore - GitHub Official Template
6. Remove .iml Files From GIT for Good - Stack Overflow
7. Linked android modules generate unwanted .iml files - Stack Overflow
8. Android Studio keeps changing project files between developers - Reddit r/androiddev

Conclusion

The modern approach for Android Studio .gitignore files is to exclude .iml files along with other generated files, build artifacts, and IDE-specific configurations. This practice ensures:

• Clean, consistent repositories across team members
• Reduced merge conflicts from IDE-specific files
• Faster clone and checkout times
• Better separation between code and generated artifacts

For most Android projects, the comprehensive template provided above will handle all necessary exclusions. However, always consider your team’s specific needs and project structure when customizing your .gitignore file. When in doubt, follow the principle of excluding anything that can be automatically generated by the build system or IDE.