Введение в зависимости Git

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

Примечание: Вы не можете указать зависимости Git в package.json файл, потому что Package Manager Git не поддерживает зависимости Git между пакетами. Он поддерживает зависимости Git только для проектов, так что вы можете объявить зависимости Git только в manifest.json файл.

Тип: Если вы хотите обновить свою зависимость Git до определенной версии (пересмотр) из хранилища, см. Заблокированные зависимости Git.

В этом разделе рассматриваются следующие темы:

• Потребности в ресурсах
• Гит URLs
  • Использование протокола HTTP/HTTPS
  • Использование протокола SSH
  • Использование протокола FILE
  • Использование протокола GIT
• Расширенный синтаксис
  • Указание ревизии Git
  • Указание пакета в подпапке хранилища
  • Указание ревизий и путей одновременно
• Заблокированные зависимости Git
• Гит LFS Поддержка

Потребности в ресурсах

Чтобы использовать зависимости Git в проекте, убедитесь, что вы установили Клиент Git (минимальная версия 2.14.0) на вашем компьютере и что вы добавили путь к исполняемому файлу Git PATH переменная среды системы.

Предупреждение: Unity проверил Package Manager на работу с Git 2.14.0 и выше. Unity не может гарантировать результаты, если вы используете Git версий ниже 2.14.0.

Если хранилище отслеживает файлы с Git LFS, убедитесь, что клиент Git LFS также установлен на вашей машине. Если он не установлен, Package Manager не может получить файлы, хранящиеся на сервере LFS, и вместо этого извлекает файлы указателя LFS без каких-либо ошибок или предупреждений.

Вы можете использовать окно Package Manager для установки пакета непосредственно из хранилища Git. Дополнительные сведения см. в Установка из Git URL.

Гит URLs

Package Manager поддерживает все Git протоколы, за исключением путей к локальным файлам. Чтобы указать Git URL в качестве зависимости, добавьте в манифест проекта имя пакета, который будет добавлен с Git URL, вместо номера версии или пути к локальному файлу. Например, вот как указать удаленный Git, используя различные протоколы:

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "ssh://git@github.example.com/myuser/myrepository2.git",
    "com.mycompany.mypackage3": "file://localhost/github.example.com/myuser/myrepository3.git",
    "com.mycompany.mypackage4": "git://github.example.com/myuser/myrepository4.git",
    etc.
  }
}

Package Manager распознает зависимость, отформатированную как URL, как Git URL, смотря на расширение файла .git в конце пути к хранилищу. Некоторые сервисы хостинга Git не поддерживают URLs с этим расширением, в то время как другие его поддерживают. По этой причине синтаксис зависимостей Git позволяет опустить расширение, если вы используете протокол GIT, или если вы добавляете специальный префикс git+ к HTTP/HTTPS, SSH, или FILE URL.

Примечание: Префикс git+ является специальным маркером в файле manifest.json, указывающим, что зависимость основана на Git. Package Manager не передает его Git при клонировании хранилища.

Более подробную информацию о поддерживаемом Git формате URLs см. в документации по команде git clone. Обзор различий между протоколами, используемыми Git, см. в документации Git по использованию протоколов.

Вы также можете использовать расширенный синтаксис для зависимостей Git:

• Если пакет, который вы хотите, не находится в корне хранилища, вы можете указать путь к подпапке пакета в хранилище. Это необходимо только если пакет, который вы хотите, не находится в корне хранилища. Например, строка ?path=/folder1/folder2 в:

  "https://github.example.com/myuser/myrepository.git?path=/folder1/folder2".

  Дополнительные сведения см. в Указание пакета в подпапке.

• Вы можете указать ревизию Git, которая может быть меткой, именем ветки или конкретным хэшем фиксации, к которой нужно заблокировать. Это гарантирует, что Package Manager всегда загружает эту точную ревизию. Если вы не указываете ревизию, Package Manager клонирует хранилище в ветку по умолчанию и последнюю фиксацию и заблокирует на этой ревизии. Например, строка #v2.0.0 в:

  "https://github.example.com/myuser/myrepository.git#v2.0.0"

  Дополнительные сведения см. в Указание ревизии Git.

Использование протокола HTTP/HTTPS

Вы можете использовать протокол HTTPS с полным протоколом URL:

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git"
  }
}

Если ваш сервер Git не поддерживает расширение .git, вы можете добавить специальный префикс git+ с расширением или без него:

{
  "dependencies": {
    "com.mycompany.mypackage1": "git+https://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2"
  }
}

Примечание: В качестве альтернативы можно использовать протокол GIT вместо префикса git+. Дополнительные сведения см. в Использование протокола GIT.

Если хранилище общедоступно, HTTPS является рекомендуемой схемой для совместного использования Git URLs с пользователями, так как вы можете скопировать и вставить URL непосредственно с веб-страницы службы хостинга хранилища Git.

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

Чтобы обойти эти проблемы проверки подлинности, можно:

