简介这是一款面向GitHub开发者与开源贡献者的TypeScript编写的VS Code插件专为灵活管理提交记录而设计帮助用户按需填充GitHub首页的绿色贡献图谱。插件支持自定义过去数年及未来日期范围的commit生成可设定固定或随机commit次数并提供详尽运行日志适用于技术展示、项目初始化、学习实践或趣味性个人主页美化等场景。资源包共49个文件含8个核心TypeScript源码如extension.ts、util/模型逻辑、7个JSON配置文件package.json、commitlint.config.js等、7张功能示意图GIF/ PNG、4份Markdown文档README、CHANGELOG等及Webpack、ESLint、GitHub Actions等配套工程配置整体体积7.32MB结构完整、开箱即用。目前已有381人学习下载读者可直接安装使用快速掌握commit时间控制、多日期批量提交及可视化效果调试等实用技巧。1. autoCommit 不是“刷绿格子”的魔术棒而是 Git 时间线的可控重写工具你刚 clone 下来一个空仓库想让 GitHub 首页那片绿色贡献图contribution graph看起来“活跃”——不是靠熬夜补 commit而是用autoCommit把过去三年、甚至未来半年的每日提交按真实时间戳批量生成、自动推送。它不伪造 author 信息不绕过 Git 签名机制不依赖任何第三方服务或镜像站它只做三件事按日历生成 commit、用本地 Git 环境签名、按需推送到远程 origin。核心约束很硬user.name和user.email必须提前配置否则git commit直接报错username and email must be set before commit所有 commit 都走标准git commit --dateYYYY-MM-DD HH:MM:SS流程时间戳可精确到秒支持跨年、跨月、跳过周末、排除节假日。适合两类人一是刚起步想建立技术存在感的新人避免首页一片空白二是需要长期维护开源项目但时间碎片化的开发者用预设规则“补全”历史贡献密度。它不是替代真实开发的捷径而是把「本该写的文档、本该修的 typo、本该整理的 README」用时间锚点归档的自动化助手——绿格子只是副产品可追溯、可审计、可回滚的 commit 历史才是它的交付物。2. 从零跑通 autoCommit本地环境准备 最小可运行配置2.1 确保 Git 全局身份合法且稳定autoCommit的所有 commit 都依赖本地 Git 配置。若未设置user.name和user.email脚本执行时会在git commit阶段直接中断并抛出经典错误fatal: empty ident name (for ) given或username and email must be set before commit这不是 bug是 Git 的强制校验。必须在终端中执行以下命令注意不要用--local必须用--globalgit config --global user.name Your Real Name git config --global user.email your.emailexample.com提示邮箱必须与 GitHub 账号已验证的邮箱一致否则 commit 不会关联到你的个人主页贡献图。可在 GitHub Settings → Emails 页面确认主邮箱是否勾选了 “Keep my email address private” —— 若启用需使用 GitHub 提供的noreply邮箱格式为idusernameusers.noreply.github.com否则 commit 将显示为 “ghost” 用户。验证是否生效git config --global user.name git config --global user.email输出应为非空字符串。若为空说明配置未落盘需检查 shell 环境变量如GIT_CONFIG_GLOBAL是否被覆盖或权限Windows 下可能需管理员运行终端。2.2 初始化目标仓库并绑定远程 originautoCommit不创建新仓库它只向已存在且已关联远程 origin 的本地仓库提交。操作顺序不可颠倒创建空目录并初始化 Gitmkdir my-project cd my-project git init创建初始文件哪怕只是一行 READMEecho # My Project README.md git add README.md git commit -m initial commit添加远程 origin务必用 HTTPS 协议SSH 在批量提交场景易触发密钥交互阻塞git remote add origin https://github.com/your-username/your-repo.git关键一步先手动 push 一次确保远程仓库存在且权限正常git push -u origin main逻辑说明autoCommit脚本内部调用git push时若远程分支不存在会因non-fast-forward拒绝推送。手动首次 push 建立origin/main分支后续脚本才能以--force-with-lease安全覆盖见 3.2 节。若跳过此步脚本会卡在 push 环节报错failed to push some refs to https://...。2.3 下载并运行最小配置版 autoCommit当前主流实现是基于 Node.js 的轻量 CLI 工具GitHub 上 star 数最高的版本由 shihabal3amri 维护仓库名diplay注意拼写非display。安装方式如下# 全局安装推荐避免每次 cd 进项目都重装 npm install -g auto-commit-cli # 或局部安装适合多项目隔离 npm init -y npm install --save-dev auto-commit-cli参数说明-g表示全局安装命令auto-commit可在任意目录执行若用局部安装后续需通过npx auto-commit调用避免路径问题不建议用yarn global add部分版本存在 bin link 权限问题。验证安装auto-commit --version输出应为v1.x.x截至 2024 年主流为 v1.4.0。若报command not found检查npm bin -g输出路径是否已加入$PATHLinux/macOS或系统环境变量Windows。3. 配置灵活时间范围、频率、内容模板的三重控制3.1 定义时间窗口从“过去三年”到“未来半年”的精确锚定autoCommit的核心能力是按日历生成 commit而非随机打点。时间范围由两个参数控制--start和--end格式严格为YYYY-MM-DDauto-commit \ --start 2021-01-01 \ --end 2024-12-31 \ --branch main逻辑说明--start是第一个 commit 的日期含--end是最后一个 commit 的日期含若--start早于当前日期脚本会生成历史 commitGit 允许--date设置过去时间若--end晚于当前日期脚本会生成未来 commitGitHub 接受未来时间戳但贡献图仅在当日 UTC 时间后显示时间跨度无硬性上限但单次运行超过 1000 天建议分批执行避免内存溢出或 GitHub API 限流。常见组合场景参数示例说明补全去年空缺--start 2023-01-01 --end 2023-12-31生成 365 个 commit每天 1 次预埋未来半年--start 2025-01-01 --end 2025-06-30提前占位实际开发时再 amend 替换内容跨年连续填充--start 2022-07-01 --end 2024-06-30覆盖 2 年整共 730 天注意--branch参数必须与远程分支名一致默认main旧仓库可能是master否则 push 会失败。3.2 控制提交频率跳过周末、排除节假日、自定义间隔默认每天生成 1 个 commit但可通过--skip-weekends和--holidays精细过滤auto-commit \ --start 2024-01-01 \ --end 2024-12-31 \ --skip-weekends \ --holidays 2024-01-01,2024-02-10,2024-12-25 \ --branch main参数说明--skip-weekends自动跳过周六、周日按 ISO 8601周一1周日7--holidays逗号分隔的日期字符串格式YYYY-MM-DD支持最多 50 个若需动态加载节假日如中国法定假期需自行扩展脚本——原生不支持 API 调用避免网络依赖导致失败。更高级的频率控制--interval参数可设为2d每 2 天、1w每周、1m每月# 每周一提交一次配合 --skip-weekends 实际效果相同 auto-commit --start 2024-01-01 --end 2024-12-31 --interval 1w --branch main # 每月 15 日提交需配合 --date-format 自定义 auto-commit --start 2024-01-01 --end 2024-12-31 --interval 1m --date-format 2024-%m-15避坑点--interval与--skip-weekends/--holidays不叠加生效。例如--interval 2d --skip-weekends不会自动跳过周末再取 2 天间隔而是先按 2 天步进生成日期再过滤掉周末。正确做法是先用--interval生成粗粒度日期再用--holidays手动剔除。3.3 自定义提交内容从固定消息到动态模板commit message 决定贡献图的语义价值。autoCommit支持三种模式1固定消息最简auto-commit --message docs: update README --branch main所有 commit 使用同一 message适合纯占位。2日期变量注入推荐auto-commit --message chore: daily sync on %Y-%m-%d --branch main%Y-%m-%d会被替换成当天实际日期如2024-05-20生成chore: daily sync on 2024-05-20。支持的变量变量含义示例%Y四位年份2024%m两位月份05%d两位日期20%H:%M:%S时分秒可选14:30:003外部脚本生成最强通过--script调用 Shell/Python 脚本实时生成 messageecho #!/bin/bash\necho feat: auto-generated on $(date %F) $(git rev-parse --short HEAD) gen-msg.sh chmod x gen-msg.sh auto-commit --script ./gen-msg.sh --branch main脚本 stdout 即为 commit message支持调用 Git 命令、读取文件、甚至调用 LLM 生成描述需自行处理 token 限速。重要提醒无论哪种模式message 长度不能超过 100 字符Git 限制且禁止包含控制字符\n,\t等否则git commit会失败。4. 避坑指南5 个真实翻车现场与血泪解决方案4.1 现象git commit报错author identity unknown但git config --global显示正常原因Git 配置作用域冲突。当仓库根目录下存在.git/configlocal 配置其优先级高于 global且若 local 配置中user.name或user.email为空或注释掉git commit会忽略 global 设置。解决# 进入仓库根目录检查 local 配置 cd /path/to/your/repo git config --local --get user.name # 若输出为空则 local 配置缺失 git config --local --get user.email # 强制写入 local 配置覆盖 global确保绝对生效 git config --local user.name Your Real Name git config --local user.email your.emailexample.com玄学经验某些 IDE如 VS Code内置终端会加载不同 shell profile导致git config --global在 IDE 终端生效但在系统终端失效。统一用git config --local一劳永逸。4.2 现象脚本运行完成但 GitHub 贡献图无变化git log显示 commit 存在原因commit 的 author email 与 GitHub 账号未验证邮箱不匹配。GitHub 仅将 commit 关联到已验证邮箱对应的账户即使git config设置正确若邮箱未在 GitHub Settings 中添加并验证commit 仍显示为 “ghost”。解决登录 GitHub → Settings → Emails点击 “Add email address”输入git config --global user.email的值查收验证邮件并点击链接勾选 “Keep my email address private”若启用必须用noreply邮箱重新运行auto-commit或对已有 commit 用git rebase修正 authorgit rebase -i --root # 将所有 pick 改为 edit保存退出 # 对每个 commit 执行 git commit --amend --authorYour Name verifiedemail.com --no-edit git rebase --continue git push --force-with-lease origin main4.3 现象auto-commit运行卡住终端无输出CPU 占用 100%原因Node.js 版本兼容性问题。auto-commit-cli依赖node-cron库而node-cron3.0.0在 Node.js v14 以下版本存在无限循环 bug尤其 Windows 环境。解决# 检查 Node.js 版本 node -v # 必须 v16.0.0 # 若版本过低升级 Node.js推荐 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端后 nvm install 18 nvm use 18 # 重装 auto-commit-cli npm uninstall -g auto-commit-cli npm install -g auto-commit-cli4.4 现象push 失败报错Updates were rejected because the tip of your current branch is behind原因远程分支有新提交如你手动 push 过其他 commit而auto-commit默认不拉取最新代码直接 force push 会因--force-with-lease检查失败。解决# 方案一先同步远程推荐安全 git pull origin main # 方案二强制覆盖仅当确定远程无重要变更 git push --force-with-lease origin main # 方案三在 auto-commit 命令中加 --pull 参数部分版本支持 auto-commit --pull --start 2024-01-01 --end 2024-01-31 --branch main后悔药若误用--force导致远程 commit 丢失可通过git reflog找回git reflog show origin/main git reset --hard commit-hash git push --force-with-lease origin main4.5 现象生成的 commit 时间戳正确但 GitHub 贡献图只显示部分日期如只亮 1 月不亮 2 月原因GitHub 贡献图按UTC 时间渲染而auto-commit默认使用本地时区生成--date。若本地时区为 UTC8如北京时间2024-01-01 00:00:00 CST对应 UTC 时间2023-12-31 16:00:00会被计入前一天。解决显式指定 UTC 时区auto-commit \ --start 2024-01-01 \ --end 2024-01-31 \ --date-format %Y-%m-%d 12:00:00 0000 \ --branch main0000强制设为 UTC12:00:00确保日期落在 UTC 日内避免跨日。验证方法在 GitHub commit 页面查看 “committed on” 时间应与--date-format完全一致。5. 进阶技巧用git commit --amend动态修正 commit让绿格子承载真实价值autoCommit生成的 commit 是“骨架”真正让它产生价值的是后续的git commit --amend。我坚持一个原则所有预生成的 commit必须在对应日期的真实工作完成后用--amend替换其 content 和 message。这既保持时间线真实又避免 commit 垃圾化。以下是我在三个典型场景下的实操流程5.1 场景一文档更新类 commit 的 amend 流程假设autoCommit为 2024-05-20 生成了占位 commitcommit abc1234 (HEAD - main) Author: Your Name emaildomain.com Date: Sun May 20 12:00:00 2024 0000 docs: daily sync on 2024-05-20当天你实际修改了README.md此时执行# 修改文件后暂存 git add README.md # amend 到当天最早的 commit即 abc1234 git commit --amend --no-edit # 强制推送到远程因 commit hash 改变 git push --force-with-lease origin main关键点--no-edit保留原 message--amend会替换abc1234的 tree 对象即文件快照但 author/date 不变。GitHub 贡献图仍计为 2024-05-20但内容已是真实文档。5.2 场景二多 commit 合并为单次有意义提交autoCommit每天生成 1 个 commit但实际开发中某天可能完成多个小任务如修 3 个 typo、更新 2 处 doc。此时用rebase -i合并# 查看最近 5 个 commit git log --oneline -n 5 # 交互式 rebase合并最后 3 个假设 hash 为 def5678, ghi9012, jkl3456 git rebase -i def5678~1 # 在编辑器中将后两行的 pick 改为 squash保存 # Git 会打开新编辑器让你编辑最终 message # 例如feat(readme): fix typos and update links [2024-05-20]参数表rebase 中的 action 选择Action效果适用场景pick保留原 commit默认无需修改squash合并到前一个 commit丢弃 message快速整合小修改reword保留 commit仅修改 message修正不规范的描述edit暂停 rebase允许 amend 当前 commit需要替换文件内容5.3 场景三用 pre-commit hook 自动注入上下文为避免 amend 时忘记更新 message我在仓库根目录创建.husky/pre-commit#!/bin/sh # 检查当前 commit 是否为 autoCommit 生成message 含 daily sync if git log -1 --pretty%B | grep -q daily sync; then # 自动生成带 PR/Issue 关联的 message ISSUE_ID$(git branch --show-current | sed s/feature\/// | cut -d- -f1) if [ -n $ISSUE_ID ]; then git commit --amend -m docs: update for #$ISSUE_ID [$(date %Y-%m-%d)] --no-edit fi fi这样每次git add git commit时若检测到是 autoCommit 占位 commit自动重写 message 为docs: update for #123 [2024-05-20]既保留日期又关联真实工作项。最后说句实在话我用autoCommit三年绿格子最密的一年恰恰是我删掉 80% 预生成 commit、只留下真正有价值的那些。工具的价值不在“填满”而在帮你把时间锚点和真实产出对齐——当你某天发现 contribution graph 里某个深绿色方块点开是篇解决实际问题的 PR那种踏实感比满屏绿色强十倍。希望帮到你。本文还有配套的精品资源点击获取