Русский ▾ Topics ▾ Latest version ▾ git-fetch last updated in 2.54.0

НАЗВАНИЕ

git-fetch - Загрузка объектов и ссылок из другого репозитория

ОБЗОР

git fetch [<параметры>] [<репозиторий> [<спецификатор-ссылки>…​]]
git fetch [<параметры>] <группа>
git fetch --multiple [<параметры>] [(<репозиторий>|<группа>)…​]
git fetch --all [<параметры>]

ОПИСАНИЕ

Получает (fetch) ветки и/или метки (совместно называемые «ссылки») из одного или нескольких других репозиториев вместе с объектами, необходимыми для завершения их историй. Отслеживаемые внешние ветки обновляются (способы управления этим поведением см. в описании <спецификатор-ссылки> ниже).

По умолчанию любая метка, указывающая на получаемые истории, также получается; в результате получаются метки, указывающие на ветки, которые вас интересуют. Это поведение по умолчанию можно изменить, используя параметры --tags или --no-tags или настроив remote.<имя>.tagOpt. Используя спецификатор ссылки, который явно получает метки, вы также можете получать метки, которые не указывают на интересующие вас ветки.

git fetch может получать данные либо из одного именованного репозитория или URL-адреса, либо сразу из нескольких репозиториев, если задана <группа> и в файле конфигурации есть запись remotes.<группа>. (См. git-config[1]).

Если внешний репозиторий не указан, по умолчанию будет использоваться внешний репозиторий origin, если только для текущей ветки не настроена вышестоящая (upstream) ветка.

Имена полученных ссылок вместе с именами объектов, на которые они указывают, записываются в .git/FETCH_HEAD. Эта информация может использоваться сценариями или другими командами git, такими как git-pull[1].

ПАРАМЕТРЫ

--all
--no-all

Загрузить все удалённые репозитории, за исключением тех, для которых установлена конфигурационная переменная remote.<имя>.skipFetchAll. Это переопределяет конфигурационную переменную fetch.all.

-a
--append

Добавляет имена ссылок и объектов загруженных ссылок к существующему содержимому .git/FETCH_HEAD. Без этой опции старые данные в .git/FETCH_HEAD будут перезаписаны.

--atomic

Использовать атомарную транзакцию для обновления локальных ссылок. Либо все ссылки обновляются, либо при ошибке никакие ссылки не обновляются.

--depth=<глубина>

Ограничивает загрузку указанным количеством коммитов от конца истории каждой удалённой ветки. При загрузке в мелкий (shallow) репозиторий, созданный git clone с опцией --depth=<глубина> (см. git-clone[1]), углубляет или укорачивает историю до указанного количества коммитов. Теги для углублённых коммитов не загружаются.

--deepen=<глубина>

Аналогично --depth, но указывает количество коммитов от текущей границы мелкого репозитория, а не от конца истории каждой удалённой ветки.

--shallow-since=<дата>

Углубляет или укорачивает историю мелкого репозитория, чтобы включить все достижимые коммиты после <даты>.

--shallow-exclude=<ссылка>

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

--unshallow

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

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

--update-shallow

По умолчанию при загрузке из мелкого репозитория git fetch отклоняет ссылки, требующие обновления .git/shallow. Эта опция обновляет .git/shallow и принимает такие ссылки.

--negotiation-tip=(<коммит>|<шаблон-glob>)

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

Эту опцию можно указать несколько раз; в этом случае Git будет сообщать о коммитах, достижимых из любого из указанных коммитов.

Аргументом этой опции может быть glob для имён ссылок, ссылка или (возможно, сокращённый) SHA-1 коммита. Указание glob эквивалентно указанию этой опции несколько раз, по одному разу для каждого совпадающего имени ссылки.

См. также конфигурационные переменные fetch.negotiationAlgorithm и push.negotiate, описанные в git-config[1], и опцию --negotiate-only ниже.

--negotiate-only

Не загружает ничего с сервера, а вместо этого печатает предков указанных аргументов --negotiation-tip=, которые есть у нас общего с сервером.

Несовместимо с --recurse-submodules=(yes|on-demand). Внутренне используется для реализации опции push.negotiate, см. git-config[1].

--dry-run

Показать, что будет сделано, без внесения изменений.

--porcelain

Выводит результат в стандартный вывод в удобном для разбора скриптами формате. Подробности см. в разделе OUTPUT в git-fetch[1].

Несовместимо с --recurse-submodules=(yes|on-demand) и имеет приоритет над опцией конфигурации fetch.output.

--filter=<спецификатор-фильтра>

Использовать функцию частичного клона и запросить, чтобы сервер отправлял подмножество достижимых объектов в соответствии с заданным фильтром объектов. При использовании --filter указанный <спецификатор-фильтра> используется для частичного получения.

Если используется --filter=auto, спецификация фильтра определяется автоматически путём объединения спецификаций фильтра, объявленных сервером для внешних репозиториев-промисоров, которые принимает клиент (см. gitprotocol-v2[5] и параметр конфигурации promisor.acceptFromServer в git-config[1]).

Подробности обо всех других доступных спецификациях фильтров см. в параметре --filter=<спецификатор-фильтра> в git-rev-list[1].

Например, --filter=blob:none отфильтрует все blob-объекты (содержимое файлов), пока они не понадобятся Git. Кроме того, --filter=blob:limit=<размер> отфильтрует все blob-объекты размером не менее <размер>.

--write-fetch-head
--no-write-fetch-head

Записывает список загруженных удалённых ссылок в файл FETCH_HEAD прямо в $GIT_DIR. Это поведение по умолчанию. Передача --no-write-fetch-head из командной строки указывает Git не записывать файл. При опции --dry-run файл никогда не записывается.

