git-week-summary（git 周总结）

Git Week Summary

Generates a weekly git change summary for the current repository: commits in the current week (Mon–Sun), filtered by author and by file extensions (e.g. .swift, .py). Output is JSON only (no terminal output): a summary file and one fragment file per commit.

When to Use

• User wants a weekly git summary or week in review of their commits
• User asks for standup or report content based on git activity
• User wants to see what changed this week in a repo, filtered by author or file type

How to Run

Run from the repository root of the repo you want to summarize (the directory that contains .git). The script is at scripts/git_weeksummary.py in this skill.

python3 <skill-root>/scripts/git_weeksummary.py --author EMAIL --suffix EXT [EXT ...] --output-dir DIR

Your git email (for --author): From the repo root, run git config user.email for the effective value (repo-specific, or global if unset). Use git config --global user.email to see only the global setting.

Choosing --suffix: Pick extensions by project type (e.g. .py for Python, .swift for Swift, .ts .tsx for TypeScript). A leading dot is optional (e.g. py and .py are equivalent). It is common to exclude resources and binary files (e.g. .png, .jpg, .pdf, .woff, .mp4) and focus on source code so the summary stays relevant and smaller.

--output-dir (required): Temporary directory for storing the JSON output. Provide a system temporary directory or a secure temporary sandbox (e.g. /tmp/weeksummary, ./reports). If you prefer not to provide one explicitly, use the magic string $SYSTEMTEMP$ (resolves to e.g. $TMPDIR/weeksummary on Unix). Prefer temp or sandbox paths to avoid writing into the repo or other sensitive locations.

Week is always Mon–Sun (first workday Monday).

Invocation by platform

• macOS: Use python3; python is often absent or Python 2.
• Linux: Prefer python3; on some distros python points to Python 3.
• Windows: Use python (python.org or Microsoft Store) or py -3 (Python launcher). In Git Bash or WSL, python3 is often available.
• uv: From a uv-managed project (or the skill repo): uv run <skill-root>/scripts/git_weeksummary.py [options]. The script needs only the stdlib, so no extra deps.

Examples

# Use system temp ($SYSTEMTEMP$ → TMPDIR/weeksummary or equivalent)
python3 scripts/git_weeksummary.py --author "you@example.com" --suffix .swift --output-dir '$SYSTEMTEMP$'

# Swift and Python, sandbox path
python3 scripts/git_weeksummary.py --author "you@example.com" --suffix .swift .py --output-dir /tmp/weeksummary

# Python only, custom output base
python3 scripts/git_weeksummary.py --author "you@example.com" --suffix .py --output-dir ./reports

# With uv (from a uv project or the skill repo)
uv run python scripts/git_weeksummary.py --author "you@example.com" --suffix .py --output-dir '$SYSTEMTEMP$'

Agent note: Run from the target repo’s root. Use the full path to scripts/git_weeksummary.py (e.g. from the skill’s install directory) when the working directory is the repo to summarize.

Output

The script prints nothing to stdout. On error (e.g. not a git repository) it writes to stderr and exits non‑zero.

JSON (under --output-dir):

<output-dir>/<repo_name>/git_summary_<YYYYMM>_<DD>/

Overwrite: If that directory already exists (e.g. from a previous run for the same week), the script removes it and recreates it. Each run overwrites that week’s output.

1. 0_git_summary_<YYYYMM>_<DD>.json — summary: {"_meta": {"all_in_one_size": <bytes>, "fragment_sizes": {"<sha>": <bytes>,...}}, "<sha>": {"date", "message", "filechanged", "changes"},...}. all_in_one_size is the sum of all fragment file sizes (UTF‑8 bytes). fragment_sizes is the byte size of each N_<sha>.json file.
2. 1_<sha>.json, 2_<sha>.json,... — one fragment per commit (chronological order): {"date", "message", "filechanged", "changes"}. date is YYYY-MM-DD. filechanged is a list of repo-relative paths. changes is a map from repo-relative path to that file’s unified-diff hunk content. Commits with no matching files after the suffix filter are omitted.

For callers: Check _meta.all_in_one_size and _meta.fragment_sizes first. If all_in_one_size is within your context limit, read 0_git_summary_*.json to get the full index and all commit data. If it is too large, read the fragment files (1_<sha>.json, 2_<sha>.json, …) one by one as needed; use fragment_sizes to decide which to load or in what order.

Script

scripts/git_weeksummary.py. Dependencies: Python 3 standard library only.

Packaging (e.g. for Claude)

1. Use the git-week-summary folder as the Skill root.
2. ZIP the folder so the root of the archive is git-week-summary/ (not the files directly).
3. Correct: git-week-summary.zip → git-week-summary/SKILL.md, git-week-summary/scripts/git_weeksummary.py.