gitremote-helpers

Название

gitremote-helpers — вспомогательные программы для взаимодействия с удалёнными репозиториями

Краткое описание

git remote-<transport> <repository> [<URL>]

Описание

Вспомогательные программы для работы с удалёнными репозиториями обычно не используются конечными пользователями напрямую, но Git запускает их, когда ему требуется взаимодействовать с удалёнными репозиториями, поддержку которых он не реализует самостоятельно. Каждый вспомогательный инструмент реализует подмножество возможностей, описанных здесь. Когда Git требуется взаимодействовать с репозиторием с помощью вспомогательной программы, он запускает её как независимый процесс, отправляет команды в стандартный ввод программы и ожидает результаты в её стандартном выводе. Поскольку вспомогательная программа работает как независимый от Git процесс, нет необходимости повторно компоновывать Git для добавления новой программы или связывать вспомогательную программу с реализацией Git.

Каждая вспомогательная программа должна поддерживать команду "capabilities", с помощью которой Git определяет, какие другие команды она принимает. Эти команды можно использовать для получения и обновления удалённых ссылок, передачи объектов между базой объектов и удалённым репозиторием, а также обновления локального хранилища объектов.

Git поставляется с семейством вспомогательных программ для удалённых репозиториев "curl", которые обрабатывают различные транспортные протоколы, например git-remote-http, git-remote-https, git-remote-ftp и git-remote-ftps. Они реализуют возможности fetch, option и push.

Вызов

Вспомогательные программы для удалённых репозиториев вызываются с одним или (при необходимости) двумя аргументами. Первый аргумент задаёт удалённый репозиторий, как и в Git: это может быть имя настроенного удалённого репозитория или URL. Второй аргумент задаёт URL; обычно он имеет вид <transport>://<address>, но может быть любой произвольной строкой. Для вспомогательной программы устанавливается переменная окружения GIT_DIR; её можно использовать, чтобы определить, где хранить дополнительные данные или из какого каталога запускать вспомогательные команды Git.

Когда Git встречает URL вида <transport>://<address>, где <transport> — протокол, который он не может обрабатывать самостоятельно, он автоматически вызывает git remote-<transport>, передавая полный URL в качестве второго аргумента. Если такой URL указан непосредственно в командной строке, первый аргумент совпадает со вторым; если URL указан в настройках удалённого репозитория, первый аргумент — имя этого репозитория.

URL вида <transport>::<address> явно указывает Git вызвать git remote-<transport>, передав <address> в качестве второго аргумента. Если такой URL указан непосредственно в командной строке, первый аргумент — <address>; если URL указан в настройках удалённого репозитория, первый аргумент — имя этого репозитория.

Кроме того, если для настроенного удалённого репозитория задано remote.<name>.vcs со значением <transport>, Git явно вызывает git remote-<transport>, передавая <name> в качестве первого аргумента. Если задано значение, второй аргумент — remote.<name>.url; в противном случае второй аргумент не передаётся.

Формат входных данных

Git отправляет вспомогательной программе список команд в стандартный ввод, по одной команде в строке. Первой всегда идёт команда capabilities; в ответ вспомогательная программа должна вывести список поддерживаемых возможностей (см. ниже), а затем пустую строку. Ответ на команду capabilities определяет, какие команды Git использует в оставшейся части потока команд.

Поток команд завершается пустой строкой. В некоторых случаях (указанных в документации к соответствующим командам) за этой пустой строкой следуют данные в формате другого протокола (например, протокола pack), а в других случаях она обозначает конец входных данных.

Возможности

Предполагается, что каждая вспомогательная программа поддерживает только подмножество команд. Операции, поддерживаемые программой, объявляются Git в ответе на команду capabilities (см. раздел «КОМАНДЫ» ниже).

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

Возможности для отправки изменений

connect

Может попытаться подключиться к git receive-pack (для отправки изменений), git upload-pack и т. д. для обмена данными с использованием собственного протокола Git для файлов pack. Для этого требуется двунаправленное соединение с полным дуплексом.

Поддерживаемые команды: connect.

stateless-connect