• Используйте Помощник учетных данных Git для аутентификации заранее. Дополнительные сведения см. Использование приватных репозиториев с HTTPS-адресами Git.
• Используйте протокол SSH вместо. Если вы создаете и настраиваете пару ключей SSH с помощью службы хостинга хранилища Git, Package Manager может беспрепятственно аутентифицировать запрос от вашего имени.

Использование протокола SSH

Вы можете использовать протокол SSH с полным протоколом URL:

{
  "dependencies": {
    "com.mycompany.mypackage": "ssh://git@mycompany.github.com/gitproject/com.mycompany.mypackage.git"
  }
}

Если ваш сервер Git не поддерживает расширение .git, вы можете добавить специальный префикс git+ с расширением или без него:

{
  "dependencies": {
    "com.mycompany.mypackage1": "git+ssh://git@github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git+ssh://git@github.example.com/myuser/myrepository2"
  }
}

Примечание: В качестве альтернативы можно использовать протокол GIT вместо префикса git+. Дополнительные сведения см. в Использование протокола GIT.

Вы также можете использовать SCP-подобную аббревиатуру, которую Package Manager всегда распознает как зависимость Git:

{
  "dependencies": {
    "com.mycompany.mypackage": "git@mycompany.github.com:gitproject/com.mycompany.mypackage.git"
  }
}

Использование PuTTY на Windows

Git использует ключи в расположении по умолчанию, когда вы используете SSH для аутентификации. Однако, если вы используете PuTTY в качестве клиента SSH на Windows, вам нужно настроить переменные среды GIT_SSH так, чтобы они указывали на plink.exe.

Аутентификация с SSH

Если вы хотите использовать протокол SSH, вам необходимо настроить ключи SSH вне Unity. Дополнительные сведения о настройке аутентификации для конкретного узла см. на страницах справки по Bitbucket, GitLabи GitHub.

Примечание: Если вы зашифровали ваш ключ SSH паролем, Package Manager не может получить пакет, потому что он не предоставляет способ ввода пароля в терминал или командную строку. В этом случае Редактор сообщает вам, что аутентификация не удалась. Информацию об использовании агента аутентификации см. в Использование защищённых парольной фразой SSH-ключей с SSH-адресами Git. Для получения дополнительной информации об использовании ssh-агент для аутентификации, см. Решения для SSH.

Использование протокола FILE

Package Manager не признает Git URLs с префиксом file: в качестве зависимостей Git, если они не правильно отформатированы. Это означает, что вы должны использовать либо протокол git+file:, либо суффикс .git с протоколом file::

{
  "dependencies": {
    "com.mycompany.mypackage1": "git+file://github.example.com/myuser/myrepository1",
    "com.mycompany.mypackage2": "git+file:///github.example.com/myuser/myrepository2",
    "com.mycompany.mypackage3": "file:///github.example.com/myuser/myrepository3.git"
  }
}

Примечание: В качестве альтернативы можно использовать протокол GIT вместо префикса git+. Дополнительные сведения см. в Использование протокола GIT.

Package Manager интерпретирует любой другой синтаксис как локальный путь вместо этого.

Использование протокола GIT

Package Manager распознает протокол git:, с суффиксом пути .git или без него:

{
  "dependencies": {
    "com.mycompany.mypackage1": "git://github.example.com/myuser/myrepository1.git",
    "com.mycompany.mypackage2": "git://github.example.com/myuser/myrepository2"
  }
}

Протокол GIT не нуждается в префиксе git+ и не поддерживает его.

Расширенный синтаксис

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

Вы можете использовать расширенный синтаксис с любым протоколом Git, поддерживаемым Unity.

Указание ревизии Git

Чтобы объявить конкретную ревизию, которую вы хотите, чтобы клонировал Package Manager, добавьте ревизию, префиксированную цифровым знаком (#) в конце URL:

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository1.git#revision",
    "com.mycompany.mypackage2": "git+https://github.example.com/myuser/myrepository2#revision"
  }
}

Ревизия может быть любой меткой, ветвью или хэшем фиксации. Вы должны предоставить полный хэш фиксации. Unity не поддерживает сокращённые хэши SHA–1. В этой таблице показаны примеры указания ревизий:

Синтаксис	URL пример
Последнее ответвление по умолчанию	"https://github.example.com/myuser/myrepository.git"
Конкретная отрасль	"https://github.example.com/myuser/myrepository.git#my-branch"
Специфический тег	"https://github.example.com/myuser/myrepository.git#tag-pointing-to-package-version"
Хеш фиксации	"https://github.example.com/myuser/myrepository.git#9e72f9d5a6a3dadc38d813d8399e1b0e86781a49"

Указание пакета в подпапке хранилища

Если вы указываете хранилище, используя синтаксис Git URL, Package Manager предполагает, что пакет должен находиться в корне хранилища. Однако некоторые пакеты не находятся на корневом уровне своего хранилища, а некоторые хранилища содержат более одного пакета.

Вы можете использовать параметр запроса path в Git URL, чтобы сообщить Package Manager, где найти пакет. Путь, который вы указываете, должен быть относительным к корню хранилища, а подпапка, которую вы указываете, должна содержать манифест пакета (файлpackage.json).

