gitprotocol-capabilities

gitprotocol-capabilities - Возможности протокола v0 и v1

Серверы ДОЛЖНЫ поддерживать все возможности, определенные в этом документе.

В самой первой строке начального ответа сервера как для receive-pack, так и для upload-pack, первая ссылка следует за байтом NUL, а затем перечислены разделенные пробелом возможности сервера. Это позволяет серверу объявить, какие возможности он поддерживает, а какие нет, для клиента.

Затем клиент отправляет список возможностей, разделенных пробелами, которые он хочет использовать. Клиент НЕ ДОЛЖЕН запрашивать возможности, которые сервер не заявил о поддержке.

Сервер ДОЛЖЕН диагностировать и прервать выполнение, если были отправлены возможности, которые он не понимает. Сервер НЕ ДОЛЖЕН игнорировать возможности, запрошенные клиентом и опубликованные сервером. Вследствие этих правил сервер НЕ ДОЛЖЕН публиковать возможности, которые он не понимает.

Возможности atomic, report-status, report-status-v2, delete-refs, quiet, и push-cert отправляются и распознаются процессом receive-pack (отправка на сервер).

Возможности ofs-delta и side-band-64k отправляются и распознаются как протоколом upload-pack, так и receive-pack. Возможности agent и session-id могут необязательно быть отправлены в обоих протоколах.

Все остальные возможности распознаются только процессом upload-pack (получение с сервера).

Возможность multi_ack позволяет серверу вернуть "ACK obj-id continue", как только он найдет коммит, который может быть использован в качестве общей основы между запрошенным клиентом и набором, который у него есть.

Отправляя это рано, сервер может потенциально предотвратить клиенту от прохода дальше по той или иной ветке истории репозитория клиента. Клиент всё равно может пройтись по другим веткам, отправив строки "have" для них, пока сервер не создаст полное пересечение DAG или клиент не скажет "done".

Без multi_ack клиент отправляет строки "have" в порядке даты, пока сервер не найдёт общую базу. Это означает, что клиент будет отправлять строки "have", которые уже известны серверу как общие, потому что они перекрываются во времени с другой веткой, для которой сервер ещё не нашел общей базы.

Например, предположим, что клиент имеет коммиты в верхнем регистре, которых нет у сервера, а сервер имеет коммиты в нижнем регистре, которых нет у клиента, как показано на следующей диаграмме:

      +---- u ---------------------- x
     /              +----- y
    /              /
   a -- b -- c -- d -- E -- F
      \
+--- Q -- R -- S

Если клиент хочет x,y и начинает с отправки "have F,S", сервер не знает, что такое F,S. В конечном итоге клиент отправляет "have d", и сервер отправляет "ACK d continue", чтобы сообщить клиенту о прекращении прохода по этой ветке (не отправлять c-b-a), но это ещё не всё, ему нужна база для x. Клиент продолжает отправлять S-R-Q, пока не будет достигнут a, в этот момент сервер имеет ясную базу, и всё заканчивается.

Без multi_ack клиент в любом случае отправил бы цепочку c-b-a, перемежаясь с S-R-Q.

Это расширение multi_ack, которое позволяет клиенту лучше понять внутреннее состояние сервера. Подробная информация доступна в разделе «Переговоры о файлах pack» документа gitprotocol-pack[5].

Эта возможность должна использоваться только с умным протоколом HTTP. Если multi_ack_detailed и no-done оба присутствуют, отправитель свободен сразу же отправить pack после первого сообщения "ACK obj-id ready".

Без no-done в умном протоколе HTTP сессия сервера заканчивалась, и клиенту приходилось совершать дополнительный запрос, чтобы отправить "done", прежде чем сервер мог отправить pack. no-done устраняет последний раунд и, таким образом, немного снижает задержку.

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

Сервер upload-pack объявляет thin-pack, когда он может сгенерировать и отправить тонкий pack. Клиент запрашивает возможность thin-pack, когда понимает, как «утолщать» его, сообщая серверу, что может получить такой pack. Клиент НЕ ДОЛЖЕН запрашивать возможность thin-pack, если он не может преобразовать тонкий pack в автономный pack.

С другой стороны, receive-pack по умолчанию предполагается способным обрабатывать тонкие pack, но может попросить клиента не использовать эту функцию, объявив возможность no-thin. Клиент НЕ ДОЛЖЕН отправлять тонкий pack, если сервер объявляет возможность no-thin.

Причины этой асимметрии исторические. Программа receive-pack появилась позже, чем изобретение тонких pack, поэтому исторически реализация receive-pack всегда понимала тонкие pack. Добавление no-thin позже позволило receive-pack отключить эту функцию совместимым образом.

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

