How to Think About `.gitignore` for Android Studio and a Standard Practical Setup

When developing Android apps in Android Studio (Gradle / Kotlin-based), many developers struggle at least once with how to write a .gitignore. In practice, discussions and real-world knowledge online have largely converged, and the way of thinking about “what to exclude from Git” is fairly consistent.

In this article, we organize widely referenced official templates and practical discussion points, and succinctly summarize a safe, easy-to-adopt .gitignore as a starting point, along with areas where opinions tend to differ.

Basic Policy for an Android .gitignore

A .gitignore for Android Studio is generally structured around excluding the following four categories:

• Build artifacts and caches Regenerable items that tend to add noisy diffs
• Device- or environment-specific settings Things like SDK paths that are meaningless on other machines
• IDE-generated files and user-specific settings Configuration files automatically generated by Android Studio / IntelliJ
• Sensitive information (especially signing-related) Anything that could cause serious issues if leaked

As a starting point for this way of thinking, many people refer to GitHub’s official Android.gitignore. On Stack Overflow and in Japanese articles as well, it’s common to see advice like “start with this as a base.” (GitHub)

Official References Commonly Used as Standards

GitHub’s Android.gitignore

The Android.gitignore published by GitHub includes items such as the following (summary):

• Gradle-related: .gradle/, build/
• Environment-specific: local.properties
• Android Studio artifacts: captures/, .externalNativeBuild/, .cxx/
• Outputs: *.apk, *.aab, output-metadata.json
• IntelliJ / Android Studio: *.iml, .idea/
• Signing keys: *.jks, *.keystore
• Firebase / Google: google-services.json
• Profiles: *.hprof

This aligns with the overall philosophy of GitHub’s gitignore repository as a whole, and the stance of “base your setup on the official template” is widely supported. (GitHub)

JetBrains’ (IntelliJ / Android Studio) Official View

On the other hand, opinions differ on how to handle the .idea directory.

In JetBrains’ official guide (updated 2025-11-26), the guidance is summarized as follows:

• Contents under .idea are generally OK to share (commit)
• However, user-specific files such as workspace.xml and shelf/ should be excluded
• For Gradle / Maven projects, *.iml and some configuration files are “generated artifacts, so choosing not to share them is also reasonable”

In other words, from JetBrains’ perspective, “ignoring .idea entirely is not necessarily correct,” but they also acknowledge practical flexibility for Gradle-based Android projects. (JetBrains)

Notes When Using Kotlin

The Kotlin Gradle Plugin generates a .kotlin/ directory at the project root. The official documentation explicitly states that this should not be committed.

Therefore, for projects using Kotlin, adding .kotlin/ to .gitignore is standard practice. (Kotlin)

Point of Divergence ①: What to Do with .idea/

In real-world usage, approaches generally fall into two categories:

A) Ignore .idea/ Entirely

• This is the stance taken by GitHub’s Android.gitignore

• Similar examples exist in older AOSP demo projects

• Pros

  • Reduces noise from IDE configuration diffs
  • Less friction when team members use different IDE or plugin setups

• Cons

  • Harder to share run configurations and code style settings

Developers who believe “Gradle defines the source of truth for project structure, and IDE settings vary greatly by individual” often choose this simple approach. (Qiita)

B) Keep Only Shareable Parts of .idea/

• This is JetBrains’ official recommendation

• GitHub’s Global/JetBrains.gitignore also follows a partial-exclusion design

• Pros

  • Easier to standardize code style and run configs across the team

• Cons

  • .idea can become messy due to plugin differences

When Android Studio is used as the team’s standard IDE, this compromise approach is sometimes chosen. (GitHub)

Point of Divergence ②: google-services.json

google-services.json does not contain secret keys themselves, but how to handle it depends on policy.

• Position: OK to commit

  • The information is included in the APK and can be extracted by analysis
  • API keys are assumed to have usage restrictions applied (Google Groups, Stack Overflow)

• Position: Ignore in public / OSS projects

  • Only provide a sample file in the repository
  • Decisions should depend on the visibility of the repository (Reddit, droidcon)

GitHub’s Android.gitignore includes it in the ignore list by default. (GitHub)

A Safe, Practical .gitignore Recommendation

Below is a configuration that:

• Is based on GitHub’s Android.gitignore
• Incorporates official guidance for Kotlin usage

and is easy to adopt as an initial setup.

# ===== OS / editor =====
.DS_Store
Thumbs.db
*.swp
*.swo
 
# ===== Gradle / Kotlin =====
.gradle/
.kotlin/
build/
local.properties
 
# ===== Android Studio / IntelliJ =====
*.iml
.idea/
*.ipr
*.iws
out/
 
# ===== Android build outputs =====
*.apk
*.aab
output-metadata.json
 
# ===== Android Studio generated =====
captures/
.externalNativeBuild/
.cxx/
 
# ===== Profiling =====
*.hprof
 
# ===== Signing / secrets =====
*.jks
*.keystore
keystore.properties
signing.properties
 
# ===== Google Services (decide by policy) =====
# google-services.json

This setup is considered a safe choice in many teams because it “keeps diffs under control and avoids unnecessary conflicts.” (GitHub)

A Compromise When You Want to Share .idea/

Another approach is to avoid ignoring .idea entirely, and instead exclude only user-specific files and generated artifacts.

.idea/**/workspace.xml
.idea/**/usage.statistics.xml
.idea/**/shelf/
 
.idea/**/tasks.xml
.idea/**/dictionaries/
 
.idea/**/modules.xml
.idea/**/gradle.xml
.idea/**/libraries/
 
*.iml

This is a realistic compromise that combines JetBrains’ official policy with the realities of Gradle projects. (JetBrains)

Convenient Ways to Generate .gitignore

If you want to specify multiple OSes and tools at once, gitignore.io (provided by Toptal) is convenient.

curl -L "https://www.toptal.com/developers/gitignore/api/android,androidstudio,gradle,kotlin,macos,windows,linux" > .gitignore

(Toptal)

Common Pitfalls

• Adding something to .gitignore does not remove files that are already tracked → You need git rm --cached (Stack Overflow)

• For google-services.json:

  • Needs to be shared within the team → commit it

  • Public / OSS → ignore it + provide a sample This branching strategy is realistic. (Google Groups)