українська мова ▾ Topics ▾ Latest version ▾ git-worktree last updated in 2.53.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 нове робоче дерево повʼязується з репозиторієм разом із додатковими метаданими, які відрізняють це робоче дерево від інших у тому ж репозиторії. Робоче дерево разом із цими метаданими називається "worktree".

Це нове робоче дерево називається «звʼязаним робочим деревом» ("linked worktree"), на відміну від «головного робочого дерева» ("main worktree"), підготовленого за допомогою git-init[1] або git-clone[1]. Репозиторій має одне головне робоче дерево (якщо це не голий репозиторій) та нуль або більше звʼязаних робочих дерев. Коли ви закінчите роботу зі звʼязаним робочим деревом, видаліть його за допомогою команди git worktree remove.

У найпростішій формі, git worktree add <шлях> автоматично створює нову гілку, імʼя якої є останнім компонентом <шляху>, що зручно, якщо ви плануєте працювати над новою темою. Наприклад, git worktree add ../hotfix створює нову гілку hotfix та переходить до неї за шляхом ../hotfix. Щоб натомість працювати з наявною гілкою в новому робочому дереві, використовуйте git worktree add <шлях> <гілка>. З іншого боку, якщо ви просто плануєте внести деякі експериментальні зміни або провести тестування, не порушуючи поточної розробки, часто зручно створити "тимчасове" (throwaway) робоче дерево, не повʼязане з жодною гілкою. Наприклад, git worktree add -d <шлях> створює нове робоче дерево з відокремленим HEAD у тому ж коміті, що й поточна гілка.

Якщо робоче дерево видаляється без використання команди git worktree remove, то повʼязані з ним адміністративні файли, які знаходяться в репозиторії (див. "ДЕТАЛІ" нижче), зрештою будуть видалені автоматично (див. gc.worktreePruneExpire в git-config[1]), або ви можете запустити git worktree prune в головному або будь-якому повʼязаному робочому дереві, щоб очистити будь-які застарілі адміністративні файли.

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

КОМАНДИ

add <path> [<commit-ish>]

Створити робоче дерево за адресою <шлях> та передати <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

Вивести детальну інформацію про кожне робоче дерево. Спочатку виводиться головне робоче дерево, а потім — кожне з пов’язаних робочих дерев. У вихідних даних вказується, чи є робоче дерево «голим», яка ревізія наразі вибрана, яка гілка наразі вибрана (або «detached HEAD», якщо гілки немає), «locked», якщо робоче дерево заблоковано, та «prunable», якщо робоче дерево можна очистити за допомогою команди 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. Якщо пункт призначення вже призначено якомусь іншому робочому дереву, але він відсутній (наприклад, якщо <новий-шлях> було видалено вручну), тоді --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].

--checkout
--no-checkout

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

--guess-remote
--no-guess-remote

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

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

--relative-paths
--no-relative-paths

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

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

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

--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

У форматі «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-config[1]. Вміст такий самий, як і там:

worktree.guessRemote

Якщо гілка не вказана і не використовуються параметри -b, -B або --detach, то git worktree add стандартно створює нову гілку з HEAD. Якщо worktree.guessRemote встановлено в значення true, worktree add намагається знайти гілку віддаленого відстеження, імʼя якої однозначно збігається з іменем нової гілки. Якщо така гілка існує, вона вибирається і встановлюється як «upstream» для нової гілки. Якщо такого збігу не вдається знайти, виконується створення нової гілки з поточного HEAD.

worktree.useRelativePaths

Повʼязує робочі дерева за допомогою відносних шляхів (якщо встановлено значення «true») або абсолютних шляхів (якщо встановлено значення «false»). Це особливо корисно в ситуаціях, коли репозиторій та робочі дерева можуть переміщуватися між різними місцями або середовищами. Стандартне значення — «false».

Зверніть увагу, що встановлення для параметра worktree.useRelativePaths значення «true» означає увімкнення параметра конфігурації extensions.relativeWorktrees (див. git-config[1]), що робить його несумісним зі старими версіями Git.

ПОМИЛКИ

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

GIT

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