git-read-tree

Слияние одного дерева

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

Это означает, что если вы выполните git read-tree -m <newtree> за которым следует 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" обозначает индекс, "чисто" означает, что индекс и рабочая директория совпадают, а "существует"/"нет" относится к наличию пути в указанном коммите:

        I                   H        M        Result
       -------------------------------------------------------
     0  nothing             nothing  nothing  (does not happen)
     1  nothing             nothing  exists   use M
     2  nothing             exists   nothing  remove path from index
     3  nothing             exists   exists,  use M if "initial checkout",
                                     H == M   keep index otherwise
                                     exists,  fail
                                     H != M

        clean I==H  I==M
       ------------------
     4  yes   N/A   N/A     nothing  nothing  keep index
     5  no    N/A   N/A     nothing  nothing  keep index

     6  yes   N/A   yes     nothing  exists   keep index
     7  no    N/A   yes     nothing  exists   keep index
     8  yes   N/A   no      nothing  exists   fail
     9  no    N/A   no      nothing  exists   fail

     10 yes   yes   N/A     exists   nothing  remove path from index
     11 no    yes   N/A     exists   nothing  fail
     12 yes   no    N/A     exists   nothing  fail
     13 no    no    N/A     exists   nothing  fail

        clean (H==M)
       ------
     14 yes                 exists   exists   keep index
     15 no                  exists   exists   keep index

        clean I==H  I==M (H!=M)
       ------------------
     16 yes   no    no      exists   exists   fail
     17 no    no    no      exists   exists   fail
     18 yes   no    yes     exists   exists   keep index
     19 no    no    yes     exists   exists   keep index
     20 yes   yes   no      exists   exists   use M
     21 no    yes   no      exists   exists   fail

Во всех случаях "сохранение индекса" запись в индексе остаётся такой же, как и в исходном файле индекса. Если запись не обновлена, 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 одинаковы.

Слияние трёх путей

В каждой записи "индекса" есть два бита состояния "этапа". Стадия 0 — обычная, и именно она видна при обычном использовании.

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

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

$ git read-tree -m <tree1> <tree2> <tree3>

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

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

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

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

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

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

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

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

$ JC=`git rev-parse --verify "HEAD^0"`
$ git checkout-index -f -u -a $JC

Вы делаете случайные правки, не выполняя git update-index. И затем вы замечаете, что вершина вашего "удаленного" дерева продвинулась с момента вашего извлечения данных от него:

$ git fetch git://.... linus
$ LT=`git rev-parse FETCH_HEAD`

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

$ git read-tree -m -u `git merge-base $JC $LT` $JC $LT
$ git merge-index git-merge-one-file -a
$ echo "Merge with Linus" | \
  git commit-tree `git write-tree` -p $JC -p $LT

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

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

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