每个工作日快结束时几乎都有一个固定动作写进度。有人对着空白聊天框发呆有人一边翻 Git 记录一边憋总结有人干脆把昨天的内容改改再发一遍。如果你的团队还没有强制要求日报你可能觉得这无所谓但如果遇到项目复盘、版本评审、绩效对齐你大概率会后悔当初没有留下像样的过程记录。我越来越倾向一个判断进度不该是下班后才开始写的而应该是开发过程中自然沉淀出来的。真正的“今天的进度”不是回忆作文而是从 Git 记录、Issue 状态、分支信息和构建结果里提炼出来的事实。这篇文章想做一件事把“写进度”这个每天重复的动作改造成一套低成本、可自动化、可追溯的工程实践。哪怕你的团队什么都不用换只要坚持规范提交信息再用一个几十行脚本就能把“今天的进度”变成一份有依据、可统计、可复用的文档。1. 这篇文章真正要解决的问题先对齐一个概念这里说的“今天的进度”不是个人日记而是团队协作语境下的进度同步记录。它的常见载体包括日报、周报、站会发言、项目管理工具里的评论、版本发布说明。这个动作真正让人痛苦的不是写本身而是三个问题。第一个问题是回忆成本高。很多人是下班前才打开聊天框这时候大脑已经装满了代码细节反而记不清今天具体完成了哪几件事。如果中途被叫去查过问题、开过会、改过紧急 Bug回忆的难度会更高。第二个问题是信息失真。靠记忆写出来的进度往往只有结论没有过程只有“做了什么”没有“为什么做”到了复盘的时候很难还原决策链路。第三个问题是无法度量。一张表格里写着“修复登录超时问题”但这个问题花了多长时间、改了哪些文件、关联哪个需求没人知道。这样的进度记录本质上是无效信息。那怎么解决我给出的思路是把进度记录的生成点从“下班后回忆”前置到“开发过程中”。你提交一次代码就留下一条进度你关闭一个 Issue就留下一个里程碑你在分支命名里带上需求编号就建立了一次可追溯的关联。这些动作不是你额外的工作量而是你本来就要做的开发行为。进度记录只是这些行为的副产物。具体来说这篇文章会教你三件事用规范的 Git 提交信息让每一次提交都变成一条“可读的进度”。用分支命名和 Issue 关联把代码变更映射到业务需求。用自动化脚本从 Git 历史中抽取今日记录生成 Markdown 格式的日报文件。这套方法不需要额外购买工具不需要团队成员改变工作习惯太多只要把提交信息从“update”换成一句话整个团队的进度透明度和复盘效率都会明显提升。2. 进度记录的三个层次与核心概念在动手操作之前先要理解进度记录为什么难自动化。因为不同团队对“进度”的定义和粒度完全不同我们需要先给这个概念分层。2.1 第一层印象型进度这是最常见的形态典型表达是“今天主要在做用户模块”“下午调了一个 Bug”“整体进展顺利”。这种进度只能用于口头同步无法被系统记录、统计、追溯。它的问题在于没有可验证的载体说和不说几乎没有区别。2.2 第二层结果型进度这一层开始有工具支撑典型表达是“完成了用户注册接口的开发提交了代码”“修复了订单超时问题关闭了 Issue #128”。这里的核心变化是进度有了可查询的对象比如 Git 提交、Issue、PR、测试报告。但它的生成仍然依赖人工整理属于半结构化状态。2.3 第三层行为型进度这一层才是本文的目标。所谓行为型进度是指进度记录直接由开发行为自动产生。你不需要专门“写”进度只需要保持规范的开发习惯系统就能从提交记录中抽取出一份结构化日报。它的核心载体有三个Commit Message每一次提交都是一条带类型、带范围的变更说明。分支名与 Issue分支名里带上 Issue 编号代码变更就能关联到需求或缺陷。Git Reflog 与日志Git 本身就记录了每个操作的精确时间这是自动化的数据基础。这三者结合就能实现“今天的进度”自动生成。2.4 一个需要避免的误区很多人一开始想把进度记录做得很重比如集成 Jira、禅道、Trello再把工时填写、任务状态、燃尽图全部打通。这个想法没有错但它的问题在于启动成本太高而且这些工具的填写动作依然依赖人工。更稳妥的做法是先在最底层把 Git 提交信息规范化再在上一层把分支和 Issue 关联起来最后用脚本做轻量抽取。这一套链路只要 Git 就能跑通不需要任何外部平台。3. 环境准备与前置条件在开始写脚本之前先把环境准备好。本文的方案依赖以下工具它们的安装方式在不同系统上略有差异但概念完全一致。3.1 必需工具工具用途安装建议Git记录代码变更提供进度原始数据版本不要低于 2.20建议使用 2.30 以上Python 3运行自动化脚本解析 Git 日志建议使用 Python 3.8 以上GitHub CLI可选读取 Issue 标题与状态让日报更完整如果不使用 GitHub可以跳过如果没有安装 Git可以先通过系统包管理器安装。以 Ubuntu/Debian 为例sudo apt update sudo apt install git python3 python3-pipmacOS 用户可以用 Homebrewbrew install git pythonWindows 用户建议安装 Git for Windows它自带 Git Bash脚本运行环境也一并解决。3.2 验证 Git 是否可用git --version python3 --version如果两条命令都能正确输出版本号说明基础环境已经就绪。3.3 本文的演示场景为了让后面的代码有明确的落地场景这里约定一个简单的项目背景项目名称demo-progress项目结构一个典型的 Python Web 项目包含用户模块和订单模块协作方式分支名关联 Issue 编号例如fix/128-order-timeout提交信息遵循 Conventional Commits 规范这个场景是很多中小团队的真实缩影没有专职的 DevRel 团队没有复杂的项目管理平台但大家每天都在产出代码每天都希望能有一份清晰的进度汇总。4. 核心流程拆解从提交信息到进度日报整个自动化的核心链路可以拆成五步每一步解决一个具体问题。下面按顺序拆解并说明为什么需要这一步。4.1 第一步统一提交信息格式提交信息是进度记录的最小单元。如果提交信息写得随意后续所有自动化和分析都没有意义。推荐使用 Conventional Commits 规范它可以做到人类可读也可以被脚本解析。最基础的格式是type(scope): subject其中type表示变更类型常见的取值包括type含义feat新功能fix修复缺陷docs文档变更style格式调整不影响逻辑refactor重构test测试相关chore构建任务、依赖调整等一个规范的提交信息示例feat(user): 新增用户注册接口 完成手机号校验、密码加密和用户信息落库。 关联需求#120这里的关键不是格式本身而是“为什么这样做”。格式统一的提交信息让 Git 历史变成一份可检索的变更日志而不是一串难以辨认的乱码。它是进度自动化的数据基础。4.2 第二步让分支名关联 Issue只有提交信息还不够。你还需要知道这次提交属于哪个需求或缺陷。把 Issue 编号放进分支名是最简单、零成本的关联方式。推荐的分支命名模式type/issue-id-short-desc例如fix/128-order-timeout feat/135-user-register docs/140-api-guide脚本可以解析当前分支名从中提取 Issue 编号。如果项目托管在 GitHub 上还能进一步调用 GitHub API 或 GitHub CLI 读取 Issue 标题和状态让日报更加完整。这一步的工程价值在于它把代码变更和业务需求连接在一起。将来做版本评审时你只要看一眼分支名就能知道这个功能是为了解决哪个问题。4.3 第三步用 Git 日志抽取今日记录Git 本身记录了每个提交的时间和作者。使用git log加上--since和--until参数可以精确筛选某个时间范围内的提交。示例命令git log --since2025-01-01 00:00:00 --until2025-01-01 23:59:59 --prettyformat:%h|%an|%s这条命令会输出当天所有的提交哈希、作者和提交信息。这是生成日报的原始素材。脚本要做的就是解析这个输出再按模块、类型、Issue 分组。4.4 第四步组装并输出 Markdown 日报拿到原始提交记录后脚本需要完成三件事按提交类型分组统计新增了哪些功能、修复了哪些 Bug。从分支名或提交信息中提取 Issue 编号并补充 Issue 标题。生成一份 Markdown 文件输出到项目的docs/daily/目录。日报的基本结构可以是# 2025-01-01 开发日报 ## 功能开发 - 新增用户注册接口 (feat(user)) [#120]() ## 缺陷修复 - 修复订单超时问题 (fix(order)) [#128]()4.5 第五步提交并发布日报生成的 Markdown 日报可以提交到仓库的docs/daily/目录。这样做的好处是日报本身就是代码提交的一部分天然可审计、可回溯。团队其他人可以通过 Git 历史查看某一天的完整开发情况。周报可以由日报聚合而来减少重复劳动。5. 完整示例用 Git 日志自动生成今日进度日报下面进入实操部分。我会提供一套完整、可直接复制运行的示例包含三个文件。5.1 规范 Git 提交信息的模板为了让团队成员更容易写出规范提交信息可以在项目根目录创建一个.gitmessage模板文件# 文件路径.gitmessage type(scope): subject body 关联需求#issue-id然后配置 Git 使用这个模板git config commit.template .gitmessage配置完成后每次执行git commit时编辑器会自动带入模板降低提交信息的“随便写”概率。5.2 核心脚本自动生成日报下面这个 Python 脚本是整套方案的核心。它读取今天或指定日期内的 Git 提交记录解析提交类型和 Issue 信息最终生成 Markdown 日报文件。#!/usr/bin/env python3 文件路径scripts/daily_progress.py 功能根据 Git 提交记录自动生成日报 Markdown 文件 用法 python3 scripts/daily_progress.py # 生成今天的日报 python3 scripts/daily_progress.py --date 2025-01-01 # 生成指定日期的日报 import argparse import re import subprocess from datetime import date, datetime from pathlib import Path COMMIT_TYPES { feat: 功能开发, fix: 缺陷修复, docs: 文档变更, refactor: 代码重构, chore: 工程配置, style: 格式调整, test: 测试补充, } ISSUE_PATTERN re.compile(r#(\d)) def run_git_log(since: str, until: str) - str: 运行 git log 获取指定时间段的提交记录 cmd [ git, log, --since, since, --until, until, --prettyformat:%h|%an|%D|%s, ] result subprocess.run(cmd, capture_outputTrue, textTrue, checkTrue) return result.stdout.strip() def parse_commit_line(line: str): 解析一行提交记录 parts line.split(|, 3) if len(parts) ! 4: return None commit_hash, author, refs, subject parts commit_type subject.split(:)[0].strip() if : in subject else other scope type_match re.match(r^([a-z])(?:\(([^)])\))?:, subject) if type_match: commit_type type_match.group(1) scope type_match.group(2) or issue_id None issue_match ISSUE_PATTERN.search(subject) if issue_match: issue_id issue_match.group(1) else: ref_match re.search(r/(\d)-, refs) if ref_match: issue_id ref_match.group(1) return { hash: commit_hash, author: author, refs: refs, subject: subject, type: commit_type, scope: scope, issue_id: issue_id, } def group_commits(commits): 按提交类型对记录分组 grouped {category: [] for category in COMMIT_TYPES.values()} grouped[其他] [] for commit in commits: category COMMIT_TYPES.get(commit[type], 其他) grouped[category].append(commit) return {key: value for key, value in grouped.items() if value} def render_markdown(target_date: str, grouped: dict) - str: 渲染 Markdown 日报内容 lines [] lines.append(f# {target_date} 开发进度) lines.append() lines.append( 本文档由 Git 提交记录自动生成人工修改前请确认不会被脚本覆盖。) lines.append() for category, commits in grouped.items(): lines.append(f## {category}) lines.append() for commit in commits: scope_part f({commit[scope]}) if commit[scope] else issue_part f [#{commit[issue_id]}] if commit[issue_id] else lines.append( f- {commit[subject]} f{commit[hash]} f{commit[author]}{issue_part} ) lines.append() return \n.join(lines) def write_daily_file(target_date: str, content: str) - Path: 写入日报文件到 docs/daily 目录 output_dir Path(docs/daily) output_dir.mkdir(parentsTrue, exist_okTrue) output_file output_dir / f{target_date}.md output_file.write_text(content, encodingutf-8) return output_file def main(): parser argparse.ArgumentParser(description自动生成开发日报) parser.add_argument(--date, typestr, defaultNone, help目标日期格式 YYYY-MM-DD) args parser.parse_args() if args.date: target_date args.date else: target_date date.today().isoformat() start_datetime datetime.fromisoformat(f{target_date} 00:00:00) end_datetime datetime.fromisoformat(f{target_date} 23:59:59) raw_log run_git_log( start_datetime.strftime(%Y-%m-%d %H:%M:%S), end_datetime.strftime(%Y-%m-%d %H:%M:%S), ) if not raw_log: print(f[INFO] {target_date} 没有找到提交记录) return commits [] for line in raw_log.splitlines(): parsed parse_commit_line(line) if parsed: commits.append(parsed) grouped group_commits(commits) content render_markdown(target_date, grouped) output_file write_daily_file(target_date, content) print(f[OK] 日报已生成{output_file}) print(f[INFO] 共 {len(commits)} 条提交记录) if __name__ __main__: main()脚本的核心逻辑可以拆成四个部分run_git_log负责调用 Git 命令取出指定日期内的所有提交记录。parse_commit_line负责解析每一行记录提取提交类型、影响范围、作者和 Issue 编号。group_commits按提交类型分组让日报按“功能开发”“缺陷修复”等类别展示。render_markdown负责把分组后的数据渲染成标准 Markdown 格式。脚本对 Issue 编号的提取做了两层处理先从提交信息里找#数字如果找不到再尝试从分支引用的/数字-模式里提取。这保证了即使提交信息里忘记写 Issue只要分支名符合规范日报依然能建立关联。5.3 一键运行脚本为了让团队成员不记 Python 命令可以提供一个简单的 Shell 包装脚本#!/usr/bin/env bash # 文件路径scripts/run_daily.sh BASE_DIR$(cd $(dirname $0)/.. pwd) cd $BASE_DIR python3 scripts/daily_progress.py $给脚本加执行权限chmod x scripts/run_daily.sh之后只需要执行./scripts/run_daily.sh就能生成当天日报。如果团队成员每天都用这个命令就等于建立了一个轻量级的“进度自动归档”机制。5.4 演示一次完整的模拟提交为了让验证过程更真实我在一个空仓库里做了如下操作创建项目结构mkdir demo-progress cd demo-progress git init mkdir -p docs/daily scripts配置 Git 用户信息git config user.name dev-leo git config user.email dev-leoexample.com创建脚本文件后进行几次模拟提交git checkout -b feat/120-user-register echo user_service user_service.py git add user_service.py git commit -m feat(user): 新增用户注册接口完成手机号和密码校验 关联需求#120git checkout -b fix/128-order-timeout echo order_fix order_fix.py git add order_fix.py git commit -m fix(order): 修复订单超时问题调整超时判定逻辑 关联缺陷#128然后切回主分支把两个分支合并回maingit checkout -b main 2/dev/null || git checkout main git merge feat/120-user-register --no-ff -m merge: 合并用户注册功能 git merge fix/128-order-timeout --no-ff -m merge: 合并订单超时修复当然这些只是为了演示创建的数据。如果你要记住“今天的进度”最好是基于实际开发中的提交记录而不是临时伪造。6. 运行结果与效果验证现在运行自动生成脚本./scripts/run_daily.sh --date 2025-01-01如果指定日期内有提交记录你会看到类似下面的输出[OK] 日报已生成docs/daily/2025-01-01.md [INFO] 共 4 条提交记录打开生成的docs/daily/2025-01-01.md内容大致如下# 2025-01-01 开发进度 本文档由 Git 提交记录自动生成人工修改前请确认不会被脚本覆盖。 ## 功能开发 - feat(user): 新增用户注册接口完成手机号和密码校验 a1b2c3d dev-leo [#120] ## 缺陷修复 - fix(order): 修复订单超时问题调整超时判定逻辑 e4f5a6b dev-leo [#128]6.1 如何判断生成结果是否正确判断日报是否合格可以按下面三个维度检查完整性当天所有提交是否都被包含有没有漏掉的提交。准确性提交类型是否被正确分组Issue 编号是否被正确提取。可读性别人拿到这份日报是否可以不用查代码就知道当天完成了什么。如果某一天的日报出现空文件先检查当天在目标分支上是否有提交。Git 日志默认只看当前分支如果你的提交在另一个分支而没有合并回来脚本会认为当天没有产出。6.2 如果失败先看哪里脚本失败最常见的错误是 Git 命令执行失败。运行脚本时如果看到类似fatal: not a git repository的错误说明你不在 Git 仓库目录中。请先确认pwd是否在项目根目录。另一个常见问题是时区。Git 默认使用本地时区但如果你设置了环境变量TZUTC生成的日期范围就会和本地时间错开。排错时优先检查这两点可以解决绝大部分问题。7. 常见问题与排查思路问题现象可能原因排查方式解决方案日报文件为空当天在当前分支没有提交记录运行git log --oneline --since00:00查看提交是否存在确认需要统计的分支必要时先合并分支再生成HTTP 392 Git 命令报错当前目录不在 Git 仓库内运行pwd和git status确认位置切换到仓库根目录后重新执行提交没有按类型分组提交信息不符合type(scope): subject格式检查git log --prettyformat:%s的提交内容统一团队提交规范必要时用脚本做一次历史清洗Issue 编号缺失提交信息中没有#数字分支名也不符合规范检查分支名和提交信息统一分支命名规则在提交模板中提示关联需求gh命令未找到GitHub CLI 未安装或未认证运行gh --version和gh auth status安装并登录 GitHub CLI或跳过 Issue 辅助功能脚本输出乱码终端编码问题查看locale输出确认 UTF-8Windows 用户建议在 Git Bash 中运行脚本8. 最佳实践与工程建议把这套机制真正用起来不只是跑通脚本那么简单还需要在团队协作层面做几件配套的事情。8.1 提交信息要写“新闻标题”不是写“日记”一个容易被忽略的点是提交信息里的 subject 应该像新闻标题告诉读者“本次变更带来了什么”而不是“我做了什么”。不要这样写update user_service.py fix bug要这样写fix(order): 修复超时未支付订单被错误标记为已支付的问题前一种写法对读者是无效信息后一种写法让任何时间点的进度都能被理解。这是投入产出比最高的一项改进。8.2 分支即任务合并即里程碑如果你能坚持“一个分支只做一个任务”的原则进度管理的粒度会清晰很多。分支合并到主分支的时点就是任务完成的时点。这种模式下查看 Git 合并历史就等同于查看项目里程碑。配合这个方法我建议在合并 PR 时使用 squash 模式。这样主分支的提交历史会保持整齐每个任务只对应一条提交记录日报的生成也会更准确。8.3 日报要提交到仓库而不是只发到聊天群把日报写入docs/daily/目录并提交到远程仓库有几个实际好处第一日报不依赖任何人的聊天记录永远可查第二日报本身也纳入版本管理可以回溯修改历史第三后续周报、月报都可以从这些文件中聚合生成。如果你不想让日报污染主仓库可以单独建一个progress仓库来存放。这不影响脚本逻辑只是目标路径不同。8.4 周报用“聚合”代替“回忆”有了日报之后周报就不需要从头开始写了。把docs/daily/目录下的 5 个文件合并按模块归类就能快速生成一份周报草稿。这个过程依然可以用脚本完成甚至可以在 CI 中自动执行。8.5 不要过度依赖自动化最后再提醒一句自动化负责“事实记录”但人负责“决策解释”。脚本可以告诉你“今天改了什么”但为什么这么改、为什么选这个方案、遇到了什么风险这些内容还是要靠人来补充。一份好的进度记录应该包含事实、理由和风险三个层面而不是只有冷冰冰的提交列表。8.6 团队推广时的节奏控制如果团队之前没有提交规范不要一次性引入太多规则。建议分三步走第一阶段只约定提交信息的类型前缀允许feat、fix两类起步。第二阶段加入scope范围描述让提交能关联到模块。第三阶段引入分支命名与 Issue 关联启动日报脚本。渐进式推广的阻力最小也更容易让团队成员理解每一步的价值。9. 总结与后续学习方向这篇文章把“今天的进度”从一个日常动作拆解成了一个可控的工程链路。你现在应该能回答这几个问题为什么进度难写因为进度记录被放到了开发行为之后变成了回忆作文。怎么解决让开发行为本身留下结构化痕迹然后用脚本抽取生成日报。最小落地方式是什么规范提交信息规范分支命名运行一个 Python 脚本。适合什么团队从个人开源项目到中小研发团队都可以用没有平台依赖。如果要从这里继续深入有四个方向值得探索第一个方向是周报聚合。在日报基础上写一个按周汇总的脚本输出本周完成功能、修复缺陷的数量与列表。第二个方向是趋势度量。例如统计每个模块的提交频率、平均修复时间、功能开发与缺陷修复的比例这些指标可以辅助团队发现测试薄弱区。第三个方向是与 CI/CD 集成。在流水线里自动生成日报并在群机器人中推送摘要。第四个方向是数据可视化。把日报数据录入 SQLite 或 ClickHouse用 Web 面板展示团队历史进度。关于实际项目中的落地有一点想特别提醒不要在刚开始推行时过分追求格式完美。格式是为了让信息被理解如果团队成员因为模板太复杂而不愿意提交代码反而会损害效率。先用最简单的feat:和fix:标记跑起来让脚本每天生成一份基础日报再逐渐补充类型和关联规则。技术的价值在于帮助你减少重复劳动而不是给你增加新的负担。如果今天你面前正好有一个 Git 仓库建议从明天开始把第一次提交信息写完整一点。几天以后你会发现自己第一次对“进度”这件事有了实感。