Эти два варианта взаимоисключающие. Современный клиент всегда отдает предпочтение side-band-64k.

Любой из этих режимов указывает, что данные файла pack будут передаваться потоком, разбитым на пакеты объёмом до 1000 байт в случае side_band, или 65520 байт в случае side_band_64k. Каждый пакет состоит из 4-байтовой длины pkt-line, указывающей на размер данных в пакете, за которой следует 1-байтовый код потока и сами данные.

Код потока может быть одним из:

1 - pack data
2 - progress messages
3 - fatal error message just before stream aborts

Возможность "side-band-64k" появилась как способ для новых клиентов, которые могут обрабатывать гораздо более крупные пакеты, запросить пакеты, заполненные практически полностью, сохраняя обратную совместимость для старых клиентов.

Кроме того, с side-band и его сообщениями до 1000 байт, фактически 999 байт полезной нагрузки и 1 байт для кода потока. С side-band-64k, та же ситуация, у вас может быть до 65519 байт данных и 1 байт для кода потока.

Клиент ДОЛЖЕН отправить только один из "side-band" и "side-band-64k". Сервер ДОЛЖЕН распознать это как ошибку, если клиент запросит оба.

Сервер может отправлять, а клиент может понимать, PACKv2 с дельтами, которые ссылаются на базовые объекты по положению в pack, а не по obj-id. То есть, они могут отправлять/читать OBJ_OFS_DELTA (также известный как тип 6) в файле pack.

Сервер может необязательно отправить возможность в формате agent=X, чтобы сообщить клиенту, что сервер работает под версией X. Клиент может необязательно вернуть свою строку агента, ответив возможностью agent=Y (но он НЕ ДОЛЖЕН этого делать, если сервер не упомянул возможность агента). Строки X и Y могут содержать любые печатные символы ASCII, кроме пробела (то есть диапазон байтов 32 < x < 127), и обычно имеют формат «пакет/версия» (например, «git/1.8.3.1»). Строки агента предназначены только для информационных целей, статистики и отладки, и НЕ ДОЛЖНЫ использоваться для программирования предположений о наличии или отсутствии определенных функций.

Эта возможность, которая принимает алгоритм хеширования в качестве аргумента, указывает, что сервер поддерживает указанные алгоритмы хеширования. Она может быть отправлена несколько раз; в таком случае первая из них используется для рекламы ссылок.

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

Если эта возможность не предоставляется, предполагается, что единственный поддерживаемый алгоритм — SHA-1.

Эта параметризованная возможность используется для информирования получателя о том, какие символические ссылки указывают на какие ссылки; например, «symref=HEAD:refs/heads/master» сообщает получателю, что HEAD указывает на master. Эта возможность может повторяться для представления нескольких symref.

Серверы ДОЛЖНЫ включать эту возможность для symref HEAD, если это одна из отправляемых ссылок.

Клиенты МОГУТ использовать параметры из этой возможности для выбора правильной начальной ветки при клонировании репозитория.

Эта возможность добавляет команды «deepen», «shallow» и «unshallow» к протоколам fetch-pack/upload-pack, чтобы клиенты могли запрашивать поверхностные клоны.

Эта возможность добавляет команду «deepen-since» к протоколам fetch-pack/upload-pack, чтобы клиент мог запрашивать поверхностные клоны, которые обрезаются в определенное время, а не по глубине. Внутренне это эквивалентно выполнению «rev-list --max-age=<timestamp>» на стороне сервера. «deepen-since» нельзя использовать с «deepen».

Эта возможность добавляет команду «deepen-not» к протоколам fetch-pack/upload-pack, чтобы клиент мог запрашивать поверхностные клоны, которые обрезаются по определённой ревизии, а не по глубине. Внутренне это эквивалентно выполнению «rev-list --not <rev>» на стороне сервера. «deepen-not» нельзя использовать с «deepen», но можно использовать с «deepen-since».

Если клиент запросил эту возможность, семантика команды «deepen» изменяется. Аргумент «глубина» представляет глубину от текущей границы поверхностного репозитория, а не глубину от удалённых ссылок.

Клиент был запущен с «git clone -q» или чем-то подобным и не хочет получать side band 2. По сути, клиент просто говорит: «Я не хочу получать поток 2 на sideband, поэтому не отправляйте его мне, и если вы это сделаете, я его игнорирую». Однако канал sideband 3 всё ещё используется для ответов об ошибках.

Возможность include-tag связана с отправкой аннотированных тегов, если мы отправляем объекты, на которые они ссылаются. Если мы упаковываем объект для клиента, а объект тега указывает именно на этот объект, мы также упаковываем объект тега. В общем случае это позволяет клиенту получить все новые аннотированные теги при получении ветки в одном сетевом соединении.

