Docker环境下Tox集成pre-commit钩子遇参数错误或测试不执行问题

问题背景 #

所有操作在Docker容器内执行，单独运行Tox功能正常，但将其集成到pre-commit钩子后，无法正确处理待提交的变更文件。

当前pre-commit配置 #

-   repo: local
    hooks:
    -   id: tox-project
        name: tox
        entry: tox
        language: system
        types: [python]
        args: [-c, path_inside_docker/tox.ini, --workdir=path_inside_docker, -e, "fix,pylint,[other_tests]"]

报错信息 #

tox......................................................................Failed
- hook id: tox-project
- exit code: 2

usage: tox [-h] [--colored {yes,no}] [-v | -q] [--exit-and-dump-after seconds] [-c file] 
[--workdir dir] [--root dir] [--runner {virtualenv}] [--version] [--no-provision [REQ_JSON]] 
[--no-recreate-provision] [-r] [-x OVERRIDE]
{run,r,run-parallel,p,depends,de,list,l,devenv,d,config,c,quickstart,q,exec,e,legacy,
le} ... 

tox: error: unrecognized arguments: path/to/file/to/be/commited/main.py hint: if you tried to pass 
    arguments to a command use -- to separate them from tox ones

已尝试的无效方案 #

• 在Tox的args末尾添加--以传递提交文件，修改后配置：

  args: [-c, path_inside_docker/tox.ini, --workdir=path_inside_docker, -e,"fix,pylint,[other_tests]",--]
  

  钩子运行成功，但Tox未生成预期测试结果（单独运行Tox能正常检测出代码错误）。
• 添加pass_filenames: false关闭文件名传递，Tox执行成功但完全不处理提交的文件，无任何有效检测结果。

可行解决办法 #

核心思路 #

pre-commit会把待提交的文件路径传递给钩子，但Tox本身不直接处理这些文件，需要让Tox将这些路径转发给具体的测试工具（如pylint、black等）。

步骤1：修正pre-commit配置 #

保持pass_filenames: true（默认开启），确保args末尾的--正确分隔Tox参数和待传递的文件路径：

-   repo: local
    hooks:
    -   id: tox-project
        name: tox
        entry: tox
        language: system
        types: [python]
        args: [-c, path_inside_docker/tox.ini, --workdir=path_inside_docker, -e, "fix,pylint,[other_tests]", --]

步骤2：修改tox.ini配置 #

在tox.ini中，给每个需要处理指定文件的测试环境添加{posargs}，让工具接收Tox传递过来的文件路径：

[testenv:pylint]
commands = pylint {posargs}
deps = pylint

[testenv:fix]
commands = black {posargs}
deps = black

这样当pre-commit把待提交文件路径传给Tox后，Tox会通过{posargs}把这些路径转发给对应的测试工具，工具就会只处理这些目标文件。

额外注意事项 #

确保Docker容器内的路径映射正确，pre-commit传入的文件路径要和容器内的实际路径一致，避免测试工具找不到文件。

如果路径映射存在问题，可通过自定义脚本中转处理：

1. 创建run-tox-hook.sh脚本：

#!/bin/bash
# 若路径需要转换，在这里处理（比如将宿主机路径转为容器内路径）
FILES="$@"
tox -c path_inside_docker/tox.ini --workdir=path_inside_docker -e fix,pylint,[other_tests] -- $FILES

2. 修改pre-commit配置：

-   repo: local
    hooks:
    -   id: tox-project
        name: tox
        entry: ./run-tox-hook.sh
        language: script
        types: [python]

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