-f
--force

Когда git fetch используется с рефспеком <src>:<dst>, он может отказаться обновлять локальную ветку, как обсуждается в части <рефспек> ниже. Этот параметр отменяет эту проверку.

-k
--keep

Сохранять загруженный pack-файл.

--multiple

Позволяет указать несколько аргументов <репозиторий> и <группа>. <рефспек>и не могут быть указаны.

--auto-maintenance
--no-auto-maintenance
--auto-gc
--no-auto-gc

Выполняет git maintenance run --auto в конце для автоматического обслуживания репозитория, если необходимо. Включено по умолчанию.

--write-commit-graph
--no-write-commit-graph

Записывает граф коммитов после загрузки. Это переопределяет настройку конфигурации fetch.writeCommitGraph.

--prefetch

Изменяет настроенный рефспек, чтобы поместить все ссылки в пространство имён refs/prefetch/. См. задачу prefetch в git-maintenance[1].

-p
--prune

Перед загрузкой удаляет все удалённые отслеживающие ссылки, которые больше не существуют на удалённом репозитории. Теги не подлежат обрезке, если они загружаются только из-за автоматического отслеживания тегов по умолчанию или из-за опции --tags. Однако если теги загружаются из-за явного рефспекта (либо в командной строке, либо в конфигурации удалённого репозитория, например, если удалённый репозиторий был клонирован с опцией --mirror), то они также подлежат обрезке. Указание --prune-tags является сокращением для указания рефспекта тега.

Подробности см. в разделе PRUNING ниже.

-P
--prune-tags

Перед загрузкой удаляет все локальные теги, которые больше не существуют на удалённом репозитории, если включена опция --prune. Эту опцию следует использовать более осторожно, в отличие от --prune, она удалит все созданные локальные ссылки (локальные теги). Эта опция является сокращением для указания явного рефспекта тега вместе с --prune, см. обсуждение этого в её документации.

Подробности см. в разделе PRUNING ниже.

-n
--no-tags

По умолчанию теги, указывающие на объекты, загружаемые из удалённого репозитория, загружаются и сохраняются локально. Эта опция отключает это автоматическое отслеживание тегов. Поведение по умолчанию для удалённого репозитория может быть задано настройкой remote.<имя>.tagOpt. См. git-config[1].

--refetch

Вместо согласования с сервером для избежания передачи коммитов и связанных объектов, уже присутствующих локально, эта опция загружает все объекты, как это сделал бы новый клон. Используйте это для повторного применения фильтра частичного клона из конфигурации или с помощью --filter=, когда определение фильтра изменилось. Автоматическое обслуживание после загрузки выполнит консолидацию пакетов базы данных объектов для удаления любых дублирующихся объектов.

--refmap=<спецификатор-ссылки>

При загрузке ссылок, перечисленных в командной строке, использует указанный рефспект (можно указать несколько раз) для отображения ссылок на удалённые отслеживающие ветки вместо значений конфигурационных переменных remote.<имя>.fetch для удалённого репозитория. Предоставление пустого <рефспекта> для опции --refmap заставляет Git игнорировать настроенные рефспекты и полностью полагаться на рефспекты, предоставленные в качестве аргументов командной строки. Подробности см. в разделе "Настроенные удалённые отслеживающие ветки".

-t
--tags

