未修改配置却出现Pre-commit安装Flake8失败问题求助

问题描述 #

未修改pre-commit配置文件，但运行时突然失败，初始化Flake8环境时输出如下错误日志：

...
[INFO] Initializing environment for https://gitlab.com/pycqa/flake8.git.
An unexpected error has occurred: CalledProcessError: command: ('/usr/bin/git', 'fetch', 'origin', '--tags')
return code: 128
expected return code: 0
stdout: (none)
stderr:
    fatal: could not read Username for 'https://gitlab.com': No such device or address
...

当前pre-commit配置文件内容：

---
repos:
- repo: https://gitlab.com/pycqa/flake8.git
  rev: 3.9.2
  hooks:
  - id: flake8
    exclude: 'tests|env|docs'

原因分析 #

该错误是由于Git通过HTTPS协议访问GitLab仓库时，无法获取有效的用户名凭据，导致git fetch操作失败。常见触发因素包括：Git凭据缓存失效、系统凭据管理器配置异常、环境中未正确设置GitLab访问凭据。

解决方案 #

1. 改用SSH地址拉取仓库 #

将pre-commit配置中的HTTPS仓库地址替换为SSH格式，前提是已配置好GitLab的SSH密钥并能正常访问仓库：

---
repos:
- repo: git@gitlab.com:pycqa/flake8.git
  rev: 3.9.2
  hooks:
  - id: flake8
    exclude: 'tests|env|docs'

2. 配置Git HTTPS凭据缓存 #

若需继续使用HTTPS地址，可配置Git自动缓存凭据：

• 临时缓存（默认15分钟）：

  git config --global credential.helper cache
  

  如需延长缓存时间（例如1小时）：

  git config --global credential.helper 'cache --timeout=3600'
  

• 永久存储凭据：
  根据操作系统选择对应凭据助手：
  • Linux：

    git config --global credential.helper /usr/share/git-core/contrib/credential/libsecret/git-credential-libsecret
    

  • Windows：

    git config --global credential.helper wincred
    

  • macOS：

    git config --global credential.helper osxkeychain
    

  配置完成后重新运行pre-commit，首次会提示输入GitLab用户名和密码，后续将自动使用缓存凭据。

3. 临时嵌入凭据（不推荐） #

可在HTTPS地址中直接嵌入用户名和密码（存在明文泄露风险，仅临时应急使用）：

---
repos:
- repo: https://<你的GitLab用户名>:<你的GitLab密码>@gitlab.com/pycqa/flake8.git
  rev: 3.9.2
  hooks:
  - id: flake8
    exclude: 'tests|env|docs'

内容的提问来源于stack exchange，提问作者Roald Nefs