gitmodules

Название

gitmodules — определение свойств подмодулей

Краткое описание

$GIT_WORK_TREE/.gitmodules

Описание

Файл .gitmodules, расположенный в каталоге верхнего уровня рабочего дерева Git, является текстовым файлом с синтаксисом, соответствующим требованиям git-config[1].

Файл содержит по одному подразделу для каждого подмодуля, а значение подраздела — имя подмодуля. В качестве имени задаётся путь, по которому был добавлен подмодуль, если оно не было изменено с помощью параметра --name команды git submodule add. В каждом разделе подмодуля также содержатся следующие обязательные ключи:

submodule.<name>.path: Определяет путь относительно каталога верхнего уровня рабочего дерева Git, по которому должен быть извлечён подмодуль. Имя пути не должно оканчиваться на /. Все пути подмодулей в файле .gitmodules должны быть уникальными.
submodule.<name>.url: Определяет URL, по которому можно клонировать репозиторий подмодуля. Это может быть либо абсолютный URL, готовый для передачи команде git-clone[1], либо (если он начинается с ./ или ../) путь относительно исходного репозитория суперпроекта.

Кроме того, есть несколько необязательных ключей:

submodule.<name>.update

Определяет процедуру обновления по умолчанию для указанного подмодуля, то есть способ обновления подмодуля командой git submodule update в суперпроекте. Используется только командой git submodule init для инициализации одноимённой переменной конфигурации. Допустимые значения: checkout, rebase, merge или none, но не !command (по соображениям безопасности). Подробнее см. описание команды update в git-submodule[1].

submodule.<name>.branch

Имя удалённой ветки для отслеживания обновлений вышестоящего подмодуля. Если параметр не указан, по умолчанию используется удалённый репозиторий HEAD. Специальное значение . указывает, что имя ветки в подмодуле должно совпадать с именем текущей ветки в текущем репозитории. Подробнее см. документацию к --remote в git-submodule[1].

submodule.<name>.fetchRecurseSubmodules

Этот параметр позволяет управлять рекурсивной выборкой данных для данного подмодуля. Если этот параметр также присутствует в записи подмодуля в .git/config суперпроекта, значение в ней переопределяет значение из .gitmodules. Оба значения можно переопределить в командной строке с помощью параметра --[no-]recurse-submodules для команд git fetch и git pull.

submodule.<name>.ignore

Определяет, при каких обстоятельствах git status и семейство команд diff показывают подмодуль как изменённый. Поддерживаются следующие значения:

all: Подмодуль никогда не будет считаться изменённым (но всё равно появится в выводе status и commit, если он был добавлен в индекс). Добавление подмодуля с помощью (new commits) можно принудительно выполнить с помощью git add --force <submodule.path>. Этот параметр влияет на команды status, update-index, diff и log (из-за лежащей в их основе команды diff).
dirty: Все изменения рабочего дерева подмодуля игнорируются; учитываются только зафиксированные различия между HEAD подмодуля и его состоянием, записанным в суперпроекте.
untracked: Игнорируются только неотслеживаемые файлы в подмодулях. Зафиксированные различия и изменения отслеживаемых файлов будут отображаться.
none: Изменения в подмодулях не игнорируются: отображаются все зафиксированные различия, а также изменения отслеживаемых и неотслеживаемых файлов. Это значение используется по умолчанию.

Если этот параметр также присутствует в записи подмодуля в .git/config суперпроекта, значение в ней переопределяет значение из .gitmodules.

Оба значения можно переопределить в командной строке с помощью параметра --ignore-submodules. На команды git submodule этот параметр не влияет.

submodule.<name>.shallow

Если установлено значение true, подмодуль будет клонирован поверхностно (с глубиной истории 1), если только пользователь явно не запросит обычное клонирование.

Примечания

Git не разрешает использовать символическую ссылку в качестве файла .gitmodules в рабочем дереве и откажется извлекать такой элемент дерева. Это обеспечивает согласованное поведение при доступе к файлу через индекс или дерево и через файловую систему, а также помогает Git надёжно выполнять проверки безопасности содержимого файла.

Примеры

Рассмотрим следующий файл .gitmodules:

[submodule "libfoo"]
        path = include/foo
        url = git://foo.com/git/lib.git

[submodule "libbar"]
        path = include/bar
        url = git://bar.com/git/lib.git

В нём определены два подмодуля: libfoo и libbar. Предполагается, что они будут извлечены в пути include/foo и include/bar; для обоих подмодулей указан URL, который можно использовать для их клонирования.

См. также

git-submodule[1], gitsubmodules[7], git-config[1]

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/gitmodules