Загружает все теги из удалённого репозитория (т.е. загружает удалённые теги refs/tags/* в локальные теги с теми же именами), в дополнение ко всему, что было бы загружено иначе. Использование этой опции само по себе не подвергает теги обрезке, даже если используется --prune (хотя теги всё равно могут быть обрезаны, если они также являются целью явного рефспекта; см. --prune).

--recurse-submodules[=(yes|on-demand|no)]

Управляет тем, следует ли и при каких условиях также загружать новые коммиты подмодулей. При рекурсивном обходе подмодулей git fetch всегда пытается загрузить "изменённые" подмодули, то есть подмодули, у которых есть коммиты, на которые ссылается новый загруженный коммит суперпроекта, но которые отсутствуют в локальном клоне подмодуля. Изменённый подмодуль может быть загружен, если он присутствует локально, например, в $GIT_DIR/modules/ (см. gitsubmodules[7]); если вышестоящий репозиторий добавляет новый подмодуль, этот подмодуль не может быть загружен, пока он не будет клонирован, например, с помощью git submodule update.

При значении on-demand загружаются только изменённые подмодули. При значении yes загружаются все заполненные подмодули, а также подмодули, которые одновременно и незаполнены, и изменены. При значении no подмодули никогда не загружаются.

Если не указано, используется значение fetch.recurseSubmodules, если оно установлено (см. git-config[1]), по умолчанию on-demand, если не установлено. Когда эта опция используется без значения, по умолчанию используется yes.

-j <n>
--jobs=<n>

Параллелизует все формы загрузки до <n> заданий одновременно.

Значение 0 приведёт к использованию некоторого разумного значения по умолчанию.

Если указана опция --multiple, разные удалённые репозитории будут загружаться параллельно. Если загружается несколько подмодулей, они также будут загружаться параллельно. Чтобы управлять ими независимо, используйте настройки конфигурации fetch.parallel и submodule.fetchJobs (см. git-config[1]).

Обычно параллельная рекурсивная и многопользовательская загрузка будет быстрее. По умолчанию загрузка выполняется последовательно, а не параллельно.

--no-recurse-submodules

Отключает рекурсивную загрузку подмодулей (имеет тот же эффект, что и использование опции --recurse-submodules=no).

--set-upstream

Если удалённый репозиторий успешно загружен, добавляет вышестоящую (отслеживающую) ссылку, используемую командой git-pull[1] без аргументов и другими командами. Для получения дополнительной информации см. branch.<имя>.merge и branch.<имя>.remote в git-config[1].

--submodule-prefix=<путь>

Добавляет <путь> к путям, печатаемым в информационных сообщениях, таких как "Fetching submodule foo". Эта опция используется внутренне при рекурсивном обходе подмодулей.

--recurse-submodules-default=(yes|on-demand)

Эта опция используется внутренне для временного предоставления неотрицательного значения по умолчанию для опции --recurse-submodules. Все другие методы настройки рекурсии подмодулей fetch (такие как настройки в gitmodules[5] и git-config[1]) переопределяют эту опцию, как и прямое указание --[no-]recurse-submodules.

-u
--update-head-ok

По умолчанию git fetch отказывается обновлять голову, соответствующую текущей ветке. Этот флаг отключает проверку. Это исключительно для внутреннего использования git pull для связи с git fetch, и если вы не реализуете свою собственную Porcelain-оболочку, вам не следует её использовать.

--upload-pack <пакет-отправки>

Когда указано и репозиторий для извлечения обрабатывается git fetch-pack, --exec=<пакет-отправки> передаётся команде для указания нестандартного пути для команды, выполняемой на другом конце.

-q
--quiet

Передать --quiet в git-fetch-pack и отключить вывод любых других внутренне используемых команд git. Прогресс не сообщается в стандартный поток ошибок.

-v
--verbose

Быть многословнее.

--progress

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

-o <параметр>
--server-option=<параметры>

Передать заданную строку на сервер при обмене данными по протоколу версии 2. Заданная строка не должна содержать символы NUL или LF. Обработка сервером параметров сервера, включая неизвестные, зависит от конкретного сервера. Когда указано несколько --server-option=<параметр>, все они отправляются на другую сторону в порядке, перечисленном в командной строке. Если в командной строке не указано ни одной --server-option=<параметр>, вместо этого используются значения переменной конфигурации remote.<имя>.serverOption.

--show-forced-updates

По умолчанию git проверяет, была ли ветка принудительно обновлена во время загрузки. Это можно отключить через fetch.showForcedUpdates, но опция --show-forced-updates гарантирует выполнение этой проверки. См. git-config[1].

--no-show-forced-updates

По умолчанию git проверяет, была ли ветка принудительно обновлена во время загрузки. Передайте --no-show-forced-updates или установите fetch.showForcedUpdates в false, чтобы пропустить эту проверку по соображениям производительности. Если используется во время git-pull, опция --ff-only всё равно будет проверять принудительные обновления перед попыткой быстрого перемотки. См. git-config[1].

-4
--ipv4

Использовать только IPv4 адреса, игнорируя IPv6 адреса.

-6
--ipv6

Использовать только IPv6 адреса, игнорируя адреса IPv4.

<репозиторий>

«Внешний» (remote) репозиторий, являющийся источником операции получения (fetch) или извлечения (pull). Этот параметр может быть либо URL-адресом (см. раздел URL-АДРЕСА GIT ниже), либо именем внешнего репозитория (см. раздел ВНЕШНИЕ РЕПОЗИТОРИИ ниже).

<группа>

Имя, ссылающееся на список репозиториев, заданное как значение параметра remotes.<group> в конфигурационном файле. (См. git-config[1]).

<спецификатор-ссылки>

Указывает, какие ссылки получать (fetch) и какие локальные ссылки обновлять. Если в командной строке нет <спецификатор-ссылки>, получаемые ссылки считываются из переменных remote.<репозиторий>.fetch (см. НАСТРОЕННЫЕ ОТСЛЕЖИВАЕМЫЕ ВНЕШНИЕ ВЕТКИ ниже).

Формат параметра <спецификатор-ссылки>: необязательный плюс +, затем источник <источник>, затем двоеточие :, затем назначение <назначение>. Двоеточие можно опустить, если <назначение> пусто. <источник> обычно является ссылкой или glob-шаблоном с одним символом *, используемым для сопоставления набора ссылок, но также может быть полностью указанным шестнадцатеричным именем объекта.

<спецификатор-ссылки> может содержать * в своём <источник> для указания простого сопоставления с образцом. Такой спецификатор ссылки функционирует как glob-шаблон, соответствующий любой ссылке, подходящей под образец. Шаблонный <спецификатор-ссылки> должен содержать один и только один * как в <источник>, так и в <назначение>. Он будет сопоставлять ссылки с назначением, заменяя * содержимым, сопоставленным из источника.

Если спецификатор ссылки имеет префикс ^, он интерпретируется как отрицательный спецификатор ссылки. Такой спецификатор ссылки вместо указания того, какие ссылки получать или какие локальные ссылки обновлять, указывает ссылки для исключения. Ссылка будет считаться соответствующей, если она соответствует хотя бы одному положительному спецификатору ссылки и не соответствует ни одному отрицательному спецификатору ссылки. Отрицательные спецификаторы ссылок могут быть полезны для ограничения области действия шаблонного спецификатора ссылки, чтобы он не включал определённые ссылки. Отрицательные спецификаторы ссылок сами могут быть шаблонными спецификаторами ссылок. Однако они могут содержать только <источник> и не указывают <назначение>. Полностью указанные шестнадцатеричные имена объектов также не поддерживаются.

tag <метка> означает то же, что и refs/tags/<метка>:refs/tags/<метка>; это запрашивает получение всего вплоть до указанной метки.

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

Разрешено ли такое обновление без --force, зависит от пространства имён ссылок, в которое оно извлекается, типа получаемого объекта и того, считается ли обновление перемоткой вперёд (fast-forward). Как правило, для получения (fetch) применяются те же правила, что и для отправки (push); узнать, что это за правила, можно в разделе <спецификатор-ссылки>... git-push[1]. Исключения из этих правил, характерные для git fetch, отмечены ниже.

До версии Git 2.20, в отличие от отправки с помощью git-push[1], любые обновления refs/tags/* принимались без + в спецификаторе ссылки (или --force). При получении мы без разбора считали все обновления меток из внешнего репозитория принудительными получениями. Начиная с версии Git 2.20, получение для обновления refs/tags/* работает так же, как и при отправке. Т.е. любые обновления будут отклоняться без + в спецификаторе ссылки (или --force).

В отличие от отправки с помощью git-push[1], любые обновления за пределами refs/{tags,heads}/* будут приниматься без + в спецификаторе ссылки (или --force), будь то замена, например, объекта-дерева на blob-объект или коммита на другой коммит, у которого предыдущий коммит не является предком, и т.д.

В отличие от отправки с помощью git-push[1], не существует конфигурации, которая изменяла бы эти правила, и нет ничего похожего на перехватчик (hook) pre-fetch, аналогичный перехватчику pre-receive.

Как и при отправке с помощью git-push[1], все описанные выше правила относительно того, что не разрешено в качестве обновления, можно отменить, добавив необязательный начальный символ + к спецификатору ссылки (или используя параметр командной строки --force). Единственным исключением является то, что никакое принуждение не заставит пространство имён refs/heads/* принять объект, не являющийся коммитом.

Note
 Если известно, что внешняя ветка, которую вы хотите получить, регулярно перематывается назад и перемещается (rebase), ожидается, что её новая верхушка (tip) не будет потомком её предыдущей верхушки (как сохранено в вашей отслеживаемой внешней ветке при последнем получении). Вам следует использовать знак +, чтобы указать, что для таких веток потребуются обновления, не являющиеся перемоткой вперёд. Невозможно определить или объявить, что ветка будет доступна в репозитории с таким поведением; пользователь, выполняющий извлечение (pull), просто должен знать, что это ожидаемый шаблон использования для данной ветки.
--stdin

Читать спецификаторы ссылок (refspecs), по одному на строку, из stdin в дополнение к тем, которые предоставлены в качестве аргументов. Формат "tag <имя>" не поддерживается.

URL-АДРЕСА GIT

В целом, URL-адреса содержат информацию о транспортном протоколе, адресе удалённого сервера и пути к репозиторию. В зависимости от транспортного протокола, некоторые из этих элементов могут отсутствовать.

Git поддерживает следующие протоколы: ssh, git, http и https (кроме того, ftp и ftps могут быть использованы для извлечения из репозиториев, но это неэффективно и является устаревшей (deprecated) возможностью; не используйте эти протоколы).

Родной транспорт (т.е. адреса вида git://) не имеет аутентификации и должен использоваться с осторожностью в незащищённых сетях.

Для этих протоколов может использоваться следующий синтаксис:

  • ssh://[<пользователь>@]<хост>[:<порт>]/<путь-к-репозиторию-git>

  • git://<хост>[:<порт>]/<путь-к-репозиторию-git>

  • http[s]://<хост>[:<порт>]/<путь-к-репозиторию-git>

  • ftp[s]://<хост>[:<порт>]/<путь-к-репозиторию-git>

В качестве альтернативы для протокола ssh можно также использовать scp-подобный синтаксис:

  • [<пользователь>@]<хост>:/<путь-к-репозиторию-git>

Этот синтаксис распознаётся только в том случае, если перед первым двоеточием нет слэшей. Это позволяет отличить его от локального пути, который содержит двоеточие. Например, локальный путь foo:bar можно записан как ./foo:bar или как абсолютный путь, дабы он не был бы ошибочно интерпретирован как ssh-адреса.

Кроме того протоколы ssh и git поддерживают расширение ~<имени-пользователя>:

  • ssh://[<пользователь>@]<хост>[:<порт>]/~<имя-пользователя>/<путь-к-репозиторию-git>

  • git://<хост>[:<порт>]/~<имя-пользователя>/<путь-к-репозиторию-git>

  • [<пользователь>@]<хост>:/~<имя-пользователя>/<путь-к-репозиторию-git>

Для локальных репозиториев, для которых поддержка у Git также родная, могут использоваться следующие варианты синтаксиса:

  • /путь/к/репозиторию.git/

  • file:///путь/к/репозиторию.git/

Эти два синтаксиса по большей части эквивалентны, кроме как при клонировании; в этом случае первый подразумевает параметр --local. См. подробности в git-clone[1].

git clone, git fetch и git pull, но не git push, также примут сформированный соответствующим образом pack-файл. См. git-bundle[1].

Когда Git не знает, как работать с определённым транспортным протоколом, он пытается использовать вспомогательную программу remote-<транспорт>, помощник работы со внешним репозиторием, если таковая существует. Для явного запроса такого помощника можно использовать следующий синтаксис:

  • <транспорт>::<адрес>

где <адрес> может быть путём, сервером и путём, или произвольной URL-подобной строкой, которая распознаётся конкретным помощником работы с удалённым репозиторием. См. подробности в gitremote-helpers[7].

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

	[url "<настоящая-база-url>"]
		insteadOf = <другая-база-url>

Например, при такой конфигурации:

	[url "git://git.host.xz/"]
		insteadOf = host.xz:/path/to/
		insteadOf = work:

URL-адрес вида "work:repo.git" или "host.xz:/path/to/repo.git", будет преобразовываться в любом контексте, в котором ожидается URL-адрес, в "git.host.xz/repo.git".

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

	[url "<настоящая-база-url>"]
		pushInsteadOf = <другая-база-url>

Например, при такой конфигурации:

	[url "ssh://example.org/"]
		pushInsteadOf = git://example.org/

URL-адрес вида "git://example.org/path/to/repo.git", будет преобразован в "ssh://example.org/path/to/repo.git" для отправки изменений, но при получении изменений будет по-прежнему использоваться оригинальный URL-адрес.

ВНЕШНИЕ РЕПОЗИТОРИИ

Имя одного из следующих может использоваться вместо URL в качестве аргумента <репозиторий>:

  • внешний репозиторий в файле конфигурации Git: $GIT_DIR/config,

  • файл в каталоге $GIT_DIR/remotes или

  • файл в каталоге $GIT_DIR/branches.

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

Именованный внешний репозиторий в файле конфигурации

Вы можете указать имя внешнего репозитория, который вы ранее настроили с помощью git-remote[1], git-config[1] или даже путём ручного редактирования файла $GIT_DIR/config. URL этого внешнего репозитория будет использоваться для доступа к репозиторию. Спецификатор ссылки этого внешнего репозитория будет использоваться по умолчанию, если вы не укажете спецификатор ссылки в командной строке. Запись в файле конфигурации будет выглядеть так:

	[remote "<имя>"]
		url = <URL>
		pushurl = <URL-отправки>
		push = <спецификатор-ссылки>
		fetch = <спецификатор-ссылки>

<URL-отправки> используется только для отправки. Он необязателен и по умолчанию равен <URL>. Отправка во внешний репозиторий влияет на все определённые pushurl-ы или все определённые url-ы, если pushurl-ы не определены. Однако получение будет выполняться только из первого определённого url, если определено несколько url-ов.

Именованный файл в $GIT_DIR/remotes

Вы можете указать имя файла в $GIT_DIR/remotes. URL в этом файле будет использоваться для доступа к репозиторию. Спецификатор ссылки в этом файле будет использоваться по умолчанию, если вы не укажете спецификатор ссылки в командной строке. Этот файл должен иметь следующий формат:

	URL: один из вышеуказанных форматов URL
	Push: <спецификатор-ссылки>
	Pull: <спецификатор-ссылки>

Строки Push: используются git push, а строки Pull: используются git pull и git fetch. Для дополнительных сопоставлений веток может быть указано несколько строк Push: и Pull:.

Именованный файл в $GIT_DIR/branches

Вы можете указать имя файла в $GIT_DIR/branches. URL в этом файле будет использоваться для доступа к репозиторию. Этот файл должен иметь следующий формат:

	<URL>#<голова>

<URL> обязателен; #<голова> необязателен.

В зависимости от операции git будет использовать один из следующих спецификаторов ссылок, если вы не укажете его в командной строке. <ветка> — это имя этого файла в $GIT_DIR/branches, а <голова> по умолчанию равна master.

git fetch использует:

	refs/heads/<голова>:refs/heads/<ветка>

git push использует:

	HEAD:refs/heads/<голова>

ВЫШЕСТОЯЩИЕ ВЕТКИ

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

  • Это значение по умолчанию для git pull или git fetch без аргументов.

  • Это значение по умолчанию для git push без аргументов, с некоторыми исключениями. Например, вы можете использовать параметр branch.<имя>.pushRemote, чтобы отправлять в другой внешний репозиторий, отличный от того, из которого вы получаете, и по умолчанию с push.default=simple настраиваемая вами вышестоящая ветка должна иметь то же имя.

  • Различные команды, включая git checkout и git status, покажут вам, сколько коммитов было добавлено в вашу текущую ветку и вышестоящую с момента ответвления от неё, например: "Ваша ветка и origin/main разошлись, и имеют 2 и 3 разных коммита соответственно".

Вышестоящая ветка хранится в .git/config в полях "remote" и "merge". Например, если вышестоящей для main является origin/main:

[branch "main"]
   remote = origin
   merge = refs/heads/main

Вы можете явно установить вышестоящую ветку с помощью git push --set-upstream <внешний-репозиторий> <ветка>, но Git часто автоматически устанавливает вышестоящую ветку за вас, например:

  • Когда вы клонируете репозиторий, Git автоматически устанавливает вышестоящую ветку для ветки по умолчанию.

  • Если у вас установлен параметр конфигурации push.autoSetupRemote, git push автоматически установит вышестоящую ветку при первой отправке ветки.

  • Переключение на отслеживаемую внешнюю ветку с помощью git checkout <ветка> автоматически создаст локальную ветку с этим именем и установит вышестоящую ветку на внешнюю ветку.

Note
 Вышестоящие ветки иногда называют "информацией об отслеживании", как в выражении "установить информацию об отслеживании ветки".

НАСТРОЕННЫЕ ОТСЛЕЖИВАЕМЫЕ ВНЕШНИЕ ВЕТКИ

Вы часто взаимодействуете с одним и тем же внешним репозиторием, регулярно и многократно получая из него данные. Чтобы отслеживать прогресс такого внешнего репозитория, git fetch позволяет вам настроить переменные конфигурации remote.<репозиторий>.fetch.

Обычно такая переменная может выглядеть так:

[remote "origin"]
	fetch = +refs/heads/*:refs/remotes/origin/*

Эта конфигурация используется двумя способами:

  • Когда git fetch запускается без указания того, какие ветки и/или метки получать в командной строке, например git fetch origin или git fetch, значения remote.<репозиторий>.fetch используются в качестве спецификаторов ссылок — они определяют, какие ссылки получать и какие локальные ссылки обновлять. Приведённый выше пример получит все ветки, существующие в origin (т.е. любую ссылку, соответствующую левой части значения, refs/heads/*), и обновит соответствующие отслеживаемые внешние ветки в иерархии refs/remotes/origin/*.

  • Когда git fetch запускается с явными ветками и/или метками для получения в командной строке, например git fetch origin master, <спецификаторы-ссылки>, заданные в командной строке, определяют, что должно быть получено (например, master в примере, что является сокращением для master:, что в свою очередь означает «получить ветку master, но я явно не указываю, какую отслеживаемую внешнюю ветку обновить с её помощью из командной строки»), и пример команды получит только ветку master. Значения remote.<репозиторий>.fetch определяют, какая отслеживаемая внешняя ветка (если таковая имеется) обновляется. При использовании таким образом значения remote.<репозиторий>.fetch не влияют на решение что получать (т.е. значения не используются в качестве спецификаторов ссылок, когда командная строка перечисляет спецификаторы ссылок); они используются только для определения где хранятся полученные ссылки, действуя как отображение.

Последнее использование значений remote.<репозиторий>.fetch можно переопределить, указав параметр(ы) --refmap=<спецификатор-ссылки> в командной строке.

ОБРЕЗКА

Git по умолчанию хранит данные, если они не удалены явно; это распространяется и на хранение локальных ссылок на ветки во внешних репозиториях, которые сами удалили эти ветки.

Если позволить им накапливаться, эти устаревшие ссылки могут ухудшить производительность в больших и активных репозиториях с частым изменением веток и, например, сделать вывод таких команд, как git branch -a --contains <коммит>, излишне подробным, а также повлиять на всё остальное, что работает с полным набором известных ссылок.

Эти отслеживаемые внешние ссылки могут быть удалены разово с помощью одной из следующих команд:

# Во время получения (fetch)
$ git fetch --prune <имя>

# Только подчистка (prune), без получения (fetch)
$ git remote prune <имя>

Чтобы подчищать ссылки как часть вашего обычного рабочего процесса без необходимости помнить о запуске этой команды, установите fetch.prune глобально или remote.<имя>.prune для каждого внешнего репозитория в конфигурации. См. git-config[1].

Здесь всё становится сложнее и конкретнее. Функция подчистки на самом деле не заботится о ветках; вместо этого она подчищает локальные ←→ внешние ссылки как функцию спецификатора ссылки внешнего репозитория (см. <спецификатор-ссылки> и НАСТРОЕННЫЕ ОТСЛЕЖИВАЕМЫЕ ВНЕШНИЕ ВЕТКИ выше).

Поэтому, если спецификатор ссылки для внешнего репозитория включает, например, refs/tags/*:refs/tags/*, или вы вручную выполняете, например, git fetch --prune <имя> "refs/tags/*:refs/tags/*", то будут удалены не устаревшие отслеживаемые внешние ветки, а любые локальные метки, которые не существуют во внешнем репозитории.

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

Поэтому будьте осторожны при использовании этого с таким спецификатором ссылки, как refs/tags/*:refs/tags/*, или любым другим спецификатором ссылки, который может отображать ссылки из нескольких внешних репозиториев в одно и то же локальное пространство имён.

Поскольку поддержание актуальности как веток, так и меток во внешнем репозитории является распространённым случаем использования, опция --prune-tags может быть предоставлена вместе с --prune для подчистки локальных меток, которых нет во внешнем репозитории, и принудительного обновления тех меток, которые отличаются. Подчистка меток также может быть включена с помощью fetch.pruneTags или remote.<имя>.pruneTags в конфигурации. См. git-config[1].

Параметр --prune-tags эквивалентен объявлению refs/tags/*:refs/tags/* в спецификаторах ссылок внешнего репозитория. Это может привести к некоторым, казалось бы, странным взаимодействиям:

# Оба этих варианта получают метки
$ git fetch --no-tags origin 'refs/tags/*:refs/tags/*'
$ git fetch --no-tags --prune-tags origin

Причина, по которой он не завершается ошибкой при предоставлении без --prune или его версий в конфигурации, заключается в гибкости настроенных версий и в поддержании соответствия 1:1 между тем, что делают флаги командной строки, и тем, что делают версии в конфигурации.

Разумно, например, настроить fetch.pruneTags=true в ~/.gitconfig, чтобы метки подчищались всякий раз, когда выполняется git fetch --prune, не делая каждый вызов git fetch без --prune ошибочным.

Подчистка меток с помощью --prune-tags также работает при получении из URL-адреса вместо именованного внешнего репозитория. Все эти команды подчистят метки, не найденные в origin:

$ git fetch origin --prune --prune-tags
$ git fetch origin --prune 'refs/tags/*:refs/tags/*'
$ git fetch <url-of-origin> --prune --prune-tags
$ git fetch <url-of-origin> --prune 'refs/tags/*:refs/tags/*'

ВЫВОД

Вывод «git fetch» зависит от используемого транспортного метода; в этом разделе описывается вывод при получении по протоколу Git (локально или через ssh) и по протоколу Smart HTTP.

Статус получения выводится в табличной форме, где каждая строка представляет статус одной ссылки. Каждая строка имеет вид:

 <флаг> <сводка> <откуда> -> <куда> [<причина>]

При использовании --porcelain формат вывода предназначен для машинного разбора. В отличие от удобочитаемых форматов вывода, он выводит данные в стандартный вывод (stdout) вместо стандартного потока ошибок. Каждая строка имеет вид:

<флаг> <старый-id-объекта> <новый-id-объекта> <локальная-ссылка>

Состояние актуальных ссылок показывается только в том случае, если используется параметр --verbose.

В компактном режиме вывода, задаваемом переменной конфигурации fetch.output, если вся строка <откуда> или <куда> найдена в другой строке, она будет заменена на * в другой строке. Например, master -> origin/master превращается в master -> origin/*.

флаг

Один символ, указывающий статус ссылки:

(пространство)

для успешно полученной перемотки вперёд (fast-forward);

+

для успешного принудительного обновления;

-

для успешно подчищенной ссылки;

t

для успешного обновления метки;

*

для успешно полученной новой ссылки;

!

для ссылки, которая была отклонена или не обновлена; и

=

для ссылки, которая была актуальна и не требовала получения.

summary

Для успешно полученной ссылки в сводке показываются старое и новое значения ссылки в форме, подходящей для использования в качестве аргумента git log (в большинстве случаев это <старое>..<новое>, а для принудительных обновлений, не являющихся перемоткой вперёд — <старое>...<новое>).

из

Имя получаемой внешней ссылки без префикса refs/<тип>/. В случае удаления имя внешней ссылки — «(none)».

в

Имя обновляемой локальной ссылки без префикса refs/<тип>/.

причина

Пояснение, понятное человеку. В случае успешно полученных ссылок пояснение не требуется. Для неудачной ссылки описывается причина сбоя.

ПРИМЕРЫ

  • Обновить отслеживаемые внешние ветки:

    $ git fetch origin

    Вышеуказанная команда копирует все ветки из пространства имён внешнего репозитория refs/heads/ и сохраняет их в локальное пространство имён refs/remotes/origin/, если только опция remote.<репозиторий>.fetch не используется для указания нестандартного спецификатора ссылки.

  • Использование спецификаторов ссылок явно:

    $ git fetch origin +seen:seen maint:tmp

    Это обновляет (или создаёт при необходимости) ветки seen и tmp в локальном репозитории, получая из внешнего репозитория ветки seen и maint соответственно.

    Ветка seen будет обновлена, даже если это не перемотка вперёд (fast-forward), потому что она имеет префикс в виде знака плюс; tmp — нет.

  • Заглянуть в ветку внешнего репозитория, не настраивая внешний репозиторий в вашем локальном репозитории:

    $ git fetch git://git.kernel.org/pub/scm/git/git.git maint
$ git log FETCH_HEAD

    Первая команда получает ветку maint из репозитория по адресу git://git.kernel.org/pub/scm/git/git.git, а вторая команда использует FETCH_HEAD для просмотра ветки с помощью git-log[1]. Полученные объекты в конечном итоге будут удалены встроенными средствами обслуживания git (см. git-gc[1]).

ЗАЩИТА

Протоколы получения (fetch) и отправки (push) не предназначены для предотвращения кражи одной стороной данных из другого репозитория, которые не предназначались для общего доступа. Если у вас есть частные данные, которые необходимо защитить от злонамеренного участника, лучший вариант — хранить их в другом репозитории. Это относится как к клиентам, так и к серверам. В частности, пространства имён на сервере неэффективны для контроля доступа на чтение; вы должны предоставлять доступ на чтение к пространству имён только тем клиентам, которым вы доверили бы доступ на чтение ко всему репозиторию.

Известные векторы атак следующие:

  1. Жертва отправляет строки «have», рекламируя идентификаторы объектов, которые у неё есть и которые явно не предназначены для общего доступа, но могут использоваться для оптимизации передачи, если они также есть у участника. Злоумышленник выбирает идентификатор объекта X для кражи и отправляет ссылку на X, но не обязан отправлять содержимое X, потому что оно уже есть у жертвы. Теперь жертва считает, что у злоумышленника есть X, и позже отправляет содержимое X обратно злоумышленнику. (Эту атаку проще всего выполнить клиенту на сервере, создав ссылку на X в пространстве имён, к которому у клиента есть доступ, а затем получив её. Наиболее вероятный способ для сервера выполнить её на клиенте — «слить» X в публичную ветку и надеяться, что пользователь выполнит дополнительную работу в этой ветке и отправит её обратно на сервер, не заметив слияния.)

  2. Как и в №1, злоумышленник выбирает идентификатор объекта X для кражи. Жертва отправляет объект Y, который у злоумышленника уже есть, а злоумышленник ложно заявляет, что у него есть X, а Y нет, поэтому жертва отправляет Y как дельту относительно X. Дельта раскрывает злоумышленнику области X, похожие на Y.

КОНФИГУРАЦИЯ

Дальнейшее содержание этого раздела, повторяет то, что может быть найдено в git-config[1]:

fetch.recurseSubmodules

Этот параметр управляет тем, будет ли git fetch (и базовое получение в git pull) рекурсивно получать данные в заполненные подмодули. Этот параметр может быть установлен либо в логическое значение, либо в on-demand. Установка в логическое значение изменяет поведение получения и извлечения на безусловную рекурсию в подмодули, если установлено true, или на отсутствие рекурсии вообще, если установлено false. При установке в on-demand получение и извлечение будут рекурсивно заходить в заполненный подмодуль только тогда, когда его суперпроект получает коммит, обновляющий ссылку подмодуля. По умолчанию on-demand или значение submodule.recurse, если оно установлено.

fetch.fsckObjects

Если установлено в true, git-fetch-pack будет проверять все полученные объекты. Что именно проверяется, см. в transfer.fsckObjects. По умолчанию false. Если не установлено, вместо этого используется значение transfer.fsckObjects.

fetch.fsck.<msg-id>

Действует как fsck.<msg-id>, но используется git-fetch-pack[1] вместо git-fsck[1]. Подробности см. в документации fsck.<msg-id>.

fetch.fsck.skipList

Действует как fsck.skipList, но используется git-fetch-pack[1] вместо git-fsck[1]. Подробности см. в документации fsck.skipList.

fetch.unpackLimit

Если количество объектов, полученных по собственному протоколу Git, ниже этого предела, объекты будут распакованы в непакованные (loose) файлы объектов. Однако если количество полученных объектов равно или превышает этот предел, полученный pack-файл будет сохранён как pack-файл после добавления любых недостающих баз дельт. Сохранение pack-файла из отправки может ускорить выполнение операции отправки, особенно на медленных файловых системах. Если не установлено, вместо этого используется значение transfer.unpackLimit.

fetch.prune

Если true, получение будет автоматически вести себя так, как если бы в командной строке была указана опция --prune. См. также remote.<имя>.prune и раздел ПОДЧИСТКА (PRUNING) в git-fetch[1].

fetch.pruneTags

Если true, получение будет автоматически вести себя так, как если бы спецификатор ссылки refs/tags/*:refs/tags/* был предоставлен при подчистке, если он ещё не установлен. Это позволяет установить как эту опцию, так и fetch.prune для поддержания сопоставления 1:1 с вышестоящими (upstream) ссылками. См. также remote.<имя>.pruneTags и раздел ПОДЧИСТКА (PRUNING) в git-fetch[1].

fetch.all

Если true, получение попытается обновить все доступные внешние репозитории. Это поведение можно переопределить, передав --no-all или явно указав один или несколько внешних репозиториев для получения. По умолчанию false.

fetch.output

Управляет тем, как печатается статус обновления ссылок. Допустимые значения: full и compact. Значение по умолчанию: full. Подробности см. в разделе OUTPUT в git-fetch[1].

fetch.negotiationAlgorithm

Управляет тем, как отправляется информация о коммитах в локальном репозитории при согласовании содержимого pack-файла, который будет отправлен сервером. Установите consecutive, чтобы использовать алгоритм, который проходит по последовательным коммитам, проверяя каждый. Установите skipping, чтобы использовать алгоритм, который пропускает коммиты в попытке сойтись быстрее, но может привести к созданию pack-файла большего, чем необходимо; или установите noop, чтобы вообще не отправлять никакую информацию, что почти наверняка приведёт к созданию pack-файла большего, чем необходимо, но пропустит этап согласования. Установите default, чтобы переопределить ранее сделанные настройки и использовать поведение по умолчанию. Обычно по умолчанию используется consecutive, но если feature.experimental равно true, то по умолчанию используется skipping. Неизвестные значения приведут к ошибке git fetch.

См. также опции --negotiate-only и --negotiation-tip в git-fetch[1].

fetch.showForcedUpdates

Установите в false, чтобы включить --no-show-forced-updates в командах git-fetch[1] и git-pull[1]. По умолчанию true.

fetch.parallel

Указывает максимальное количество операций получения, выполняемых параллельно за раз (подмодули или внешние репозитории, когда действует опция --multiple команды git-fetch[1]).

Значение 0 даст некоторое разумное значение по умолчанию. Если не установлено, по умолчанию используется 1.

Для подмодулей этот параметр можно переопределить с помощью настройки конфигурации submodule.fetchJobs.

fetch.writeCommitGraph

Установите true, чтобы записывать граф коммитов после каждой команды git fetch, которая загружает pack-файл из внешнего репозитория. При использовании опции --split большинство выполнений создадут очень маленький файл графа коммитов поверх существующего(их) файла(ов) графа коммитов. Иногда эти файлы будут сливаться, и запись может занять больше времени. Наличие обновлённого файла графа коммитов повышает производительность многих команд Git, включая git merge-base, git push -f и git log --graph. По умолчанию false.

fetch.bundleURI

Это значение хранит URI для загрузки данных объектов Git из bundle URI перед выполнением инкрементального получения с исходного Git-сервера. Это похоже на то, как ведёт себя опция --bundle-uri в git-clone[1]. git clone --bundle-uri установит значение fetch.bundleURI, если предоставленный bundle URI содержит список пакетов, организованный для инкрементальных получений.

Если вы изменяете это значение и в вашем репозитории есть значение fetch.bundleCreationToken, удалите это значение fetch.bundleCreationToken перед получением из нового bundle URI.

fetch.bundleCreationToken

При использовании fetch.bundleURI для инкрементального получения из списка пакетов, использующего эвристику «creationToken», это значение конфигурации хранит максимальное значение creationToken загруженных пакетов. Это значение используется для предотвращения загрузки пакетов в будущем, если объявленный creationToken не строго больше этого значения.

Значения токенов создания выбираются поставщиком, обслуживающим конкретный bundle URI. Если вы изменяете URI в fetch.bundleURI, обязательно удалите значение fetch.bundleCreationToken перед получением.

ОШИБКИ

Использование --recurse-submodules может получать только новые коммиты в подмодулях, которые присутствуют локально, например, в $GIT_DIR/modules/. Если вышестоящий (upstream) репозиторий добавляет новый подмодуль, этот подмодуль не может быть получен, пока он не будет клонирован, например, с помощью git submodule update. Ожидается, что это будет исправлено в будущей версии Git.

СМ. ТАКЖЕ

git-pull[1]

GIT

Является частью пакета git[1]