українська мова ▾ Topics ▾ Latest version ▾ git-worktree last updated in 2.48.0

НАЗВА

git-worktree - Керування кількома робочими деревами

СИНОПСИС

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
		   [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
git worktree list [-v | --porcelain [-z]]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>
git worktree prune [-n] [-v] [--expire <expire>]
git worktree remove [-f] <worktree>
git worktree repair [<path>…​]
git worktree unlock <worktree>

ОПИС

Керуйте кількома робочими деревами, підключеними до одного репозиторію.

Репозиторій git може підтримувати кілька робочих дерев, що дозволяє вам одночасно перевіряти більше однієї гілки. За допомогою команди git worktree add нове робоче дерево пов’язується з репозиторієм разом із додатковими метаданими, які відрізняють це робоче дерево від інших у тому ж репозиторії. Робоче дерево разом із цими метаданими називається "робочим деревом".

Це нове робоче дерево називається "зв’язаним робочим деревом", на відміну від "головного робочого дерева", підготовленого за допомогою 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, щоб пояснити, чому робоче дерево заблоковано.

КОМАНДИ

add <path> [<commit-ish>]

Створіть робоче дерево за адресою <path> та вивантажте в нього <commit-ish>. Нове робоче дерево пов’язане з поточним репозиторієм, надаючи доступ до всього, крім файлів для кожного робочого дерева, таких як HEAD, index тощо. Для зручності <commit-ish> може бути простою символом "-", що є синонімом @{-1}.

Якщо <commit-ish> є назвою гілки (назвемо її <branch>) і не знайдена, і не використовуються ні -b, ні -B, ні --detach, але існує гілка відстеження рівно в одному віддаленому об’єкті (назвемо її <remote>) з відповідним ім’ям, розглядати як еквівалент:

$ git worktree add --track -b <branch> <path> <remote>/<branch>

Якщо гілка існує на кількох віддалених серверах, і одна з них названа змінною конфігурації checkout.defaultRemote, ми використовуватимемо її для усунення неоднозначностей, навіть якщо <branch> не є унікальною на всіх віддалених серверах. Встановіть її, наприклад, на checkout.defaultRemote=origin, щоб завжди отримувати віддалені гілки звідти, якщо <branch> є неоднозначною, але існує на віддаленому сервері origin. Див. також checkout.defaultRemote у git-config[1].

Якщо <commit-ish> пропущено і не використовується ні -b, ні -B, ні --detach, то для зручності нове робоче дерево пов’язується з гілкою (назвемо її <branch>) з назвою $(basename <path>). Якщо <branch> не існує, автоматично створюється нова гілка на основі HEAD, ніби було задано -b <branch>. Якщо <branch> існує, вона буде витягнута з нового робочого дерева, якщо вона не витягнута ніде більше, інакше команда відмовиться створювати робоче дерево (якщо не використовується --force).

Якщо <commit-ish> пропущено, не використовується ні --detach, ні --orphan, і немає дійсних локальних гілок (або віддалених гілок, якщо вказано --guess-remote), тоді, для зручності, нове робоче дерево пов’язується з новою ненародженою гілкою з назвою <branch> (після $(basename <path>), якщо не використовується ні -b, ні -B), ніби --orphan було передано команді. У випадку, якщо репозиторій має віддалену гілку та використовується --guess-remote, але не існує віддалених або локальних гілок, команда не виконується з попередженням, яке нагадує користувачеві спочатку отримати дані зі своєї віддаленої гілки (або перевизначити їх за допомогою -f/--force).

list

Перелічіть деталі кожного робочого дерева. Спочатку перелічено головне робоче дерево, а потім кожне з пов’язаних робочих дерев. Вихідні деталі включають, чи є робоче дерево чистим, яку версію наразі вилучено, яку гілку наразі вилучено (або "відокремлену HEAD", якщо її немає), "заблоковано", якщо робоче дерево заблоковано, "обрізається", якщо робоче дерево можна обрізати командою prune.

lock

Якщо робоче дерево знаходиться на портативному пристрої або мережевому ресурсі, який не завжди змонтовано, заблокуйте його, щоб запобігти автоматичному видаленню адміністративних файлів. Це також запобігає його переміщенню або видаленню. За потреби вкажіть причину блокування за допомогою --reason.

move

Перемістити робоче дерево в нове місце. Зверніть увагу, що головне робоче дерево або пов’язані робочі дерева, що містять підмодулі, не можна перемістити за допомогою цієї команди. (Однак команда git worktree repair може відновити з’єднання зі пов’язаними робочими деревами, якщо ви перемістите головне робоче дерево вручну.)

prune

Вирізати інформацію з робочого дерева в $GIT_DIR/worktrees.

remove

Видалити робоче дерево. Можна видалити лише чисті робочі дерева (без невідстежуваних файлів та без змін у відстежуваних файлах). Нечисті робочі дерева або ті, що містять підмодулі, можна видалити за допомогою --force. Основне робоче дерево видалити не можна.

repair [<path>…​]

Відновіть адміністративні файли робочого дерева, якщо це можливо, якщо вони пошкоджені або застаріли через зовнішні фактори.

Наприклад, якщо головне робоче дерево (або голий репозиторій) переміщено, пов’язані робочі дерева не зможуть його знайти. Запуск repair у головному робочому дереві відновить з’єднання між пов’язаними робочими деревами та головним робочим деревом.

Аналогічно, якщо робоче дерево для пов’язаного робочого дерева переміщується без використання git worktree move, головне робоче дерево (або чистий репозиторій) не зможе його знайти. Запуск repair в нещодавно переміщеному робочому дереві відновить з’єднання. Якщо переміщено кілька пов’язаних робочих дерев, запуск repair з будь-якого робочого дерева з новим <шлях> кожного дерева як аргументом відновить з’єднання з усіма зазначеними шляхами.

Якщо і головне робоче дерево, і пов’язані робочі дерева були переміщені або скопійовані вручну, то виконання команди repair в головному робочому дереві та вказівка нового <шлях> для кожного пов’язаного робочого дерева відновить усі з’єднання в обох напрямках.

unlock

Розблокувати робоче дерево, що дозволить його скоротити, перемістити або видалити.

ОПЦІЇ

-f
--force

За замовчуванням, add відмовляється створювати нове робоче дерево, коли <commit-ish> є назвою гілки та вже витягнута іншим робочим деревом, або якщо <path> вже призначено деякому робочому дереву, але відсутнє (наприклад, якщо <path> було видалено вручну). Ця опція замінює ці запобіжні заходи. Щоб додати відсутній, але заблокований шлях до робочого дерева, двічі вкажіть --force.

move відмовляється переміщувати заблоковане робоче дерево, якщо двічі не вказано --force. Якщо пункт призначення вже призначено якомусь іншому робочому дереву, але він відсутній (наприклад, якщо <new-path> було видалено вручну), тоді --force дозволяє продовжити переміщення; використовуйте --force двічі, якщо пункт призначення заблоковано.

remove відмовляється видаляти нечисте робоче дерево, якщо не використовується --force. Щоб видалити заблоковане робоче дерево, двічі вкажіть --force.

-b <new-branch>
-B <new-branch>

За допомогою add створіть нову гілку з назвою <new-branch>, починаючи з <commit-ish>, та перенесіть <new-branch> у нове робоче дерево. Якщо <commit-ish> пропущено, за замовчуванням використовується HEAD. За замовчуванням -b відмовляється створювати нову гілку, якщо вона вже існує. -B ігнорує цей захист, скидаючи <new-branch> до <commit-ish>.

-d
--detach

За допомогою add від’єднайте HEAD у новому робочому дереві. Див. "DETACHED HEAD" у git-checkout[1].

--[no-]checkout

За замовчуванням, add перевіряє <commit-ish>, проте --no-checkout можна використовувати для придушення перевірки, щоб внести зміни, такі як налаштування розрідженої перевірки. Див. "Різдкісну перевірку" в git-read-tree[1].

--[no-]guess-remote

З worktree add <path>, без <commit-ish>, замість створення нової гілки з HEAD, якщо існує гілка відстеження рівно в одній віддаленій гілці, що відповідає базовій назві <path>, нова гілка базується на гілці віддаленого відстеження та позначається гілка віддаленого відстеження як "upstream" від нової гілки.

Це також можна налаштувати як поведінку за замовчуванням, використовуючи параметр конфігурації worktree.guessRemote.

--[no-]relative-paths

Зв’язування робочих дерев за допомогою відносних або абсолютних шляхів (за замовчуванням). Перевизначає параметр конфігурації worktree.useRelativePaths, див. git-config[1].

За допомогою функції repair файли посилань будуть оновлені, якщо виникне абсолютна/відносна невідповідність, навіть якщо посилання правильні.

--[no-]track

Під час створення нової гілки, якщо <commit-ish> є гілкою, позначте її як "upstream" (вище за течією) від нової гілки. Це значення за замовчуванням, якщо <commit-ish> є гілкою з віддаленим відстеженням. Дивіться --track у git-branch[1] для отримання детальної інформації.

--lock

Тримати робоче дерево заблокованим після створення. Це еквівалент git worktree lock після git worktree add, але без умови змагання.

-n
--dry-run

З командою prune нічого не видаляйте; просто повідомте, що буде видалено.

--orphan

За допомогою команди add зробіть нове робоче дерево та індекс порожніми, пов’язавши робоче дерево з новою ненародженою гілкою під назвою <new-branch>.

--porcelain

За допомогою list виводьте дані у зручному для розбору форматі для скриптів. Цей формат залишатиметься стабільним у різних версіях Git та незалежно від конфігурації користувача. Рекомендується поєднувати це з -z. Детальніше дивіться нижче.

-z

Закінчувати кожен рядок символом NUL, а не символом нового рядка, коли --porcelain вказано разом із list. Це дає змогу розбирати вивід, коли шлях до робочого дерева містить символ нового рядка.

-q
--quiet

За допомогою add приховує повідомлення зворотного зв’язку.

-v
--verbose

За допомогою оператора prune повідомляти про всі видалення.

За допомогою list виведіть додаткову інформацію про робочі дерева (див. нижче).

--expire <time>

За допомогою prune видаляються лише невикористані робочі дерева, старші за <час>.

За допомогою list позначте відсутні робочі дерева як такі, що підлягають скороченню, якщо вони старіші за <time>.

--reason <string>

З lock або add --lock, пояснення, чому робоче дерево заблоковано.

<worktree>

Робочі дерева можна ідентифікувати за шляхом, відносним або абсолютним.

Якщо останні компоненти шляху в робочому дереві є унікальними серед робочих дерев, їх можна використовувати для ідентифікації робочого дерева. Наприклад, якщо у вас є лише два робочі дерева, /abc/def/ghi та /abc/def/ggg, тоді ghi або def/ghi достатньо, щоб вказати на попереднє робоче дерево.

REFS

Під час використання кількох робочих дерев деякі посилання є спільними для всіх робочих дерев, але інші є специфічними для окремого робочого дерева. Одним із прикладів є 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 config extensions.worktreeConfig true

У цьому режимі певна конфігурація залишається у шляху, вказаному git rev-parse --git-path config.worktree. Ви можете додати або оновити конфігурацію в цьому файлі за допомогою git config --worktree. Старіші версії Git відмовлятимуться в доступі до репозиторіїв з цим розширенням.

Зверніть увагу, що в цьому файлі виняток для core.bare та core.worktree відсутній. Якщо вони існують в $GIT_DIR/config, ви повинні перемістити їх до config.worktree головного робочого дерева. Ви також можете скористатися цією можливістю, щоб переглянути та перемістити іншу конфігурацію, яку ви не хочете ділити з усіма робочими деревами:

  • core.worktree ніколи не слід ділитися.

  • core.bare не слід поширювати, якщо цінність core.bare=true.

  • core.sparseCheckout не слід використовувати спільно, окрім випадків, коли ви впевнені, що завжди використовуєте розріджене отримання для всіх робочих дерев.

Дивіться документацію 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 worktree list
/path/to/bare-source            (bare)
/path/to/linked-worktree        abcd1234 [master]
/path/to/other-linked-worktree  1234abc  (detached HEAD)

Команда також показує анотації для кожного робочого дерева, відповідно до його стану. Ці анотації:

  • locked, якщо робоче дерево заблоковано.

  • prunable, якщо робоче дерево можна обрізати за допомогою git worktree prune.

$ git worktree list
/path/to/linked-worktree    abcd1234 [master]
/path/to/locked-worktree    acbd5678 (brancha) locked
/path/to/prunable-worktree  5678abc  (detached HEAD) prunable

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

$ git worktree list --verbose
/path/to/linked-worktree              abcd1234 [master]
/path/to/locked-worktree-no-reason    abcd5678 (detached HEAD) locked
/path/to/locked-worktree-with-reason  1234abcd (brancha)
	locked: worktree path is mounted on a portable device
/path/to/prunable-worktree            5678abc1 (detached HEAD)
	prunable: gitdir file points to non-existent location

Зверніть увагу, що анотація переміщується на наступний рядок, якщо доступна додаткова інформація, інакше вона залишається на тому ж рядку, що й сама робоча структура.

Формат порцеляни

У форматі porcelain на кожен атрибут подається один рядок. Якщо задано -z, то рядки завершуються символом NUL, а не символом нового рядка. Атрибути перераховані з міткою та значенням, розділеними одним пробілом. Логічні атрибути (наприклад, bare та detached) перераховані лише як мітка та присутні лише тоді, коли значення дорівнює true. Деякі атрибути (наприклад, locked) можуть бути перераховані лише як мітка або зі значенням залежно від того, чи доступна причина. Першим атрибутом робочого дерева завжди є worktree, порожній рядок вказує на кінець запису. Наприклад:

$ git worktree list --porcelain
worktree /path/to/bare-source
bare

worktree /path/to/linked-worktree
HEAD abcd1234abcd1234abcd1234abcd1234abcd1234
branch refs/heads/master

worktree /path/to/other-linked-worktree
HEAD 1234abc1234abc1234abc1234abc1234abc1234a
detached

worktree /path/to/linked-worktree-locked-no-reason
HEAD 5678abc5678abc5678abc5678abc5678abc5678c
branch refs/heads/locked-no-reason
locked

worktree /path/to/linked-worktree-locked-with-reason
HEAD 3456def3456def3456def3456def3456def3456b
branch refs/heads/locked-with-reason
locked reason why is locked

worktree /path/to/linked-worktree-prunable
HEAD 1233def1234def1234def1234def1234def1234b
detached
Файл gitdir, який можна скоротити, вказує на неіснуюче місцезнаходження

Якщо не використовується -z, будь-які "незвичайні" символи в причині блокування, такі як символи нового рядка, екрануються, а вся причина береться в лапки, як пояснено для змінної конфігурації core.quotePath (див. git-config[1]). Наприклад:

$ git worktree list --porcelain
...
locked "reason\nwhy is locked"
...

ПРИКЛАДИ

Ви перебуваєте посеред сеансу рефакторингу, і ваш начальник вимагає негайно щось виправити. Зазвичай ви можете використовувати git-stash[1] для тимчасового зберігання змін, проте ваше робоче дерево перебуває в такому безладному стані (з новими, переміщеними та видаленими файлами, а також іншими фрагментами, розкиданими навколо), що ви не хочете ризикувати порушувати його. Натомість ви створюєте тимчасове пов’язане робоче дерево, щоб зробити екстрене виправлення, видаляєте його після завершення, а потім відновлюєте попередній сеанс рефакторингу.

$ git worktree add -b emergency-fix ../temp master
$ pushd ../temp
# ... зламати,...
$ git commit -a -m 'emergency fix for boss'
$ popd
$ git worktree remove ../temp

ПОМИЛКИ

Множинне отримання загалом все ще є експериментальним, а підтримка підмодулів є неповною. НЕ рекомендується робити кілька отримання суперпроекту.

GIT

Частина набору git[1]