Полное руководство по .gitignore для Android Studio

Правильный подход к файлам .gitignore в Android Studio зависит от структуры проекта и предпочтений команды, но общее мнение заключается в том, что файлы .iml следует игнорировать в .gitignore, несмотря на то, что некоторая более старая документация говорит об обратном. Android Studio автоматически генерирует эти файлы на основе конфигурации Gradle, что делает их избыточными для системы контроля версий.

Содержание

• Понимание дилеммы файлов .iml
• Полный шаблон .gitignore для Android Studio
• Ключевые категории файлов для игнорирования
• Когда стоит рассмотреть включение файлов .iml
• Практические шаги по реализации
• Распространенные проблемы и решения с .gitignore

Понимание дилеммы файлов .iml

Путаница вокруг файлов .iml возникает из-за исторической документации IntelliJ, которая предлагала включать их в систему контроля версий. Однако современный консенсус среди Android-разработчиков иным:

Вы не хотите коммитить эти файлы, потому что они актуальны только для вашей настройки и текущей работы. Вам не нужны из них ни один — правильная конфигурация Gradle выполнит всю работу за вас, так как это инструмент сборки со строгой структурой.

Согласно обсуждениям на Reddit, файлы .iml специфичны для IDE и должны игнорироваться, потому что:

• Они содержат пути, специфичные для вашей локальной среды разработки
• Android Studio автоматически генерирует их на основе конфигурации Gradle
• Они не содержат важной информации о проекте, которую Gradle уже не управляет
• Их совместное использование может вызывать конфликты между разными настройками разработчиков

Однако некоторые команды выбирают совместное использование файлов .iml, особенно для сложных многомодульных проектов, где файлы содержат важные отношения между модулями.

Полный шаблон .gitignore для Android Studio

На основе результатов исследований, вот комплексный шаблон .gitignore для проектов Android Studio:

# Файлы Gradle
.gradle/
build/
app/build
*/build/

# Локальный файл конфигурации (путь к SDK и т.д.)
local.properties

# Файлы Android Studio и IntelliJ IDEA
.idea/
*.iml
*.iws
*.ipr

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

# Файлы хранилища ключей
*.jks
*.keystore

# Файлы логов
*.log

# Файлы ОС
.DS_Store
Thumbs.db
ehthumbs.db

# Скомпилированные файлы приложения
*.apk
*.ap_
*.aab
*.dex

# Файлы классов Java
*.class

# Android NDK
ndkBuild/
local.properties

# Файлы конфигурации Proguard
proguard-rules.pro

# Конфигурации Crashlytics
com_crashlytics_export_strings.xml

# Временные файлы редактора навигации
.navigation/

# Папка captures
captures/

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

# CMake
CMakeLists.txt.txt

Ключевые категории файлов для игнорирования

Артефакты сборки и сгенерированные файлы

# Скомпилированные файлы приложения
*.apk
*.ap_
*.aab
*.dex

# Файлы классов Java
*.class

# Сгенерированные файлы
bin/
gen/
out/

Эти файлы автоматически генерируются системой сборки и не нуждаются в контроле версий.

Файлы, связанные с Gradle

# Файлы Gradle
.gradle/
build/
app/build
*/build/

Официальная документация Android рекомендует исключать каталоги сборки, так как они содержат скомпилированный код, который может быть регенерирован.

Файлы конфигурации IDE

# Файлы Android Studio и IntelliJ IDEA
.idea/
*.iml
*.iws
*.ipr

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

Как отмечено в обсуждении на Stack Overflow, эти файлы содержат пользовательские настройки и конфигурации IDE, которые не должны совместно использоваться.

Локальная и конфиденциальная конфигурация

# Локальный файл конфигурации (путь к SDK и т.д.)
local.properties

# Файлы хранилища ключей
*.jks
*.keystore

# Конфигурации Crashlytics
com_crashlytics_export_strings.xml

Эти файлы часто содержат конфиденциальную информацию, такую как пути к SDK и пароли от хранилищ ключей, которые не должны коммититься в систему контроля версий.

Когда стоит рассмотреть включение файлов .iml

Хотя большинство современных Android-проектов должны игнорировать файлы .iml, существуют конкретные сценарии, когда их включение может быть полезным:

1. Многомодульные проекты: При работе со сложными зависимостями модулей, файлы .iml могут помочь поддерживать отношения между модулями
2. Устаревшие проекты: Старые проекты, созданные до того как Gradle стал стандартом, могут полагаться на файлы .iml
3. Единообразие команды: Если ваша команда выработала рабочие процессы вокруг совместно используемых файлов .iml

Однако даже в этих случаях многие команды успешно переходят от зависимости от файлов .iml, правильно настраивая зависимости модулей Gradle.

Практические шаги по реализации

Создание файла .gitignore

1. Создайте файл .gitignore в корневом каталоге вашего проекта
2. Скопируйте приведенный выше шаблон или используйте встроенный генератор Android Studio
3. Зафиксируйте файл .gitignore в вашем репозитории

Удаление существующих файлов из Git

Если у вас уже есть файлы в репозитории, которые должны игнорироваться:

# Удалить все файлы .iml из git, но оставить их локально
git ls-files | grep "\.iml$" | xargs git rm --cached

# Удалить все каталоги сборки
git rm -r --cached build/
git rm -r --cached app/build/

# Зафиксировать изменения
git add .gitignore
git commit -m "Добавить комплексный gitignore для Android Studio"

Использование генераторов Gitignore

Вы также можете использовать онлайн-генераторы, такие как gitignore.io, для создания специализированных файлов .gitignore:

Добавьте Gradle, Intellij и Android, и вы готовы к работе. Возможно, потребуется изменить на *.iml для игнорирования всех файлов iml.

Распространенные проблемы и решения с .gitignore

Файлы .iml все еще отслеживаются

Если файлы .iml все еще отслеживаются, несмотря на наличие их в .gitignore:

1. Проверьте, что шаблон правильный (должен быть *.iml)
2. Удалите существующие файлы из кэша git, как показано выше
3. Убедитесь, что в вашем файле .gitignore нет опечаток

Артефакты сборки все еще коммитятся

Если файлы сборки все еще коммитируются:

1. Убедитесь, что шаблоны .gradle/ и build/ правильные
2. Проверьте наличие любых специфичных для проекта каталогов сборки
3. Обновите ваш .gitignore, чтобы включить все связанные со сборкой шаблоны

Файлы, специфичные для IDE, все еще отслеживаются

Для постоянных проблем с файлами IDE:

1. Рассмотрите использование встроенных настроек контроля версий Android Studio
2. Проверьте раздел “Игнорируемые файлы” в Настройки > Контроль версий
3. Убедитесь, что все подкаталоги .idea/ правильно игнорируются

Источники

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

Заключение

Современный подход к файлам .gitignore в Android Studio — исключать файлы .iml вместе с другими сгенерированными файлами, артефактами сборки и конфигурациями, специфичными для IDE. Этот подход обеспечивает:

• Чистые, последовательные репозитории среди членов команды
• Сокращение конфликтов слияния из-за файлов, специфичных для IDE
• Более быстрое клонирование и получение версий
• Лучшее разделение между кодом и сгенерированными артефактами

Для большинства Android-проектов предоставленный выше комплексный шаблон обработает все необходимые исключения. Однако всегда учитывайте специфические потребности вашей команды и структуру проекта при настройке вашего файла .gitignore. В случае сомнений следуйте принципу исключения всего, что может быть автоматически сгенерировано системой сборки или IDE.