Экспериментальная возможность; только для внутреннего использования. Может попытаться подключиться к удалённому серверу для обмена данными с использованием версии 2 wire-протокола Git. Дополнительные сведения см. в документации к команде stateless-connect.

Поддерживаемые команды: stateless-connect.

push

Может обнаруживать удалённые ссылки и отправлять локальные коммиты вместе с историей, ведущей к ним, в новые или существующие удалённые ссылки.

Поддерживаемые команды: list for-push, push.

export

Может обнаруживать удалённые ссылки и отправлять указанные объекты из потока fast-import в удалённые ссылки.

Поддерживаемые команды: list for-push, export.

Если вспомогательная программа объявляет возможность connect, Git использует её, если это возможно, и переключается на другую возможность, если программа запрашивает это при подключении (см. команду connect в разделе «КОМАНДЫ»). При выборе между push и export Git отдаёт предпочтение push. У других интерфейсных программ может быть иной порядок предпочтений.

no-private-update: При использовании возможности refspec Git обычно обновляет частную ссылку после успешной отправки изменений. Это обновление отключается, если вспомогательная программа для удалённого репозитория объявляет возможность no-private-update.

Возможности для получения данных

connect

Может попытаться подключиться к git upload-pack (для получения данных), git receive-pack и т. д. для обмена данными с использованием собственного протокола Git для файлов pack. Для этого требуется двунаправленное соединение с полным дуплексом.

Поддерживаемые команды: connect.

stateless-connect

Поддерживаемые команды: stateless-connect.

fetch

Может обнаруживать удалённые ссылки и передавать объекты, достижимые из этих ссылок, в локальное хранилище объектов.

Поддерживаемые команды: list, fetch.

import

Может обнаруживать удалённые ссылки и выводить объекты, достижимые из этих ссылок, в виде потока в формате fast-import.

Поддерживаемые команды: list, import.

check-connectivity

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

get

Может использовать команду get для загрузки файла по заданному URI.

Если вспомогательная программа объявляет возможность connect, Git использует её, если это возможно, и переключается на другую возможность, если программа запрашивает это при подключении (см. команду connect в разделе «КОМАНДЫ»). При выборе между fetch и import Git отдаёт предпочтение fetch. У других интерфейсных программ может быть иной порядок предпочтений.

Прочие возможности

option

Для задания параметров, таких как verbosity (объём вывода в stderr) и depth (объём истории, необходимый при неглубоком клонировании), которые влияют на выполнение других команд.

refspec <refspec>

Для вспомогательных программ, реализующих import или export, эта возможность позволяет ограничить ссылки частным пространством имён вместо непосредственной записи в refs/heads или refs/remotes. Рекомендуется, чтобы все программы импорта, предоставляющие возможность import, использовали её. Для export она обязательна.

