Если указано только 1 дерево, git read-tree работает так, как если бы пользователь не указывал -m, за исключением того, что если в исходном индексе есть запись для данного пути и содержимое пути совпадает с читаемым деревом, используется информация stat из индекса. (Другими словами, данные stat() индекса имеют приоритет над данными объединённого дерева).

Это означает, что если вы выполните git read-tree -m <новоедерево>, а затем git checkout-index -f -u -a, то git checkout-index переключит только то, что действительно изменилось.

Это используется для предотвращения ненужных ложных срабатываний при запуске git diff-files после git read-tree.

Обычно это вызывается как git read-tree -m $H $M, где $H — головной коммит текущего репозитория, а $M — голова внешнего дерева, которая просто опережает $H (т.е. мы находимся в ситуации перемотки вперёд).

Когда указаны два дерева, пользователь сообщает git read-tree следующее:

В этом случае команда git read-tree -m $H $M гарантирует, что ни одно локальное изменение не будет потеряно в результате этого «слияния». Вот правила «переноса вперёд», где «I» обозначает индекс, «clean» означает, что индекс и рабочий каталог совпадают, а «exists»/«nothing» относятся к наличию пути в указанном коммите:

Во всех случаях «сохранить индекс» запись индекса остаётся такой же, как в исходном файле индекса. Если запись не актуальна, git read-tree сохраняет копию в рабочем каталоге нетронутой при работе с флагом -u.

Когда эта форма git read-tree успешно возвращается, вы можете увидеть, какие из сделанных вами «локальных изменений» были перенесены вперёд, выполнив git diff-index --cached $M. Обратите внимание, что это не обязательно совпадает с тем, что git diff-index --cached $H показал бы до такого слияния двух деревьев. Это из-за случаев 18 и 19 — если у вас уже были изменения в $M (например, возможно, вы получили их по электронной почте в виде изменения), git diff-index --cached $H сообщил бы вам об изменении до этого слияния, но оно не отобразилось бы в выводе git diff-index --cached $M после слияния двух деревьев.

Случай 3 немного сложен и требует пояснения. Логически результатом этого правила должно быть удаление пути, если пользователь проиндексировал удаление пути, а затем переключился на новую ветку. Однако это предотвратит начальное переключение, поэтому правило изменено: использовать M (новое дерево) только тогда, когда содержимое индекса пусто. В противном случае удаление пути сохраняется до тех пор, пока $H и $M совпадают.

Каждая запись «индекса» имеет два бита состояния «этапа» (stage). Этап 0 — это обычный, и это единственный, который вы увидите при любом обычном использовании.

Однако, когда вы выполняете git read-tree с тремя деревьями, «этап» начинается с 1.

Это означает, что вы можете выполнить

и в итоге вы получите индекс со всеми записями <дерево1> на «этапе1», всеми записями <дерево2> на «этапе2» и всеми записями <дерево3> на «этапе3». При выполнении слияния другой ветки в текущую ветку мы используем дерево общего предка как <дерево1>, голову текущей ветки как <дерево2> и голову другой ветки как <дерево3>.

Кроме того, git read-tree имеет специальную логику: если вы видите файл, полностью совпадающий в следующих состояниях, он «схлопывается» обратно в «этап0»:

Команда git write-tree отказывается записывать бессмысленное дерево и будет жаловаться на неслитые (unmerged) записи, если увидит хотя бы одну запись не на этапе 0.

Итак, всё это звучит как набор совершенно бессмысленных правил, но на самом деле это именно то, что нужно для быстрого слияния. Различные этапы представляют «результирующее дерево» (этап 0, также известный как «слитое»), исходное дерево (этап 1, также известный как «orig») и два дерева, которые вы пытаетесь слить (этапы 2 и 3 соответственно).

Порядок этапов 1, 2 и 3 (а следовательно, и порядок трёх аргументов командной строки <указатель-дерева>) имеет значение, когда вы начинаете трёхстороннее слияние с уже заполненным файлом индекса. Вот краткое описание того, как работает алгоритм:

Обычно вы используете git merge-index с предоставленным git merge-one-file для выполнения этого последнего шага. Сценарий обновляет файлы в рабочем каталоге по мере слияния каждого пути и после успешного завершения слияния.

Когда вы начинаете трёхстороннее слияние с уже заполненным файлом индекса, предполагается, что он представляет состояние файлов в вашем рабочем каталоге, и у вас даже могут быть файлы с изменениями, не зарегистрированными в файле индекса. Далее предполагается, что это состояние «получено» из дерева этапа 2. Трёхстороннее слияние отказывается выполняться, если находит в исходном файле индекса запись, которая не соответствует этапу 2.

Это делается для того, чтобы вы не потеряли свои текущие изменения и не смешали свои случайные изменения в несвязанном коммите слияния. Для иллюстрации предположим, что вы начинаете с того, что было закоммичено последним в ваш репозиторий:

Вы делаете случайные правки, не запуская git update-index. А затем вы замечаете, что верхушка вашего «вышестоящего» (upstream) дерева продвинулась с тех пор, как вы извлекли (pull) от него:

Ваш рабочий каталог по-прежнему основан на вашем HEAD ($JC), но с тех пор у вас есть некоторые правки. Трёхстороннее слияние гарантирует, что вы не добавляли и не изменяли записи индекса с момента $JC, и если нет, то делает правильные вещи. Итак, со следующей последовательностью:

то, что вы закоммитите, будет чистым слиянием между $JC и $LT без ваших текущих изменений, и ваш рабочий каталог будет обновлён до результата слияния.

Однако, если у вас есть локальные изменения в рабочем каталоге, которые будут перезаписаны этим слиянием, git read-tree откажется выполняться, чтобы предотвратить потерю ваших изменений.

Другими словами, нет необходимости беспокоиться о том, что существует только в рабочем каталоге. Если у вас есть локальные изменения в части проекта, не затронутой слиянием, ваши изменения не мешают слиянию и сохраняются нетронутыми. Когда они действительно мешают, слияние даже не начинается (git read-tree громко жалуется и завершается сбоем, ничего не изменяя). В таком случае вы можете просто продолжить то, что делали, и когда ваш рабочий каталог будет готов (т.е. вы закончите свою текущую работу), повторите попытку слияния.