Для чего нужен файл gitignore
Часто при работе над проектом, использующим Git, вы хотите исключить передачу определенных файлов или каталогов в удаленный репозиторий.
Файл .gitignore указывает, какие неотслеживаемые файлы должен игнорировать Git .
Какие файлы следует игнорировать?
Игнорируемые файлы обычно представляют собой файлы, специфичные для платформы, или автоматически созданные из сборочных систем. Ниже приводятся некоторые общие примеры:
- Runtime файлы, такие как log , lock , cache или временные файлы ( tmp ).
- Файлы с конфиденциальной информацией, такие как пароли или ключи API.
- Каталоги зависимостей, такие как /vendor или /node_modules .
- Build каталоги, такие как /public или /dist .
- Системные файлы, такие как .DS_Store или Thumbs.db
- Конфигурационные файлы IDE или текстового редактора.
Шаблоны .gitignore
.gitignore - это простой текстовый файл, в каждой строке которого содержится шаблон файла или каталога, который необходимо проигнорировать.
.gitignore использует glob шаблоны для сопоставления имен файлов с символами подстановки (Это что-то вроде регулярных выражений). Если у вас есть файлы или каталоги, содержащие шаблон подстановки (например * ), вы можете использовать один обратный слеш ( \* ), чтобы экранировать такой символ.
Комментарии
Символ косой черты ( / ) представляет собой разделитель каталогов. Наклонная черта в начале шаблона относится к директории, в которой находится файл .gitignore .
Если шаблон начинается со слеша, то он соответствует файлам и каталогам только в корне хранилища.
Если шаблон не начинается со слэша, он соответствует файлам и каталогам в любом каталоге или подкаталоге.
Если шаблон заканчивается косой чертой, то он соответствует только каталогам. Когда каталог игнорируется, все его файлы и подкаталоги также игнорируются.
Имена файлов
Самый простой шаблон - это просто имя файла без каких-либо специальных символов.
| Шаблон | Примеры совпадений |
|---|---|
| /access.log | access.log |
| access.log | access.log logs/access.log var/logs/access.log |
| build/ | build |
Символы подстановки
* - Символ звездочки соответствует нулю или более символам.
| ШАБЛОН | ПРИМЕРЫ СОВПАДЕНИЙ |
|---|---|
| *.log | error.log logs/debug.log build/logs/error.log |
** - Два соседних символа звездочки соответствуют любому файлу или нулю или более каталогам. Когда за ним следует косая черта ( / ), она соответствует только каталогам.
| ШАБЛОН | ПРИМЕРЫ СОВПАДЕНИЙ |
|---|---|
| logs/** | Совпадает со всем, что находится в каталоге logs. |
| **/build | var/build pub/build build |
| foo/**/bar | foo/bar foo/a/bar foo/a/b/c/bar |
? - Вопросительный знак соответствует любому отдельному символу.
| ШАБЛОН | ПРИМЕРЫ СОВПАДЕНИЙ |
|---|---|
| access?.log | access0.log access1.log accessA.log |
| foo?? | fooab foo23 foo0s |
Квадратные скобки
[…] - Совпадает с любыми символами, заключенными в квадратные скобки. Когда два символа разделены дефисом - обозначает диапазон символов. Диапазон включает в себя все символы, находящиеся между этими двумя символами. Диапазон может быть алфавитным или цифровым.
Если первый символ после [ является восклицательным знаком ( ! ), то образец соответствует любому символу, кроме символов из указанного набора.
| ШАБЛОН | ПРИМЕРЫ СОВПАДЕНИЙ |
|---|---|
| *.[oa] | file.o file.a |
| *.[!oa] | file.s file.1 file.0 |
| access.1.log | access.0.log access.1.log access.2.log |
| file.[a-c].out | file.a.out file.b.out file.c.out |
| file.[a-cx-z].out | file.a.out file.b.out file.c.out file.x.out file.y.out file.z.out |
| access.[!0-2].log | access.3.log access.4.log access.Q.log |
Исключающие шаблоны
Шаблон, начинающийся с восклицательного знака ( ! ), отменяет (повторно включает) любой файл, игнорируемый предыдущей шаблоном. Исключением из этого правила является повторное включение файла, если его родительский каталог исключен.
| ШАБЛОН | ПРИМЕРЫ СОВПАДЕНИЙ |
|---|---|
| *.log !error.log | error.log or logs/error.log will not be ignored |
Пример .gitignore
Локальный .gitignore
Локальный файл .gitignore обычно помещается в корневую директорию хранилища. Однако вы можете создать несколько файлов .gitignore в различных подкаталогах в вашем репозитории. Шаблоны в файлах .gitignore сопоставляются относительно директории, в которой находится файл.
Шаблоны, определенные в файлах, которые находятся в каталогах нижнего уровня (подкаталогах), имеют приоритет перед файлами в каталогах верхнего уровня.
Локальные .gitignore файлы делятся с другими разработчиками и должны содержать шаблоны, полезные для всех остальных пользователей репозитория.
Персональные правила игнорирования
Шаблоны, специфичные для вашего локального репозитория и не подлежащие распространению в других репозиториях, должны быть установлены в файле .git/info/exclude .
Например, этот файл можно использовать для игнорирования сгенерированных файлов из ваших личных инструментов проекта.
Глобальный .gitignore
Git также позволяет вам создать глобальный файл .gitignore , в котором вы можете определить правила игнорирования для каждого Git-репозитория вашей локальной системы.
Файл может называться по вашему усмотрению и храниться в любом месте. Наиболее распространенным местом хранения этого файла является домашний каталог. Вам придется вручную создать файл и настроить Git для его использования.
Например, чтобы установить
/.gitignore_global в качестве глобального файла игнорирования Git, выполните следующие действия:
1. Создайте файл:
2. Добавьте этот файл в Git-конфигурацию:
3. Откройте файл в текстовом редакторе и добавьте в него свои правила.
Глобальные правила особенно полезны при игнорировании определенных файлов, которые вы никогда не захотите фиксировать, таких как файлы с конфиденциальной информацией или скомпилированные исполняемые файлы.
Игнорирование ранее зафиксированных файлов
Файлы в вашей рабочей копии могут отслеживаться или не отслеживаться.
Чтобы проигнорировать файл, который был ранее зафиксирован, вам нужно будет удалить его из индекса, а затем добавить правило для файла в .gitignore :
Опция --cached говорит не удалять файл из рабочего дерева, а только удалять его из индекса.
Для рекурсивного удаления каталога используйте параметр -r :
Если вы хотите удалить файл как из индексной, так и из локальной файловой системы, опустите опцию --cached .
При рекурсивном удалении файлов используйте опцию -n , которая выполнит пробный запуск и покажет, какие файлы будут удалены:
Отладка файла .gitignore
Иногда бывает сложно определить, почему тот или иной файл игнорируется, особенно если вы используете несколько файлов .gitignore или сложные шаблоны. В этом случае пригодится команда git check-ignore с опцией -v, которая указывает на то, что нужно отображать детали совпадающего шаблона.
Например, чтобы проверить, почему файл www/yarn.lock игнорируется, нужно выполнить следующее:
На выходе отображается путь к файлу игнорирования, номер соответствующей линии и фактический шаблон.
Команда также принимает в качестве аргументов более одного имени файла, и файл не обязательно должен существовать в рабочем дереве.
Отображение всех игнорируемых файлов
Команда git status с опцией -ignored отображает список всех проигнорированных файлов:
Заключение
Файл игнорирования .gitignore позволяет исключить файлы из проверки в репозитории. Файл содержит шаблоны, которые описывают, какие файлы и каталоги следует игнорировать.
Мы конечно могли бы вручную добавлять нужные файлы в репозиторий, например так:
Однако это было бы очень трудоемко. Гораздо проще использовать команду:
Которая добавит все файлы в каталоге проекта.
Но что если нам не нужны абсолютно все файлы, а есть файлы например в каталоге /cache или /images или /runtime проекта, которые генерируются в процессе работы. Они не должны быть добавлены в репозиторий.
Тут нам и нужен .gitignore. Вам нужно его самим создать и разместить в корне проекта либо нужной подпапке.
Где должен находиться этот файл
Файл может находиться в корне проекта или любом подкаталоге.
Либо можно задать глобальный файл gitignore, таким образом:
Таким образом вы сможете записать в глобальный файл
/.gitignore_global настройки, общие для всех ваших проектов. В нем могут храниться например файлы для игнорирования, которые специфичны для вашей IDE, и по этому не логично добавлять их в репозиторий. Однако файлы, которые специфичны для конкретного проекта, обязательно нужно добавлять в .gitignore самого проекта.
Примеры содержимого .gitignore файла
Подробнее о шаблонах игнорирования
| Шаблон | Примеры соответствия | Пояснение* |
|---|---|---|
| **/logs | logs/debug.log logs/monday/foo.bar build/logs/debug.log | Добавьте в начало шаблона две звездочки, чтобы сопоставлять каталоги в любом месте репозитория. |
| **/logs/debug.log | logs/debug.log build/logs/debug.log но не logs/build/debug.log | Две звездочки можно также использовать для сопоставления файлов на основе их имени и имени родительского каталога. |
| *.log | debug.log foo.log .log logs/debug.log | Одна звездочка — это подстановочный знак, который может соответствовать как нескольким символам, так и ни одному. |
| *.log !important.log | debug.log trace.log но не important.log logs/important.log | Добавление восклицательного знака в начало шаблона отменяет действие шаблона. Если файл соответствует некоему шаблону, но при этом также соответствует отменяющему шаблону, указанному после, такой файл не будет игнорироваться. |
| .log !important/.log trace.* | debug.log important/trace.log но не important/debug.log | Шаблоны, указанные после отменяющего шаблона, снова будут помечать файлы как игнорируемые, даже если ранее игнорирование этих файлов было отменено. |
| /debug.log | debug.log но не logs/debug.log | Косая черта перед именем файла соответствует файлу в корневом каталоге репозитория. |
| debug.log | debug.log logs/debug.log | По умолчанию шаблоны соответствуют файлам, находящимся в любом каталоге |
| debug?.log | debug0.log debugg.log но не debug10.log | Знак вопроса соответствует строго одному символу. |
| debug7.log | debug0.log debug1.log но не debug10.log | Квадратные скобки можно также использовать для указания соответствия одному символу из заданного диапазона. |
| debug[01].log | debug0.log debug1.log но не debug2.log debug01.log | Квадратные скобки соответствуют одному символу из указанного набора. |
| debug[!01].log | debug2.log но не debug0.log debug1.log debug01.log | Восклицательный знак можно использовать для указания соответствия любому символу, кроме символов из указанного набора. |
| debug[a-z].log | debuga.log debugb.log но не debug1.log | Диапазоны могут быть цифровыми или буквенными. |
| logs | logs logs/debug.log logs/latest/foo.bar build/logs build/logs/debug.log | Без косой черты в конце этот шаблон будет соответствовать и файлам, и содержимому каталогов с таким именем. В примере соответствия слева игнорируются и каталоги, и файлы с именем logs |
| logs/ | logs/debug.log logs/latest/foo.bar build/logs/foo.bar build/logs/latest/debug.log | Косая черта в конце шаблона означает каталог. Все содержимое любого каталога репозитория, соответствующего этому имени (включая все его файлы и подкаталоги), будет игнорироваться |
| logs/ !logs/important.log | logs/debug.log logs/important.log | Минуточку! Разве файл logs/important.log из примера слева не должен быть исключен нз списка игнорируемых? Нет! Из-за странностей Git, связанных с производительностью, вы не можете отменить игнорирование файла, которое задано шаблоном соответствия каталогу |
| logs/**/debug.log | logs/debug.log logs/monday/debug.log logs/monday/pm/debug.log | Две звездочки соответствуют множеству каталогов или ни одному. |
| logs/*day/debug.log | logs/monday/debug.log logs/tuesday/debug.log but not logs/latest/debug.log | Подстановочные символы можно использовать и в именах каталогов. |
| logs/debug.log | logs/debug.log но не debug.log build/logs/debug.log | Шаблоны, указывающие на файл в определенном каталоге, задаются относительно корневого каталога репозитория. (При желании можно добавить в начало косую черту, но она ни на что особо не повлияет.) |
Что если файлы из gitignore уже добавлены в репозиторий
Обратите внимание, что если файлы уже добавлены в git репозиторий, то добавление их в .gitignore не удалит эти файлы. Изменения в них будут продолжать отслеживаться и входить в коммиты, несмотря на то, что они есть в .gitignore .
Нам придется вручную их удалить из репозитория.
Очень удобная команда bash, которая удалит из git репозитория те файлы, которые содержатся в файлах .gitignore :
То же самое для Powershell
При выполнении этой команды, файлы останутся у вас на диске, однако из репозитория они будут удалены.
Либо можно удалять файлы вручную, таким образом:
Либо если нам нужно удалить целую директорию из git, то воспользуемся следующей командой:
Либо так мы могли бы удалить все файлы с расширением .log в папке log:
Параметр --cached означает, что файлы будут удалены только из раздела "проиндексированных файлов". На диске (рабочем каталоге) они останутся нетронутыми.
Как понять, почему игнорируется конкретный файл
Запустите команду вместо path/to/file следует указать путь к файлу.
В итоге мы получим ответ, в котором содержится конкретная строка .gitignore, благодаря которой данный файл игнорируется.
Git рассматривает каждый файл в вашей рабочей копии как файл одного из трех нижеуказанных типов.
- Отслеживаемый файл — файл, который был предварительно проиндексирован или зафиксирован в коммите.
- Неотслеживаемый файл — файл, который не был проиндексирован или зафиксирован в коммите.
- Игнорируемый файл — файл, явным образом помеченный для Git как файл, который необходимо игнорировать.
Игнорируемые файлы — это, как правило, артефакты сборки и файлы, генерируемые машиной из исходных файлов в вашем репозитории, либо файлы, которые по какой-либо иной причине не должны попадать в коммиты. Вот некоторые распространенные примеры таких файлов:
- кэши зависимостей, например содержимое /node_modules или /packages ;
- скомпилированный код, например файлы .o , .pyc и .class ;
- каталоги для выходных данных сборки, например /bin , /out или /target ;
- файлы, сгенерированные во время выполнения, например .log , .lock или .tmp ;
- скрытые системные файлы, например .DS_Store или Thumbs.db ;
- личные файлы конфигурации IDE, например .idea/workspace.xml .
Игнорируемые файлы отслеживаются в специальном файле .gitignore , который регистрируется в корневом каталоге репозитория. В Git нет специальной команды для указания игнорируемых файлов: вместо этого необходимо вручную отредактировать файл .gitignore , чтобы указать в нем новые файлы, которые должны быть проигнорированы. Файлы .gitignore содержат шаблоны, которые сопоставляются с именами файлов в репозитории для определения необходимости игнорировать эти файлы.
Шаблоны игнорирования в Git
Для сопоставления с именами файлов в .gitignore используются шаблоны подстановки. С помощью различных символов можно создавать собственные шаблоны.
Две звездочки (**) означают, что ваш файл .gitignore находится в каталоге верхнего уровня вашего репозитория, как указано в соглашении. Если в репозитории несколько файлов .gitignore, просто мысленно поменяйте слова «корень репозитория» на «каталог, содержащий файл .gitignore» (и подумайте об объединении этих файлов, чтобы упростить работу для своей команды)*.
Если у вас есть файлы или каталоги, в имени которых содержатся спецсимволы шаблонов, для экранирования этих спецсимволов в .gitignore можно использовать обратную косую черту (\):
Общие файлы .gitignore в вашем репозитории
Обычно правила игнорирования Git задаются в файле .gitignore в корневом каталоге репозитория. Тем не менее вы можете определить несколько файлов .gitignore в разных каталогах репозитория. Каждый шаблон из конкретного файла .gitignore проверяется относительно каталога, в котором содержится этот файл. Однако проще всего (и этот подход рекомендуется в качестве общего соглашения) определить один файл .gitignore в корневом каталоге. После регистрации файла .gitignore для него, как и для любого другого файла в репозитории, включается контроль версий, а после публикации с помощью команды push он становится доступен остальным участникам команды. В файл .gitignore , как правило, включаются только те шаблоны, которые будут полезны другим пользователям репозитория.
Персональные правила игнорирования в Git
В специальном файле, который находится в папке .git/info/exclude , можно определить персональные шаблоны игнорирования для конкретного репозитория. Этот файл не имеет контроля версий и не распространяется вместе с репозиторием, поэтому он хорошо подходит для указания шаблонов, которые будут полезны только вам. Например, если у вас есть пользовательские настройки для ведения журналов или специальные инструменты разработки, которые создают файлы в рабочем каталоге вашего репозитория, вы можете добавить их в .git/info/exclude , чтобы они случайно не попали в коммит в вашем репозитории.
Глобальные правила игнорирования в Git
Кроме того, для всех репозиториев в локальной системе можно определить глобальные шаблоны игнорирования Git, настроив параметр конфигурации Git core.excludesFile . Этот файл нужно создать самостоятельно. Если вы не знаете, куда поместить глобальный файл .gitignore , расположите его в домашнем каталоге (потом его будет легче найти). После создания этого файла необходимо настроить его местоположение с помощью команды git config :
Будьте внимательны при указании глобальных шаблонов игнорирования, поскольку для разных проектов актуальны различные типы файлов. Типичные кандидаты на глобальное игнорирование — это специальные файлы операционной системы (например, .DS_Store и thumbs.db ) или временные файлы, создаваемые некоторыми инструментами разработки.
Игнорирование ранее закоммиченного файла
Чтобы игнорировать файл, для которого ранее был сделан коммит, необходимо удалить этот файл из репозитория, а затем добавить для него правило в .gitignore . Используйте команду git rm с параметром --cached , чтобы удалить этот файл из репозитория, но оставить его в рабочем каталоге как игнорируемый файл.
Опустите опцию --cached , чтобы удалить файл как из репозитория, так и из локальной файловой системы.
Коммит игнорируемого файла
Можно принудительно сделать коммит игнорируемого файла в репозиторий с помощью команды git add с параметром -f (или --force ):
Этот способ хорош, если у вас задан общий шаблон (например, *.log ), но вы хотите сделать коммит определенного файла. Однако еще лучше в этом случае задать исключение из общего правила:
Этот подход более прозрачен и понятен, если вы работаете в команде.
Скрытие изменений в игнорируем файле
Команда git stash — это мощная функция системы Git, позволяющая временно отложить и отменить локальные изменения, а позже применить их повторно. По умолчанию команда git stash ожидаемо не обрабатывает игнорируемые файлы и создает отложенные изменения только для тех файлов, которые отслеживаются Git. Тем не менее вы можете вызвать команду git stash с параметром --all, чтобы создать отложенные изменения также для игнорируемых и неотслеживаемых файлов.
Отладка файлов .gitignore
Если шаблоны .gitignore сложны или разбиты на множество файлов .gitignore , бывает непросто отследить, почему игнорируется определенный файл. Используйте команду git check-ignore с параметром -v (или --verbose ), чтобы определить, какой шаблон приводит к игнорированию конкретного файла:
При желании команде git check-ignore можно передать несколько имен файлов, причем сами имена могут даже не соответствовать файлам, существующим в вашем репозитории.
В чем смысл .gitignore?
В большинстве проектов есть разница между кодом / конфигурацией и сгенерированные файлы из этого кода или конфигурации. Последнее обычно бесполезно, и его можно игнорировать.
Обычно вы хотите, чтобы код и конфигурация отслеживались только через git. Это связано с тем, что сгенерированные файлы эфемерны, и если вы удалите их, вы можете просто восстановить их снова. Часто нет смысла загружать их, поскольку они просто усложнят ситуацию и вызовут ненужные конфликты слияния.
Это широкое определение, поэтому давайте рассмотрим пример. В проектах Node JS есть папка с именем node_modules, которая содержит все внешние пакеты, которые необходимо запустить вашему коду. Вы можете удалить этот каталог и полностью перестроить его, запустив команду npm install, которая использует конфигурацию package.json для поиска пакетов.
Так какой смысл иметь папку node_modules в Git? На самом деле его нет, так как он более сложный, может вызвать проблемы и даже во многих случаях может значительно увеличить размер репозитория Git.
Если вы проигнорируете весь каталог, все ваши коллеги по-прежнему смогут сгенерировать свою локальную копию из файла package.json. Таким образом, вместо этого в Git следует отслеживать только package.json. Большинство вещей, которые добавляются в .gitignore, следуют этому шаблону. Артефакты сборки, такие как папка ./bin/, не фиксируются, поскольку они являются прямым результатом самого кода.
Для удобства в .gitignore можно добавить и другие вещи. MacOS генерирует системные файлы с именем .DS_store, которые вы всегда можете игнорировать. Возможно, вы храните ключи API в .env /, которые не хотите отслеживать в системе управления версиями, вы тоже можете их добавить. Кеши, журналы и другой вывод обычно можно игнорировать.
Использование .gitignore
Вам нужно будет создать файл с именем .gitignore без расширений в корне вашего проекта, где находится ваш каталог .git. Вы можете сделать это из своего файлового браузера или из командной строки с помощью любого текстового редактора CLI:
Вы можете настроить это разными способами, но основные инструменты, которые у вас есть:
- * подстановочные знаки, которые соответствуют любому тексту и могут использоваться для соответствия любому каталогу или любому файлу независимо от расширения.
- !, который работает как своего рода белый список, который отменяет ранее исключенный файл. Основная проблема заключается в том, что он добавляет файл в белый список только в том случае, если он был напрямую excluded и не будет работать для файлов в каталогах, которые были полностью исключены.
- **, который рекурсивно сопоставляет что-либо с каталогами. Например, ** / *. Json будет соответствовать любому файлу JSON независимо от того, где он находится, а src / ** будет рекурсивно соответствовать каждому файлу в папке. Это полезно, если вы хотите внести в белый список, а не игнорировать весь каталог.
Например, Node JS gitignore может выглядеть следующим образом:
node_modules / build / npm-debug.log .env .env.test .env.production .DS_Store .npm .eslintcache logs / * .log npm-debug.log *
Добавление файлов в белый список с помощью! может быть очень полезным для многих конфигураций. Например, в одном из моих проектов у меня был инструмент steamcmd, который загружает зависимости для игровых серверов из Steam. Этот инструмент упакован в один переносимый исполняемый файл, но он производит огромное количество мусора, который я не хочу отслеживать в Git.
Решением было игнорировать все в папке, но занести исполняемый файл в белый список. Это будет работать для любого переносимого исполняемого файла, который расширяется таким образом или создает в каталоге ненужный мусор.
Проект / steamcmd / **! Project / steamcmd / steamcmd.exe
gitignore также использует некоторые другие Unix шарик шаблоны для сопоставления строк, например вопросительный знак для сопоставления одного символа или [a-z] который будет соответствовать наборам символов.
Вы также можете написать несколько файлов .gitignore, которые могут соответствовать файлам относительно самих себя. На самом деле это не слишком полезно, поскольку вы можете просто включить правила в корневой файл, что легче отслеживать, но в некоторых случаях это может помочь с повторением кода. Однако обходной путь заключается в использовании наборов символов для сопоставления нескольких каталогов. Например, сопоставление каталогов в верхнем и нижнем регистре с помощью набора:
Если у вас возникли проблемы с конфигурацией .gitignore, вы можете отладить ее с помощью команды check-ignore Git:
git check-ignore -v testfile.json
Глобальный .gitignore
Git также имеет глобальную настройку для .gitignore, но в большинстве случаев ее не следует использовать. Это связано с тем, что глобальный .gitignore на вашем компьютере не применяется к вашим коллегам, а только к коммитам, сделанным с помощью вашего экземпляра Git.
Если вы все равно хотите установить его, вы можете сделать это с помощью следующей команды:
Принудительная фиксация или сохранение игнорируемых файлов
git add -f debug.log
Точно так же git stash также может хранить локальные изменения в игнорируемых файлах, что на самом деле может быть полезно, поскольку не повлияет на удаленное репо:
Читайте также: