git-worktree — управление несколькими рабочими каталогами

Управление несколькими рабочими каталогами, присоединёнными к одному репозиторию.

Репозиторий git может поддерживать несколько рабочих каталогов, позволяя вам переключать более одной ветки одновременно. С помощью git worktree add с репозиторием связывается новый рабочий каталог вместе с дополнительными метаданными, которые отличают этот рабочий каталог от других в том же репозитории. Рабочий каталог вместе с этими метаданными называется "рабочим каталогом (worktree)".

Этот новый рабочий каталог называется "связанным рабочим каталогом" в отличие от "основного рабочего каталога", подготовленного git-init[1] или git-clone[1]. Репозиторий имеет один основной рабочий каталог (если это не голый репозиторий) и ноль или более связанных рабочих каталогов. Когда вы закончили работу со связанным рабочим каталогом, удалите его с помощью git worktree remove.

В своей простейшей форме git worktree add <путь> автоматически создаёт новую ветку, имя которой является последним компонентом <пути>, что удобно, если вы планируете работать над новой темой. Например, git worktree add ../hotfix создаёт новую ветку hotfix и переключает её по пути ../hotfix. Чтобы вместо этого работать над существующей веткой в новом рабочем каталоге, используйте git worktree add <путь> <ветка>. С другой стороны, если вы просто планируете внести некоторые экспериментальные изменения или выполнить тестирование, не нарушая существующую разработку, часто удобно создать "одноразовый" рабочий каталог, не связанный ни с какой веткой. Например, git worktree add -d <путь> создаёт новый рабочий каталог с отсоединённым HEAD в том же коммите, что и текущая ветка.

Если рабочий каталог удалён без использования git worktree remove, то его связанные служебные файлы, которые находятся в репозитории (см. "ПОДРОБНОСТИ" ниже), в конечном итоге будут удалены автоматически (см. gc.worktreePruneExpire в git-config[1]), или вы можете выполнить git worktree prune в основном или любом связанном рабочем каталоге, чтобы очистить устаревшие служебные файлы.

Если рабочий каталог для связанного рабочего каталога хранится на портативном устройстве или сетевом ресурсе, который подключён не всегда, вы можете предотвратить подчистку его служебных файлов, выполнив команду git worktree lock, опционально указав --reason, чтобы объяснить, почему рабочий каталог заблокирован.

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

В общем, все псевдоссылки относятся к рабочему каталогу, а все ссылки, начинающиеся с refs/, являются общими. Псевдоссылки — это такие ссылки, как HEAD, которые находятся непосредственно в $GIT_DIR, а не внутри $GIT_DIR/refs. Однако есть исключения: ссылки внутри refs/bisect, refs/worktree и refs/rewritten не являются общими.

К ссылкам, относящимся к рабочему каталогу, всё равно можно получить доступ из другого рабочего каталога через два специальных пути: main-worktree и worktrees. Первый предоставляет доступ к ссылкам основного рабочего каталога, а второй — ко всем связанным рабочим каталогам.

Например, main-worktree/HEAD или main-worktree/refs/bisect/good преобразуются в то же значение, что и HEAD основного рабочего каталога и refs/bisect/good соответственно. Аналогично, worktrees/foo/HEAD или worktrees/bar/refs/bisect/bad совпадают с $GIT_COMMON_DIR/worktrees/foo/HEAD и $GIT_COMMON_DIR/worktrees/bar/refs/bisect/bad.

Для доступа к ссылкам лучше не заглядывать внутрь $GIT_DIR напрямую. Вместо этого используйте такие команды, как git-rev-parse[1] или git-update-ref[1], которые будут правильно обрабатывать ссылки.

По умолчанию файл config репозитория является общим для всех рабочих каталогов. Если переменные конфигурации core.bare или core.worktree присутствуют в общем файле конфигурации и extensions.worktreeConfig отключён, то они будут применяться только к основному рабочему каталогу.

Чтобы иметь конфигурацию, специфичную для рабочего каталога, вы можете включить расширение worktreeConfig, например:

В этом режиме специфическая конфигурация хранится по пути, на который указывает git rev-parse --git-path config.worktree. Вы можете добавлять или обновлять конфигурацию в этом файле с помощью git config --worktree. Более старые версии Git откажутся от доступа к репозиториям с этим расширением.

Обратите внимание, что в этом файле исключение для core.bare и core.worktree отсутствует. Если они существуют в $GIT_DIR/config, вы должны переместить их в config.worktree основного рабочего каталога. Вы также можете воспользоваться этой возможностью, чтобы просмотреть и переместить другую конфигурацию, которую вы не хотите распространять на все рабочие каталоги:

Более подробную информацию см. в документации по extensions.worktreeConfig в git-config[1].

Каждый связанный рабочий каталог имеет частный подкаталог в каталоге $GIT_DIR/worktrees репозитория. Имя частного подкаталога обычно является базовым именем пути связанного рабочего каталога, возможно, с добавленным номером для обеспечения уникальности. Например, когда $GIT_DIR=/path/main/.git, команда git worktree add /path/other/test-next next создаёт связанный рабочий каталог в /path/other/test-next, а также создаёт каталог $GIT_DIR/worktrees/test-next (или $GIT_DIR/worktrees/test-next1, если test-next уже занято).

Внутри связанного рабочего каталога $GIT_DIR устанавливается так, чтобы указывать на этот частный каталог (например, /path/main/.git/worktrees/test-next в примере), а $GIT_COMMON_DIR устанавливается так, чтобы указывать обратно на $GIT_DIR основного рабочего каталога (например, /path/main/.git). Эти настройки производятся в файле .git, расположенном в верхнем каталоге связанного рабочего каталога.

Разрешение пути с помощью git rev-parse --git-path использует либо $GIT_DIR, либо $GIT_COMMON_DIR в зависимости от пути. Например, в связанном рабочем каталоге git rev-parse --git-path HEAD возвращает /path/main/.git/worktrees/test-next/HEAD (не /path/other/test-next/.git/HEAD или /path/main/.git/HEAD), в то время как git rev-parse --git-path refs/heads/master использует $GIT_COMMON_DIR и возвращает /path/main/.git/refs/heads/master, поскольку ссылки являются общими для всех рабочих каталогов, за исключением refs/bisect, refs/worktree и refs/rewritten.

Дополнительную информацию см. в gitrepository-layout[5]. Эмпирическое правило: не делайте никаких предположений о том, принадлежит ли путь $GIT_DIR или $GIT_COMMON_DIR, когда вам нужно напрямую получить доступ к чему-либо внутри $GIT_DIR. Используйте git rev-parse --git-path, чтобы получить окончательный путь.

Если вы вручную перемещаете связанный рабочий каталог, вам нужно обновить файл gitdir в каталоге записи. Например, если связанный рабочий каталог перемещён в /newpath/test-next, и его файл .git указывает на /path/main/.git/worktrees/test-next, то обновите /path/main/.git/worktrees/test-next/gitdir, чтобы он ссылался на /newpath/test-next. Ещё лучше выполните git worktree repair, чтобы автоматически восстановить связь.

Чтобы предотвратить подчистку записи $GIT_DIR/worktrees (что может быть полезно в некоторых ситуациях, например, когда рабочий каталог записи хранится на портативном устройстве), используйте команду git worktree lock, которая добавляет файл с именем locked в каталог записи. Файл содержит причину в обычном тексте. Например, если файл .git связанного рабочего каталога указывает на /path/main/.git/worktrees/test-next, то файл с именем /path/main/.git/worktrees/test-next/locked предотвратит подчистку записи test-next. Подробности см. в gitrepository-layout[5].

Когда extensions.worktreeConfig включён, файл конфигурации .git/worktrees/<id>/config.worktree читается после .git/config.

Команда worktree list имеет два формата вывода. Формат по умолчанию показывает подробности в одной строке с колонками. Например:

Команда также показывает аннотации для каждого рабочего каталога в соответствии с его состоянием. Эти аннотации:

Для этих аннотаций также может быть доступна причина, и её можно увидеть, используя подробный режим. Затем аннотация перемещается на следующую строку с отступом, за которым следует дополнительная информация.

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

Вы находитесь в середине сеанса рефакторинга, и ваш начальник входит и требует, чтобы вы немедленно что-то исправили. Обычно вы можете использовать git-stash[1], чтобы временно сохранить ваши изменения, однако ваш рабочий каталог находится в таком состоянии беспорядка (с новыми, перемещёнными и удалёнными файлами, а также другими разбросанными частями), что вы не хотите рисковать, нарушая что-либо. Вместо этого вы создаёте временный связанный рабочий каталог, чтобы сделать срочное исправление, удаляете его, когда закончите, а затем возобновляете предыдущий сеанс рефакторинга.

Дальнейшее содержание этого раздела, повторяет то, что может быть найдено в git-config[1]:

Множественное переключение в целом всё ещё является экспериментальным, и поддержка подмодулей неполна. НЕ рекомендуется выполнять множественное переключение суперпроекта.

Является частью пакета git[1]