Клиенты МОГУТ всегда отправлять include-tag, жестко задавая его в запросе, когда сервер объявляет об этой возможности. Решение клиента запросить include-tag зависит только от желаний клиента получить данные тега, независимо от того, рекламировал ли сервер объекты в пространстве имен refs/tags/*.

Серверы ДОЛЖНЫ упаковывать теги, если их ссылки упакованы, и клиент запросил include-tags.

Клиенты ДОЛЖНЫ быть готовы к случаю, когда сервер проигнорировал include-tag и не отправил теги в упаковке. В таких случаях клиент ДОЛЖЕН выполнить последующий запрос для получения тегов, которые include-tag иначе предоставил бы клиенту.

Сервер ДОЛЖЕН отправить include-tag, если он его поддерживает, независимо от того, есть ли доступные теги.

Процесс receive-pack может получить возможность report-status, которая сообщает ему, что клиент хочет отчет о том, что произошло после загрузки файла пакета и обновления ссылок. Если клиент, выполняющий отправку, запрашивает эту возможность, после распаковки и обновления ссылок сервер ответит, успешно ли был распакован файл пакета и успешно ли было обновлено каждое обращение. Если какие-либо из них не были успешными, он отправит сообщение об ошибке. Примеры сообщений см. в gitprotocol-pack[5].

Возможность report-status-v2 расширяет возможность report-status, добавив новые директивы "option", чтобы поддерживать переписанные ссылки крючком "proc-receive". Крючок "proc-receive" может обрабатывать команду для псевдо-ссылки, которая может создавать или обновлять ссылку с другим именем, новым и старым объектами. В то время как возможность report-status не может сообщить об этом случае. Подробности см. в gitprotocol-pack[5].

Если сервер отправляет возможность delete-refs, это означает, что он может принимать нулевое значение ID в качестве целевого значения обновления ссылки. Он не отправляется клиентом, он просто сообщает клиенту, что ему могут быть отправлены нулевые значения ID для удаления ссылок.

Если сервер receive-pack объявляет возможность quiet, он может отключить вывод прогресса в удобочитаемом формате, который в противном случае может отображаться при обработке полученного пакета. Клиент send-pack должен ответить возможностью quiet, чтобы подавить отчет о прогрессе на стороне сервера, если локальный отчет о прогрессе также подавляется (например, посредством push -q, или если stderr не отправляется в tty).

Если сервер отправляет возможность atomic, он может принимать атомарные отправки. Если клиент, выполняющий отправку, запрашивает эту возможность, сервер обновит ссылки в одной атомарной транзакции. Все ссылки обновляются или ни одной.

Если сервер отправляет возможность push-options, он может принимать параметры отправки после отправки команд обновления, но до потоковой передачи файла пакета. Если клиент, выполняющий отправку, запрашивает эту возможность, сервер передаст параметры крючкам pre- и post-receive, которые обрабатывают этот запрос на отправку.

Если сервер upload-pack объявляет эту возможность, fetch-pack может отправлять строки «want» с именами объектов, которые существуют на сервере, но не объявлены upload-pack. По историческим причинам имя этой возможности содержит «sha1». Имена объектов всегда указываются с использованием формата объекта, согласованного через возможность object-format.

Если сервер upload-pack объявляет эту возможность, fetch-pack может отправлять строки «want» с именами объектов, которые существуют на сервере, но не объявлены upload-pack. По историческим причинам имя этой возможности содержит «sha1». Имена объектов всегда указываются с использованием формата объекта, согласованного через возможность object-format.

Сервер receive-pack, который объявляет эту возможность, готов принять подписанный сертификат отправки и запросит включить <nonce> в сертификат отправки. Клиент send-pack НЕ должен отправлять пакет push-cert, если сервер receive-pack не объявляет эту возможность.

Если сервер upload-pack объявляет возможность filter, fetch-pack может отправлять команды «filter» для запроса частичного клонирования или частичной загрузки и запроса исключения различных объектов из файла пакета.

Сервер может объявить идентификатор сеанса, который может использоваться для идентификации этого процесса в нескольких запросах. Клиент также может объявить свой собственный идентификатор сеанса серверу.

Идентификаторы сеансов должны быть уникальными для данного процесса. Они должны помещаться в строку пакета и не должны содержать непечатаемых или пробельных символов. Текущая реализация использует идентификаторы сеансов trace2 (подробности см. в api-trace2), но это может измениться, и пользователи идентификатора сеанса не должны полагаться на этот факт.