Чтобы указать подпапку хранилища для зависимости Git, используйте параметр запроса path:

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/subfolder"
  }
}

В этом случае Package Manager регистрирует пакет, расположенный в указанной подпапке хранилища, и игнорирует остальную часть хранилища.

Иногда хранилище содержит несколько связанных пакетов. Если вы хотите добавить несколько пакетов из одного хранилища, вы должны добавить две отдельные записи в манифест проекта:

{
  "dependencies": {
    "com.mycompany.mypackage1": "https://github.example.com/myuser/myrepository.git?path=/subfolder1",
    "com.mycompany.mypackage3": "https://github.example.com/myuser/myrepository.git?path=/subfolder2/subfolder3"
  }
}

Примечание: Если вы указываете одно и то же хранилище несколько раз, Package Manager клонирует одно и то же хранилище несколько раз, что приводит к снижению производительности и дополнительному использованию сети.

Указание ревизий и путей одновременно

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

{
  "dependencies": {
    "com.mycompany.mypackage": "https://github.example.com/myuser/myrepository.git?path=/example/folder#v1.2.3"
  }
}

Заблокированные зависимости Git

Один из ключевых принципов Package Manager Если вы делитесь своим проектом с другими пользователями, то Package Manager должен устанавливать один и тот же набор зависимостей и версий пакетов, включая пакеты, которые он получает из Git. Для этого Package Manager tracks фиксирует хэши зависимостей Git с помощью блокировка файла.

Когда вы добавляете зависимость Git с набором ревизий к ответвлению или метке, Package Manager получает соответствующий хэш фиксации для хранения в файле блокировки. Со временем ответвления и метки могут указывать на различные фиксации в хранилище Git. Например, в ответвлении могут быть добавлены новые фиксации.

Чтобы обновить пакет в другую фиксацию, на которую указывает ответвление или метка, используйте Установка пакета из git URL кнопку и введите Git URL. Вы можете использовать тот же Git URL, поскольку Package Manager игнорирует хэш заблокированной фиксации при подаче нового запроса. Однако вы также можете указать новый номер ревизии, метку или ответвление в качестве пересмотр вместо этого.

В качестве альтернативы вы можете создать скрипт с методом Client.Add C# API с этим Git URL.

Поддержка Git LFS

Package Manager поддерживает зависимости Git от хранилищ, которые используют Git Large File Storage (LFS). Однако, поскольку Unity использует мелкие клоны, файлы, отслеживаемые LFS, не всегда извлекаются правильно. Иногда пакет может импортировать файлы указателей вместо фактического содержимого файла. Для более подробной информации см. Ошибки Git LFS.

Поскольку Git LFS разработан для работы с минимальными настройками, он поддерживает как аутентификацию HTTPS, так и SSH:

• Сведения об аутентификации HTTPS см. в разделе Использование протокола HTTP/HTTPS.
• Информацию об аутентификации SSH см. в Использование протокола SSH.

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

Авторы пакетов могут помочь клиенту Git LFS найти Сервер LFS, предоставив ему URL в файле конфигурации .lfsconfig в хранилище. Это можно сделать двумя способами:

# Option 1: global setting
[lfs]
  url = ssh://git@HOSTNAME/path/to/repo.git

# Option 2: per-remote setting
[remote "origin"]
  lfsurl = ssh://git@HOSTNAME/path/to/repo.git

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

Кэш Git LFS

Начиная с Unity 2021.2, вы можете по желанию включить кэш Git LFS для Package Manager для использования при получении Git-зависимостей. Это позволяет избежать необходимости загружать один и тот же файл каждый раз, когда вы получаете другую ревизию хранилища.

Кэш Git LFS для Package Manager отличается от кэша Git LFS в папке .git/lfs вашего хранилища Git. Package Manager не может использовать кэш Git по умолчанию, потому что он не сохраняет клонированные хранилища после копирования пакетов в кэш проекта.

Чтобы включить кэш Git LFS для Package Manager, выберите один из следующих вариантов:

• Включение Git LFS кэш и использовать git-lfs подпапку под по умолчанию глобальный кэш корень в качестве его местоположения, установить UPM_ENABLE_GIT_LFS_CACHE переменная окружающей среды с любым (непустым) значением.
• Чтобы включить кэш Git LFS и использовать для него собственное расположение, установите в переменной среды UPM_GIT_LFS_CACHE_PATH свой собственный путь. Когда вы устанавливаете расположение, опция кэш Git LFS автоматически включается.

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

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

• Использование различных ревизий Git в зависимостях в нескольких проектах
• Частое обновление пакета до ревизий, содержащих различные измененные файлы LFS

Дополнительные ресурсы

• Использование приватных репозиториев с HTTPS-адресами Git
• Использование защищённых парольной фразой SSH-ключей с SSH-адресами Git
• Хранение больших файлов Git (LFS)
• Git на сервере — протоколы
• Установка из Git URL