Вспомогательная программа, объявляющая возможность refspec refs/heads/*:refs/svn/origin/branches/*, сообщает, что при запросе import refs/heads/topic создаваемый поток обновит ссылку refs/svn/origin/branches/topic.

Эту возможность можно объявлять несколько раз. Приоритет имеет первая применимая refspec. Левая часть refspec, объявляемых с этой возможностью, должна охватывать все ссылки, возвращаемые командой list. Если возможность refspec не объявлена, подразумевается refspec *:*.

При создании вспомогательных программ для децентрализованных систем управления версиями рекомендуется хранить локальную копию репозитория для взаимодействия с ней и направлять ссылки частного пространства имён на этот локальный репозиторий, используя пространство имён refs/remotes для отслеживания удалённого репозитория.

bidi-import

Эта возможность изменяет import. Команды fast-import cat-blob и ls могут использоваться вспомогательными программами для получения сведений о BLOB-объектах и деревьях, которые уже находятся в памяти fast-import. Для этого требуется канал связи от fast-import к вспомогательной программе. Если эта возможность объявлена вместе с "import", Git создаёт канал от fast-import к стандартному вводу вспомогательной программы. Таким образом, стандартный ввод вспомогательной программы одновременно подключён и к Git, и к fast-import. Поскольку Git может отправлять вспомогательной программе несколько команд, программы, использующие bidi-import, должны буферизовать все команды import из пакета, прежде чем отправлять данные в fast-import. Это необходимо, чтобы команды и ответы fast-import не смешивались в стандартном вводе вспомогательной программы.

export-marks <file>

Изменяет возможность export, указывая Git по завершении записать внутреннюю таблицу меток в <file>. Подробности см. в описании --export-marks=<file> в git-fast-export[1].

import-marks <file>

Изменяет возможность export, указывая Git загрузить метки, заданные в <file>, до обработки любых входных данных. Подробности см. в описании --import-marks=<file> в git-fast-export[1].

signed-tags

Изменяет возможность export, указывая Git передать --signed-tags=verbatim команде git-fast-export[1]. Если эта возможность отсутствует, Git будет использовать --signed-tags=warn-strip.

object-format

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

Команды

Вызывающая программа передаёт команды во вспомогательную программу через её стандартный ввод, по одной команде в строке.

capabilities

Выводит список возможностей вспомогательной программы, по одной в строке, завершая его пустой строкой. Перед каждой возможностью может стоять *, указывающий, что версии Git, использующие эту вспомогательную программу, обязаны её понимать. Неизвестная обязательная возможность приводит к фатальной ошибке.

Поддержка этой команды обязательна.

list

Выводит список ссылок, по одной в строке, в формате "<value> <name> [<attr> …]". Значением может быть шестнадцатеричный хеш sha1, "@<dest>" для символической ссылки, ":<keyword> <value>" для пары «ключ-значение» или "?", означающий, что вспомогательная программа не смогла получить значение ссылки. После имени указывается разделённый пробелами список атрибутов; неизвестные атрибуты игнорируются. Список завершается пустой строкой.

Список существующих атрибутов см. в разделе «АТРИБУТЫ СПИСКА ССЫЛОК». Список существующих ключевых слов см. в разделе «КЛЮЧЕВЫЕ СЛОВА СПИСКА ССЫЛОК».

Поддерживается, если вспомогательная программа имеет возможность "fetch" или "import".

list for-push

Аналогична list, но используется только в том случае, если вызывающей программе нужен список ссылок для подготовки команд отправки изменений. Вспомогательная программа, поддерживающая и push, и fetch, может использовать эту команду, чтобы определить, для какой операции будет использован вывод list, и при необходимости сократить объём выполняемой работы.

Поддерживается, если вспомогательная программа имеет возможность "push" или "export".

option <name> <value>

Задаёт параметру транспортной вспомогательной программы <name> значение <value>. Выводит одну строку с одним из значений ok (параметр успешно задан), unsupported (параметр не распознан) или error <msg> (параметр <name> поддерживается, но значение <value> для него недопустимо). Параметры следует задавать до других команд; они могут влиять на их поведение.

Список существующих параметров см. в разделе «ПАРАМЕТРЫ».

Поддерживается, если вспомогательная программа имеет возможность "option".

fetch <sha1> <name>

Получает указанный объект, записывая необходимые объекты в базу данных. Команды fetch отправляются пакетом, по одной в строке, и завершаются пустой строкой. Когда все команды fetch в одном пакете выполнены, выводится одна пустая строка. Таким способом можно получить только объекты с sha1, указанные в выводе list.

При необходимости может быть выведена строка lock <file> с полным путём к файлу в каталоге $GIT_DIR/objects/pack, который удерживает пакет до тех пор, пока ссылки не будут обновлены надлежащим образом. Путь должен оканчиваться на .keep. Этот механизм позволяет указать кортеж <pack,idx,keep>, передав только компонент keep. Пакет не будет удалён при параллельном repack, даже если на его объекты пока нет ссылок до завершения fetch. По завершении fetch файл .keep будет удалён.

Если запрошен параметр check-connectivity, вспомогательная программа должна вывести connectivity-ok, если клон является самодостаточным и связным.

Поддерживается, если вспомогательная программа имеет возможность "fetch".

push +<src>:<dst>

Отправляет указанный локальный коммит или ветку <src> в удалённую ветку, заданную как <dst>. Пакет из одной или нескольких команд push завершается пустой строкой (если требуется отправить только одну ссылку, после единственной команды push следует пустая строка). Например, ниже показаны два пакета команд push: в первом вспомогательной программе предлагается отправить локальную ссылку master в удалённую ссылку master, а локальную HEAD — в удалённую branch; во втором предлагается отправить ссылку foo в ссылку bar (запрошено принудительное обновление с помощью +).

push refs/heads/master:refs/heads/master
push HEAD:refs/heads/branch
\n
push +refs/heads/foo:refs/heads/bar
\n

После последней команды push, но до завершающей пустой строки пакета, можно указать ноль или более параметров протокола.

По завершении отправки выводится одна или несколько строк ok <dst> или error <dst> <why>?, указывающих на успех или неудачу отправки каждой ссылки. Отчёт о состоянии завершается пустой строкой. Поле параметра <why> можно заключить в кавычки в стиле C, если оно содержит LF.

Поддерживается, если вспомогательная программа имеет возможность "push".

import <name>

Создаёт поток fast-import, импортирующий текущее значение указанной ссылки. Для эффективного построения истории могут быть также импортированы другие ссылки. Скрипт записывает данные в частное пространство имён, принадлежащее вспомогательной программе. Значение указанной ссылки должно быть записано в расположение этого пространства имён, полученное применением refspec из возможности "refspec" к имени ссылки.

Особенно полезно для взаимодействия с внешней системой контроля версий.

Как и push, пакет из одной или нескольких команд import завершается пустой строкой. Для каждого пакета import вспомогательная программа для удалённого репозитория должна создать поток fast-import, завершающийся командой done.

Обратите внимание: если используется возможность bidi-import, весь пакет команд необходимо буферизовать до начала отправки данных в fast-import, чтобы команды и ответы fast-import не смешивались в стандартном вводе вспомогательной программы.

Поддерживается, если вспомогательная программа имеет возможность "import".

export

Указывает вспомогательной программе, что все последующие входные данные относятся к потоку fast-import (созданному командой git fast-export), содержащему объекты, которые следует отправить на удалённый сервер.

Особенно полезно для взаимодействия с внешней системой контроля версий.

Если заданы возможности export-marks и import-marks, они влияют на выполнение этой команды: их передают команде git fast-export, которая затем загружает или сохраняет таблицу меток локальных объектов. Это можно использовать для реализации инкрементальных операций.

Поддерживается, если вспомогательная программа имеет возможность "export".

connect <service>

Подключается к указанной службе. Стандартный ввод и стандартный вывод вспомогательной программы подключаются к указанной службе (имя службы включает префикс git; например, для получения данных используется git-upload-pack) на удалённой стороне. Допустимые ответы на эту команду: пустая строка (соединение установлено), fallback (поддержка интеллектуального транспорта отсутствует, следует перейти к простому транспорту) или завершение работы с выводом сообщения об ошибке (подключиться не удалось, не следует пытаться переключиться на другой транспорт). После символа перевода строки, завершающего положительный (пустой) ответ, начинается вывод службы. После завершения соединения вспомогательная программа завершает работу.

Поддерживается, если вспомогательная программа имеет возможность "connect".

stateless-connect <service>

Экспериментальная возможность; только для внутреннего использования. Подключается к указанной удалённой службе для обмена данными с использованием версии 2 wire-протокола Git. Допустимые ответы на эту команду: пустая строка (соединение установлено), fallback (поддержка интеллектуального транспорта отсутствует, следует перейти к простому транспорту) или завершение работы с выводом сообщения об ошибке (подключиться не удалось, не следует пытаться переключиться на другой транспорт). После символа перевода строки, завершающего положительный (пустой) ответ, начинается вывод службы. Сообщения (как запросы, так и ответы) должны состоять из нуля или более PKT-LINE и завершаться пакетом сброса. После пакета сброса сообщения ответа содержат пакет окончания ответа, указывающий на завершение ответа. Клиент не должен рассчитывать на сохранение сервером какого-либо состояния между парами запрос-ответ. После завершения соединения вспомогательная программа завершает работу.

Поддерживается, если вспомогательная программа имеет возможность "stateless-connect".

get <uri> <path>

Загружает файл по указанному <uri> в заданный <path>. Если существует <path>.temp, Git предполагает, что файл .temp содержит частично загруженные данные после предыдущей попытки, и продолжает загрузку с этой позиции.

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

Могут поддерживаться и дополнительные команды; это определяется по возможностям, объявленным вспомогательной программой.

Атрибуты списка ссылок

Команда list выводит список ссылок, после каждой из которых может следовать список атрибутов. Определены следующие атрибуты списка ссылок.

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

Ключевые слова списка ссылок

Команда list может выводить список пар «ключ-значение». Определены следующие ключи.

object-format: Для ссылок используется указанный алгоритм хеширования. Это ключевое слово используется только в том случае, если и сервер, и клиент поддерживают расширение object-format.

Параметры

Определены следующие параметры; при соответствующих условиях Git задаёт их, если вспомогательная программа для удалённого репозитория имеет возможность option.

option verbosity <n>: Изменяет подробность сообщений, выводимых вспомогательной программой. Значение <n>, равное 0, означает, что процессы работают без вывода сообщений, а вспомогательная программа выводит только сообщения об ошибках. Значение 1 — уровень подробности по умолчанию; более высокие значения <n> соответствуют количеству флагов -v, переданных в командной строке.
option progress {true|false}: Включает или отключает сообщения о ходе выполнения, выводимые транспортной вспомогательной программой во время команды.
option depth <depth>: Углубляет историю неглубокого репозитория.
option deepen-since <timestamp>: Углубляет историю неглубокого репозитория с учётом времени.
option deepen-not <ref>: Углубляет историю неглубокого репозитория, исключая указанную ссылку. Несколько параметров суммируются.
option deepen-relative {true|false}: Углубляет историю неглубокого репозитория относительно текущей границы. Допустим только при использовании вместе с "option depth".
option followtags {true|false}: Если параметр включён, вспомогательная программа должна автоматически получать объекты аннотированных тегов, если объект, на который указывает тег, был передан во время выполнения команды fetch. Если вспомогательная программа не получает тег, обычно отправляется вторая команда fetch с отдельным запросом этого тега. Некоторые вспомогательные программы могут использовать этот параметр, чтобы избежать второго сетевого подключения.
option dry-run {true|false}: Если значение равно true, операция считается успешно завершённой, но данные репозитория фактически не изменяются. Для большинства вспомогательных программ это относится только к push, если такая возможность поддерживается.
option servpath <c-style-quoted-path>: Задаёт путь к службе (--upload-pack, --receive-pack и т. д.) для следующего подключения. Вспомогательная программа для удалённого репозитория может поддерживать этот параметр, но не должна рассчитывать, что он будет задан до выполнения запроса на подключение.
option check-connectivity {true|false}: Запрашивает у вспомогательной программы проверку связности клона.
option force {true|false}: Запрашивает у вспомогательной программы принудительное обновление. По умолчанию используется значение false.
option cloning {true|false}: Сообщает вспомогательной программе, что запрошено клонирование (то есть текущий репозиторий гарантированно пуст).
option update-shallow {true|false}: Разрешает расширять .git/shallow, если этого требуют новые ссылки.
option pushcert {true|false}: Подписывать отправки изменений с помощью GPG.
option push-option <string>: Передаёт <string> как параметр отправки изменений. Поскольку параметр отправки не должен содержать символы LF или NUL, строка не кодируется.
option from-promisor {true|false}: Указывает, что эти объекты получаются от promisor.
option no-dependents {true|false}: Указывает, что нужно получить только запрошенные объекты, но не их зависимые объекты.
option atomic {true|false}: При отправке изменений запрашивает у удалённого сервера обновление ссылок в рамках одной атомарной транзакции. В случае успеха будут обновлены все ссылки или ни одна. Если удалённая сторона не поддерживает эту возможность, отправка завершится ошибкой.
option object-format true: Указывает, что вызывающая программа хочет получить от удалённой стороны сведения об алгоритме хеширования. Этот режим используется при получении ссылок.

См. также

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/gitremote-helpers