git-update-ref

git-update-ref — безопасное обновление имени объекта, хранящегося в ссылке

При передаче двух аргументов команда сохраняет <new-oid> в <ref>, при необходимости переходя по символическим ссылкам. Например, git update-ref HEAD <new-oid> обновляет указатель на вершину текущей ветки, указывая на новый объект.

При передаче трёх аргументов команда сохраняет <new-oid> в <ref>, при необходимости переходя по символическим ссылкам, после проверки того, что текущее значение <ref> совпадает с <old-oid>. Например, git update-ref refs/heads/master <new-oid> <old-oid> обновляет указатель на вершину ветки master, указывая на <new-oid>, только если его текущее значение равно <old-oid>. Чтобы убедиться, что создаваемая ссылка не существует, в качестве <old-oid> можно указать 40 нулей («0») или пустую строку.

Последние аргументы — это имена объектов; эта команда без параметров не поддерживает обновление символической ссылки так, чтобы она указывала на другую ссылку (см. git-symbolic-ref[1]). Однако git update-ref --stdin поддерживает команды symref-*, позволяющие зафиксировать обычные и символические ссылки в одной транзакции.

Если указан параметр --no-deref, перезаписывается сама <ref>, а не результат перехода по символическим указателям.

С параметром -d команда удаляет указанную <ref> после проверки того, что она по-прежнему содержит <old-oid>.

С параметром --stdin команда update-ref считывает инструкции из стандартного ввода и выполняет все изменения вместе. Указывайте команды в следующем формате:

update SP <ref> SP <new-oid> [SP <old-oid>] LF
create SP <ref> SP <new-oid> LF
delete SP <ref> [SP <old-oid>] LF
verify SP <ref> [SP <old-oid>] LF
symref-update SP <ref> SP <new-target> [SP (ref SP <old-target> | oid SP <old-oid>)] LF
symref-create SP <ref> SP <new-target> LF
symref-delete SP <ref> [SP <old-target>] LF
symref-verify SP <ref> [SP <old-target>] LF
option SP <opt> LF
start LF
prepare LF
commit LF
abort LF

С параметром --create-reflog команда update-ref создаёт журнал ссылок для каждой ссылки, даже если обычно он не создавался бы.

С параметром --batch-updates команда update-ref выполняет обновления пакетом, но допускает сбой отдельных обновлений из-за недопустимых или некорректных пользовательских данных, применяя только успешные обновления. Однако системные ошибки, такие как сбои ввода-вывода или нехватка памяти, приведут к полному сбою всех обновлений пакета. Сведения о неудачных обновлениях будут выведены в следующем формате:

rejected SP (<old-oid> | <old-target>) SP (<new-oid> | <new-target>) SP <rejection-reason> LF

Поля, содержащие пробелы, заключайте в кавычки так же, как строки в исходном коде на C: в двойные кавычки, с экранированием обратной косой чертой. Для указания нулевого значения используйте 40 символов «0» или пустую строку. Чтобы указать отсутствующее значение, опустите его вместе с предшествующим пробелом.

Также можно использовать -z, чтобы указать данные в формате с завершающим нулевым байтом, без кавычек:

update SP <ref> NUL <new-oid> NUL [<old-oid>] NUL
create SP <ref> NUL <new-oid> NUL
delete SP <ref> NUL [<old-oid>] NUL
verify SP <ref> NUL [<old-oid>] NUL
symref-update SP <ref> NUL <new-target> [NUL (ref NUL <old-target> | oid NUL <old-oid>)] NUL
symref-create SP <ref> NUL <new-target> NUL
symref-delete SP <ref> [NUL <old-target>] NUL
symref-verify SP <ref> [NUL <old-target>] NUL
option SP <opt> NUL
start NUL
prepare NUL
commit NUL
abort NUL

В этом формате для указания нулевого значения используйте 40 символов «0», а для указания отсутствующего значения — пустую строку.

В обоих форматах значения можно указывать в любой форме, распознаваемой Git как имя объекта. Команды в любом другом формате или повторное указание <ref> приводят к ошибке. Значения команд:

Если все <ref> удаётся одновременно заблокировать при совпадении значений <old-oid>, выполняются все изменения. В противном случае изменения не выполняются. Обратите внимание: хотя каждая отдельная <ref> обновляется или удаляется атомарно, параллельный читатель всё ещё может увидеть лишь часть изменений.

Если параметр конфигурации "core.logAllRefUpdates" имеет значение true и ссылка находится в "refs/heads/", "refs/remotes/", "refs/notes/" либо является псевдоссылкой, например HEAD или ORIG_HEAD, или если файл "$GIT_DIR/logs/<ref>" существует, то git update-ref добавит строку в файл журнала "$GIT_DIR/logs/<ref>" (перед созданием имени журнала переходя по всем символическим ссылкам), описывающую изменение значения ссылки. Строки журнала имеют следующий формат:

oldsha1 SP newsha1 SP committer LF

Здесь "oldsha1" — ранее сохранённое в <ref> 40-значное шестнадцатеричное значение, "newsha1" — 40-значное шестнадцатеричное значение <new-oid>, а "committer" — имя, адрес электронной почты и дата коммитера в стандартном формате идентификатора коммитера Git.

При указании -m формат будет следующим:

oldsha1 SP newsha1 SP committer TAB message LF

Все поля имеют описанные выше значения, а "message" — это значение, переданное параметру -m.

Обновление завершится ошибкой (не изменив <ref>), если текущий пользователь не может создать новый файл журнала, добавить данные в существующий файл журнала или если данные коммитера недоступны.

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

Эта команда переходит по реальным символическим ссылкам, только если они начинаются с "refs/"; в противном случае она просто попытается прочитать их и обновить как обычный файл (то есть позволит файловой системе перейти по ним, но заменит такую символическую ссылку, указывающую в другое место, обычным файлом).

git-symbolic-ref[1]