Rerun 项目 Git 钩子完整指南从安装 pre-push 到 fast-lint 自动检查【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文以 Rerun 仓库的 hooks/README.md 为骨架系统讲解该项目官方 Git 钩子githooks的设计思路、两种安装方式、以及pre-push钩子从 Git 触发到pixi run fast-lint的完整执行链路。读完本文你将掌握如何在本地开发环境中快速启用 Rerun 的提交前检查理解钩子脚本的薄壳转发shim架构并能够按需跳过或定制 fast-lint 的检查项在推送代码前拦截低质量问题、节省 CI 时间。一、hooks 目录是什么官方钩子与薄壳设计Rerun 仓库在根目录下维护了一个名为hooks的目录其中存放的是官方 githooks见 hooks/README.md。与直接在每个钩子文件里写满逻辑的做法不同这里的每个钩子都被设计为转发器shim它只负责定位仓库根目录然后通过exec把控制权转交给scripts目录中对应的托管脚本pre-push→ scripts/pre-push.sh当前仓库实际只提供了一个pre-push钩子它对应的是 scripts/pre-push.sh 这个管理脚本。这种钩子文件 薄壳、真实逻辑 脚本的结构有以下好处钩子本身保持极短便于复制到.git/hooks目录后与仓库后续更新解耦真实逻辑放在版本控制下的scripts目录中升级检查规则时只需更新脚本无需重新安装钩子脚本可以借助仓库内的 Pixi 环境来固定依赖与工具版本。这一设计在 CONTRIBUTING.md 的 Hooks 一节中也被推荐给所有贡献者在推送之前始终运行pixi run fast-lint它会在重复运行时于数秒内完成能在浪费 CI 时间之前拦截琐碎问题。二、安装钩子两种方式任选根据 hooks/README.md 的 Installation 一节安装方式有两种效果等价。方式一复制到本地.git/hooks目录这是 Git 的传统做法把钩子文件复制到当前检出目录的.git/hooks中并赋予可执行权限cp hooks/pre-push .git/hooks/pre-push chmod x .git/hooks/pre-push需要注意的是.git目录本身不受版本控制这种方式意味着钩子只会作用于当前这一份本地检出如果你重新 clone 仓库需要重新执行上述命令。方式二将hooks目录配置为 Git 钩子目录如果你更希望让 Git 直接使用仓库中的这个目录作为钩子来源可以配置core.hooksPathgit config core.hooksPath hooks设置之后Git 会从仓库根目录下的hooks/目录读取钩子脚本。这种方式下钩子文件始终与仓库源码保持同步——仓库更新hooks/pre-push后本地无需任何手动操作即可生效。如果你将来想回到默认行为可以执行git config --unset core.hooksPath取消该配置。两种方式都要求仓库根目录下存在scripts/pre-push.sh钩子才能正常工作若脚本缺失钩子会打印提示并静默跳过见下文 shim 分析不会阻断推送。三、pre-push 执行链路从 Git 事件到 fast-lint理解整条链路需要依次阅读三个文件钩子薄壳 hooks/pre-push、托管脚本 scripts/pre-push.sh、以及最终的 lint 入口fast-lint任务定义于 pixi.toml。3.1 薄壳hooks/pre-pushhooks/pre-push 是一个极简的 POSIX shell 脚本核心逻辑只有几步repo_root$(git rev-parse --show-toplevel) pre_push_hook$repo_root/scripts/pre-push.sh if [ -f $pre_push_hook ]; then exec $pre_push_hook # --skip lint-codegen else echo The pre-push hook appears to be missing from: $pre_push_hook -- Skipping. exit 0 fi通过git rev-parse --show-toplevel定位仓库根目录从而保证无论从哪个子目录执行 push都能找到托管脚本若scripts/pre-push.sh存在则用exec直接替换当前进程执行它若缺失则打印提示并以退出码0跳过不会阻塞推送第 8 行注释掉的--skip lint-codegen是一个预留示例你可以通过给scripts/pre-push.sh追加参数的方式跳过特定检查参数会一路透传给fast-lint。3.2 托管脚本scripts/pre-push.shscripts/pre-push.sh 是真正的决策层包含两层逻辑第一层环境前置检查。脚本要求本机已安装 PixiRerun 的包管理 / 任务运行工具if ! command -v pixi /dev/null 21; then echo The rerun hooks require pixi, which is not installed or not in your PATH. Please run: cargo install pixi. exit 1 fi若pixi不在 PATH 中钩子会以退出码1失败并提示通过cargo install pixi安装。仓库的 pixi.toml 对 Pixi 版本有明确要求requires-pixi 0.71.3建议安装满足该约束的版本。第二层分支匹配决策。Git 的pre-push钩子会从标准输入读取待推送的引用列表每行格式为local_ref local_sha remote_ref remote_sha。脚本逐行读取并对每个本地引用做处理while read -r local_ref _local_sha _remote_ref _remote_sha; do branch_name$(echo $local_ref | sed s/^refs\/heads\///) active_branch$(git symbolic-ref --short HEAD) if [ $branch_name $active_branch ]; then exec pixi run fast-lint $ else echo Skipping fast-lint because the pushed branch ($branch_name) does not match the active branch ($active_branch). fi done关键行为说明只有当被推送的分支名与当前检出的活动分支一致时才执行pixi run fast-lint $$会把用户在 push 命令行之后附加的参数例如--skip原样透传给 fast-lint若推送的是非活动分支例如git push origin other-branch而当前在main脚本会打印跳过信息——这是为了避免在开发分支上重复做与当前工作区无关的检查使用exec意味着一旦匹配后续分支不会再被处理检查结果直接决定 push 的成败非零退出码会终止推送。3.3 fast-lint 任务定义在 pixi.toml 中fast-lint被定义为fast-lint python scripts/fast_lint.pyPixi 在执行任务前会确保所有依赖已安装仓库在 pixi.toml 顶部注释中对此有明确说明因此钩子运行时无需手动准备 Python 环境。四、fast-lint 到底检查什么scripts/fast_lint.py 的模块文档将其定位为对相对main分支发生变更的文件运行常用 linters。它的核心价值在于只检查变更文件因此重复运行时只需数秒适合放在 pre-push 这种高频路径上。4.1 变更文件检测changed_files()函数见 scripts/fast_lint.py使用 GitPython 打开当前仓库计算当前分支与main的合并基点merge_base再通过repo.index.diff(common_ancestor)得到相对main变更且仍然存在的文件列表。也就是说默认只 lint 你本次分支改动涉及的文件未修改的存量代码不会被重复检查。4.2 内置的检查任务清单main()中通过LintJob定义了九个检查任务见 scripts/fast_lint.py每个任务都可以声明接受的文件扩展名、无变更时的兜底命令、以及是否支持无变更过滤任务命令适用文件说明lint-codegen不接受文件参数校验代码生成结果是否与当前源码一致对应 pixi.toml 中的cargo run --package re_types_builder -- --checklint-rerun全部运行自定义 lint 脚本 scripts/lint.py对 Rust、文档等执行项目专属规则检查支持NOLINT/NOLINT_START/NOLINT_END注释忽略机制lint-rs-files.rs对变更的 Rust 文件运行rustfmt --edition 2024 --check无变更文件时回退到全量lint-rs-all即cargo fmt --check同时用正则^crates/store/re_sdk_types(_core)?/排除生成代码目录py-fmt-check.py对变更的 Python 文件运行uv run ruff check . uv run ruff format --check .无变更时检查整个PY_FOLDERS即仓库根目录.py-lint.py运行 mypy 类型检查accepts_filesFalse即始终对全项目执行避免按文件运行 mypy 结果不一致toml-fmt-check.toml对变更的 TOML 文件运行taplo fmt --check --difflint-typos --force-exclude全部运行typos拼写检查check-large-files全部调用 scripts/ci/check_large_files.py 检查是否存在过大的仓库文件nb-strip-check不接受文件参数校验 notebook 输出是否已被清理accepts_filesFalse各任务通过concurrent.futures.ThreadPoolExecutor并行执行默认 8 个线程任何一个任务失败都会导致最终退出码非零从而中断 git push。4.3 fast-lint 的命令行参数scripts/fast_lint.py 提供了以下参数供手动运行或钩子透传使用--log-level日志级别默认INFO可选DEBUG/INFO/WARNING/ERROR/CRITICAL--num-threads并行线程数默认8--skip逗号分隔的待跳过任务列表默认值来自环境变量RERUN_LINT_SKIP如果传入了清单中不存在的任务名脚本会报错并退出见 scripts/fast_lint.py--no-change-filter不做变更过滤对所有文件全量运行位置参数files指定文件路径空则递归检查全部文件。手动运行示例无需等待 push 触发pixi run fast-lint # 仅检查相对 main 的变更文件 pixi run fast-lint -- --skip lint-codegen,nb-strip-check # 跳过指定任务 pixi run fast-lint -- --no-change-filter # 全量检查注意pixi run会把--之后的参数透传给任务脚本因此上述写法在命令行上是安全的。五、使用建议与常见问题5.1 与 CONTRIBUTING 中的推荐流程结合CONTRIBUTING.md 将推送前运行 fast-lint列为贡献者的常规动作并推荐通过安装 pre-push 钩子来自动化这一流程。由于钩子内部已经包含分支匹配逻辑日常在活动分支上git push时它就会自动生效无需额外记忆。5.2 常见问题排查推送被钩子拦截如何定位是哪项检查失败查看终端输出的FAIL: command日志见 scripts/fast_lint.py它会打印失败命令、完整命令行与被检查文件。修复问题后重新 push 即可。临时想跳过某项检查在 push 命令后透传--skip参数git push origin main --skip lint-codegen参数会经 scripts/pre-push.sh 的$透传给 fast-lint也可以设置环境变量RERUN_LINT_SKIP。注意跳过检查只是绕过本地门禁CI 上仍可能执行全量检查。没有安装 Pixi 会怎样钩子会以退出码1失败并提示先执行cargo install pixi避免在缺失依赖的情况下给出误导性的通过结论。不想使用钩子了若采用core.hooksPath方式执行git config --unset core.hooksPath恢复默认若采用复制方式把.git/hooks/pre-push移除即可。5.3 进阶钩子只做转发逻辑都在 scripts如果你想了解或扩展检查规则重点应关注 scripts/fast_lint.py任务编排与 scripts/lint.py自定义规则以及 pixi.toml 的[tasks]一节中lint-*/*-fmt-check系列任务的具体命令定义。钩子目录本身保持最小化这正是该项目钩子体系的可维护性所在仓库升级检查规则后重新拉取代码即自动获得新逻辑无需重装钩子。小结Rerun 的 git 钩子体系围绕薄壳转发 托管脚本 Pixi 任务三层结构展开hooks/README.md给出了安装入口复制到.git/hooks或配置core.hooksPathhooks/pre-push负责定位并转发scripts/pre-push.sh负责环境检查与分支匹配最终由pixi run fast-lint驱动 scripts/fast_lint.py 并行执行九类检查任务。这套设计让贡献者只需一行配置即可在推送前自动获得轻量、快速、可跳过的质量门禁是理解并参与 Rerun 开发协作流程的实用起点。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rerun 项目 Git 钩子完整指南：从安装 pre-push 到 fast-lint 自动检查
Rerun 项目 Git 钩子完整指南从安装 pre-push 到 fast-lint 自动检查【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文以 Rerun 仓库的 hooks/README.md 为骨架系统讲解该项目官方 Git 钩子githooks的设计思路、两种安装方式、以及pre-push钩子从 Git 触发到pixi run fast-lint的完整执行链路。读完本文你将掌握如何在本地开发环境中快速启用 Rerun 的提交前检查理解钩子脚本的薄壳转发shim架构并能够按需跳过或定制 fast-lint 的检查项在推送代码前拦截低质量问题、节省 CI 时间。一、hooks 目录是什么官方钩子与薄壳设计Rerun 仓库在根目录下维护了一个名为hooks的目录其中存放的是官方 githooks见 hooks/README.md。与直接在每个钩子文件里写满逻辑的做法不同这里的每个钩子都被设计为转发器shim它只负责定位仓库根目录然后通过exec把控制权转交给scripts目录中对应的托管脚本pre-push→ scripts/pre-push.sh当前仓库实际只提供了一个pre-push钩子它对应的是 scripts/pre-push.sh 这个管理脚本。这种钩子文件 薄壳、真实逻辑 脚本的结构有以下好处钩子本身保持极短便于复制到.git/hooks目录后与仓库后续更新解耦真实逻辑放在版本控制下的scripts目录中升级检查规则时只需更新脚本无需重新安装钩子脚本可以借助仓库内的 Pixi 环境来固定依赖与工具版本。这一设计在 CONTRIBUTING.md 的 Hooks 一节中也被推荐给所有贡献者在推送之前始终运行pixi run fast-lint它会在重复运行时于数秒内完成能在浪费 CI 时间之前拦截琐碎问题。二、安装钩子两种方式任选根据 hooks/README.md 的 Installation 一节安装方式有两种效果等价。方式一复制到本地.git/hooks目录这是 Git 的传统做法把钩子文件复制到当前检出目录的.git/hooks中并赋予可执行权限cp hooks/pre-push .git/hooks/pre-push chmod x .git/hooks/pre-push需要注意的是.git目录本身不受版本控制这种方式意味着钩子只会作用于当前这一份本地检出如果你重新 clone 仓库需要重新执行上述命令。方式二将hooks目录配置为 Git 钩子目录如果你更希望让 Git 直接使用仓库中的这个目录作为钩子来源可以配置core.hooksPathgit config core.hooksPath hooks设置之后Git 会从仓库根目录下的hooks/目录读取钩子脚本。这种方式下钩子文件始终与仓库源码保持同步——仓库更新hooks/pre-push后本地无需任何手动操作即可生效。如果你将来想回到默认行为可以执行git config --unset core.hooksPath取消该配置。两种方式都要求仓库根目录下存在scripts/pre-push.sh钩子才能正常工作若脚本缺失钩子会打印提示并静默跳过见下文 shim 分析不会阻断推送。三、pre-push 执行链路从 Git 事件到 fast-lint理解整条链路需要依次阅读三个文件钩子薄壳 hooks/pre-push、托管脚本 scripts/pre-push.sh、以及最终的 lint 入口fast-lint任务定义于 pixi.toml。3.1 薄壳hooks/pre-pushhooks/pre-push 是一个极简的 POSIX shell 脚本核心逻辑只有几步repo_root$(git rev-parse --show-toplevel) pre_push_hook$repo_root/scripts/pre-push.sh if [ -f $pre_push_hook ]; then exec $pre_push_hook # --skip lint-codegen else echo The pre-push hook appears to be missing from: $pre_push_hook -- Skipping. exit 0 fi通过git rev-parse --show-toplevel定位仓库根目录从而保证无论从哪个子目录执行 push都能找到托管脚本若scripts/pre-push.sh存在则用exec直接替换当前进程执行它若缺失则打印提示并以退出码0跳过不会阻塞推送第 8 行注释掉的--skip lint-codegen是一个预留示例你可以通过给scripts/pre-push.sh追加参数的方式跳过特定检查参数会一路透传给fast-lint。3.2 托管脚本scripts/pre-push.shscripts/pre-push.sh 是真正的决策层包含两层逻辑第一层环境前置检查。脚本要求本机已安装 PixiRerun 的包管理 / 任务运行工具if ! command -v pixi /dev/null 21; then echo The rerun hooks require pixi, which is not installed or not in your PATH. Please run: cargo install pixi. exit 1 fi若pixi不在 PATH 中钩子会以退出码1失败并提示通过cargo install pixi安装。仓库的 pixi.toml 对 Pixi 版本有明确要求requires-pixi 0.71.3建议安装满足该约束的版本。第二层分支匹配决策。Git 的pre-push钩子会从标准输入读取待推送的引用列表每行格式为local_ref local_sha remote_ref remote_sha。脚本逐行读取并对每个本地引用做处理while read -r local_ref _local_sha _remote_ref _remote_sha; do branch_name$(echo $local_ref | sed s/^refs\/heads\///) active_branch$(git symbolic-ref --short HEAD) if [ $branch_name $active_branch ]; then exec pixi run fast-lint $ else echo Skipping fast-lint because the pushed branch ($branch_name) does not match the active branch ($active_branch). fi done关键行为说明只有当被推送的分支名与当前检出的活动分支一致时才执行pixi run fast-lint $$会把用户在 push 命令行之后附加的参数例如--skip原样透传给 fast-lint若推送的是非活动分支例如git push origin other-branch而当前在main脚本会打印跳过信息——这是为了避免在开发分支上重复做与当前工作区无关的检查使用exec意味着一旦匹配后续分支不会再被处理检查结果直接决定 push 的成败非零退出码会终止推送。3.3 fast-lint 任务定义在 pixi.toml 中fast-lint被定义为fast-lint python scripts/fast_lint.pyPixi 在执行任务前会确保所有依赖已安装仓库在 pixi.toml 顶部注释中对此有明确说明因此钩子运行时无需手动准备 Python 环境。四、fast-lint 到底检查什么scripts/fast_lint.py 的模块文档将其定位为对相对main分支发生变更的文件运行常用 linters。它的核心价值在于只检查变更文件因此重复运行时只需数秒适合放在 pre-push 这种高频路径上。4.1 变更文件检测changed_files()函数见 scripts/fast_lint.py使用 GitPython 打开当前仓库计算当前分支与main的合并基点merge_base再通过repo.index.diff(common_ancestor)得到相对main变更且仍然存在的文件列表。也就是说默认只 lint 你本次分支改动涉及的文件未修改的存量代码不会被重复检查。4.2 内置的检查任务清单main()中通过LintJob定义了九个检查任务见 scripts/fast_lint.py每个任务都可以声明接受的文件扩展名、无变更时的兜底命令、以及是否支持无变更过滤任务命令适用文件说明lint-codegen不接受文件参数校验代码生成结果是否与当前源码一致对应 pixi.toml 中的cargo run --package re_types_builder -- --checklint-rerun全部运行自定义 lint 脚本 scripts/lint.py对 Rust、文档等执行项目专属规则检查支持NOLINT/NOLINT_START/NOLINT_END注释忽略机制lint-rs-files.rs对变更的 Rust 文件运行rustfmt --edition 2024 --check无变更文件时回退到全量lint-rs-all即cargo fmt --check同时用正则^crates/store/re_sdk_types(_core)?/排除生成代码目录py-fmt-check.py对变更的 Python 文件运行uv run ruff check . uv run ruff format --check .无变更时检查整个PY_FOLDERS即仓库根目录.py-lint.py运行 mypy 类型检查accepts_filesFalse即始终对全项目执行避免按文件运行 mypy 结果不一致toml-fmt-check.toml对变更的 TOML 文件运行taplo fmt --check --difflint-typos --force-exclude全部运行typos拼写检查check-large-files全部调用 scripts/ci/check_large_files.py 检查是否存在过大的仓库文件nb-strip-check不接受文件参数校验 notebook 输出是否已被清理accepts_filesFalse各任务通过concurrent.futures.ThreadPoolExecutor并行执行默认 8 个线程任何一个任务失败都会导致最终退出码非零从而中断 git push。4.3 fast-lint 的命令行参数scripts/fast_lint.py 提供了以下参数供手动运行或钩子透传使用--log-level日志级别默认INFO可选DEBUG/INFO/WARNING/ERROR/CRITICAL--num-threads并行线程数默认8--skip逗号分隔的待跳过任务列表默认值来自环境变量RERUN_LINT_SKIP如果传入了清单中不存在的任务名脚本会报错并退出见 scripts/fast_lint.py--no-change-filter不做变更过滤对所有文件全量运行位置参数files指定文件路径空则递归检查全部文件。手动运行示例无需等待 push 触发pixi run fast-lint # 仅检查相对 main 的变更文件 pixi run fast-lint -- --skip lint-codegen,nb-strip-check # 跳过指定任务 pixi run fast-lint -- --no-change-filter # 全量检查注意pixi run会把--之后的参数透传给任务脚本因此上述写法在命令行上是安全的。五、使用建议与常见问题5.1 与 CONTRIBUTING 中的推荐流程结合CONTRIBUTING.md 将推送前运行 fast-lint列为贡献者的常规动作并推荐通过安装 pre-push 钩子来自动化这一流程。由于钩子内部已经包含分支匹配逻辑日常在活动分支上git push时它就会自动生效无需额外记忆。5.2 常见问题排查推送被钩子拦截如何定位是哪项检查失败查看终端输出的FAIL: command日志见 scripts/fast_lint.py它会打印失败命令、完整命令行与被检查文件。修复问题后重新 push 即可。临时想跳过某项检查在 push 命令后透传--skip参数git push origin main --skip lint-codegen参数会经 scripts/pre-push.sh 的$透传给 fast-lint也可以设置环境变量RERUN_LINT_SKIP。注意跳过检查只是绕过本地门禁CI 上仍可能执行全量检查。没有安装 Pixi 会怎样钩子会以退出码1失败并提示先执行cargo install pixi避免在缺失依赖的情况下给出误导性的通过结论。不想使用钩子了若采用core.hooksPath方式执行git config --unset core.hooksPath恢复默认若采用复制方式把.git/hooks/pre-push移除即可。5.3 进阶钩子只做转发逻辑都在 scripts如果你想了解或扩展检查规则重点应关注 scripts/fast_lint.py任务编排与 scripts/lint.py自定义规则以及 pixi.toml 的[tasks]一节中lint-*/*-fmt-check系列任务的具体命令定义。钩子目录本身保持最小化这正是该项目钩子体系的可维护性所在仓库升级检查规则后重新拉取代码即自动获得新逻辑无需重装钩子。小结Rerun 的 git 钩子体系围绕薄壳转发 托管脚本 Pixi 任务三层结构展开hooks/README.md给出了安装入口复制到.git/hooks或配置core.hooksPathhooks/pre-push负责定位并转发scripts/pre-push.sh负责环境检查与分支匹配最终由pixi run fast-lint驱动 scripts/fast_lint.py 并行执行九类检查任务。这套设计让贡献者只需一行配置即可在推送前自动获得轻量、快速、可跳过的质量门禁是理解并参与 Rerun 开发协作流程的实用起点。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
