gitcredentials

gitcredentials — предоставление Git имён пользователей и паролей

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

Если средства-помощники для учётных данных не заданы, Git будет использовать следующие способы запроса имён пользователей и паролей:

Постоянно вводить одни и те же учётные данные может быть утомительно. Git предлагает два способа уменьшить это неудобство:

Первый способ прост и подходит, если у вас нет защищённого хранилища для пароля. Обычно его настраивают, добавив в конфигурацию следующее:

[credential "https://example.com"]
        username = me

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

Чтобы использовать средство-помощник, сначала необходимо выбрать его (список приведён ниже).

У вас также могут быть установлены сторонние средства-помощники; найдите credential-* в выводе команды git help -a и ознакомьтесь с документацией конкретных средств-помощников. Выбрав средство-помощник, укажите Git использовать его, добавив его имя в переменную credential.helper.

Git связывает каждую пару учётных данных с контекстом, определяемым URL-адресом. Этот контекст используется для поиска конфигурации, относящейся к нему, и передаётся средствам-помощникам, которые могут использовать его как индекс в защищённом хранилище.

Например, представим, что мы обращаемся к https://example.com/foo.git. При поиске в файле конфигурации подходящего раздела Git считает контекст соответствующим шаблону, если контекст является более конкретным подмножеством шаблона в файле конфигурации. Например, если в файле конфигурации указано следующее:

[credential "https://example.com"]
        username = foo

совпадение будет найдено: протоколы и хосты совпадают. Однако этот контекст не будет соответствовать следующему:

[credential "https://kernel.org"]
        username = foo

поскольку имена хостов различаются. Не будет соответствия и для foo.example.com: Git сравнивает имена хостов точно, не учитывая, принадлежат ли два хоста одному домену. Аналогично, запись конфигурации для http://example.com не подойдёт: Git сравнивает протоколы точно. Однако в имени домена можно использовать подстановочные символы и другие способы сопоставления шаблонов, как и в параметрах http.<URL>.*.

Если URL-адрес «шаблона» содержит компонент пути, путь контекста должен начинаться с этого пути: контекст https://example.com/bar будет соответствовать записи конфигурации для https://example.com/bar/baz.git, но не записи для https://example.com/other/repo.git или https://example.com/barry/repo.git (даже несмотря на то, что эта строка является префиксом).

Параметры контекста учётных данных можно настроить либо в credential.* (применяется ко всем учётным данным), либо в credential.<URL>.*, где <URL> соответствует контексту, как описано выше.

В обоих случаях доступны следующие параметры:

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

Средства-помощники для учётных данных — это программы, которые Git запускает для получения или сохранения учётных данных в долговременном хранилище (под «долговременным» понимается хранение дольше, чем длится один процесс Git; например, учётные данные могут храниться в памяти несколько минут или бессрочно на диске).

Каждое средство-помощник задаётся одной строкой в переменной конфигурации credential.helper (а также в других переменных, см. git-config[1]). Git преобразует эту строку в команду, используя следующие правила:

Затем к полученной команде добавляется аргумент «операция» (подробности см. ниже), и она выполняется оболочкой.

Примеры таких спецификаций:

# run "git credential-foo"
[credential]
        helper = foo

# same as above, but pass an argument to the helper
[credential]
        helper = "foo --bar=baz"

# the arguments are parsed by the shell, so use shell
# quoting if necessary
[credential]
        helper = "foo --bar='whitespace arg'"

# store helper (discouraged) with custom location for the db file;
# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,
# to allow the shell to expand tilde to the home directory.
[credential]
        helper = "store --file ~/.git-secret.txt"

# you can also use an absolute path, which will not use the git wrapper
[credential]
        helper = "/path/to/my/helper --with-arguments"

# or you can specify your own shell snippet
[credential "https://example.com"]
        username = your_user
        helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f"

Как правило, пользователям проще всего указывать средство-помощник согласно правилу (3). Разработчикам средств-помощников следует упростить их использование: назвать программу «git-credential-$NAME» и при установке поместить её в $PATH или $GIT_EXEC_PATH. Тогда пользователь сможет включить её с помощью команды git config credential.helper $NAME.

При запуске к командной строке средства-помощника добавляется один аргумент «операция», который может принимать одно из следующих значений:

Подробные сведения об учётных данных передаются через стандартный входной поток средства-помощника. Точный формат совпадает с форматом ввода и вывода низкоуровневой команды git credential (подробная спецификация приведена в разделе INPUT/OUTPUT FORMAT руководства git-credential[1]).

При операции get средство-помощник должно выводить список атрибутов в стандартный выходной поток в том же формате (общие атрибуты описаны в git-credential[1]). Средство-помощник может вывести только часть атрибутов или не вывести ничего, если ему нечего предложить. Все предоставленные атрибуты заменяют те, о которых подсистеме учётных данных Git уже известно. Неизвестные атрибуты отбрасываются без уведомления.

Хотя можно переопределять любые атрибуты, правильно работающим средствам-помощникам следует делать это только для имени пользователя и пароля.

Если средство-помощник выводит атрибут quit со значением true или 1, остальные средства-помощники вызываться не будут, и запрос пользователю выводиться не будет (если учётные данные не предоставлены, операция завершится ошибкой).

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

При операциях store или erase вывод средства-помощника игнорируется.

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

Если средство-помощник не поддерживает запрошенную операцию (например, это хранилище только для чтения или генератор), ему следует молча проигнорировать запрос.

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