Back to Details

github-traffic

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: GitHub Traffic

Skill: GitHub 流量统计

Fetch and analyze GitHub repository traffic data — page views, git clones, referral sources, popular pages, and star growth. Optionally generate trend charts as PNG images.
Prerequisites:
  • gh
    CLI must be installed and authenticated
  • Push (write) access to the target repository is required — GitHub's Traffic API does not work with read-only access
  • matplotlib
    is optional (for PNG chart generation; falls back to ASCII if unavailable)
获取并分析GitHub仓库流量数据——页面浏览量、Git克隆量、来源网站、热门页面以及星标增长情况。可选择生成PNG格式的趋势图表。
前置要求：
  • 必须安装并完成
    gh
    CLI的身份验证
  • 需要目标仓库的推送（写入）权限——GitHub Traffic API不支持只读权限
  • matplotlib
    为可选依赖（用于生成PNG图表；若未安装则自动回退到ASCII格式图表）

When to Use

适用场景

  • The user asks about repository traffic, page views, clone counts, or where visitors come from
  • The user wants to see traffic trends over time (weekly, monthly, quarterly)
  • The user wants to generate traffic report charts for sharing or documentation
  • The user wants to periodically snapshot traffic data to build long-term history
  • 用户询问仓库流量、页面浏览量、克隆次数或访客来源
  • 用户希望查看一段时间内的流量趋势（每周、每月、每季度）
  • 用户希望生成可用于分享或文档的流量报告图表
  • 用户希望定期快照流量数据以构建长期历史记录

Important: GitHub Traffic API Limitations

重要提示：GitHub Traffic API 限制

GitHub only provides the last 14 days of traffic data. To track trends over longer periods (30 days, 90 days, etc.), the script stores each fetch in a local history file (
~/.github-traffic/<repo>_traffic.json
). Regular snapshots are required to build up history.
Recommended: set up a cron job or CI schedule to run the snapshot command periodically:
bash
undefined
GitHub仅提供最近14天的流量数据。若要跟踪更长周期（30天、90天等）的趋势，脚本会将每次获取的数据存储到本地历史文件中（
~/.github-traffic/<repo>_traffic.json
）。需要定期执行快照来积累历史数据。
推荐方案：设置cron任务或CI调度，定期运行快照命令：
bash
undefined

Daily snapshot via cron (no output, just stores data)

通过cron每日执行快照（无输出，仅存储数据）

0 9 * * * python /path/to/scripts/github_traffic.py owner/repo --snapshot

---
0 9 * * * python /path/to/scripts/github_traffic.py owner/repo --snapshot

---

Default Workflow

默认工作流程

bash
python /path/to/skills/github-traffic/scripts/github_traffic.py <owner/repo>
This will:
  1. Fetch current traffic data via 
    gh api
  2. Save a snapshot to 
    ~/.github-traffic/
    for historical tracking
  3. Display a formatted summary (views, clones, referrers, popular pages)
bash
python /path/to/skills/github-traffic/scripts/github_traffic.py <owner/repo>
该命令会执行以下操作：
  1. 通过
    gh api
    获取当前流量数据
  2. 将快照保存到
    ~/.github-traffic/
    目录用于历史追踪
  3. 显示格式化的汇总信息（浏览量、克隆量、来源网站、热门页面）

Generating Charts

生成图表

bash
undefined
bash
undefined

Generate PNG trend chart (last 30 days, default)

生成PNG趋势图表（默认显示最近30天数据）

python .../github_traffic.py owner/repo --chart
python .../github_traffic.py owner/repo --chart

Last 7 days

显示最近7天数据

python .../github_traffic.py owner/repo --chart --days 7
python .../github_traffic.py owner/repo --chart --days 7

Last 90 days (needs accumulated history)

显示最近90天数据（需要已积累的历史数据）

python .../github_traffic.py owner/repo --chart --days 90
python .../github_traffic.py owner/repo --chart --days 90

ASCII chart (no matplotlib needed)

生成ASCII格式图表（无需安装matplotlib）

python .../github_traffic.py owner/repo --ascii

The PNG chart includes up to 3 panels:
1. **Page Views** — total views and unique visitors (area chart)
2. **Git Clones** — total clones and unique cloners (bar + line chart)
3. **Star Growth** — star count over time (line chart, shown when multiple snapshots exist)

---
python .../github_traffic.py owner/repo --ascii

PNG图表最多包含3个面板：
1. **页面浏览量**——总浏览量和独立访客数（面积图）
2. **Git克隆量**——总克隆次数和独立克隆用户数（柱状图+折线图）
3. **星标增长**——星标数量随时间的变化（折线图，仅当存在多次快照时显示）

---

Script Options

脚本选项

FlagDefaultDescription
repo
(positional)		requiredRepository in 
owner/name
format
--chart
offGenerate PNG trend chart
--ascii
offForce ASCII bar chart output
--days
30
Number of days to include in chart
--history-dir
~/.github-traffic/
Directory for historical data storage
--output
<repo>_traffic.png
Output path for chart image
--snapshot
offFetch and store data only (no display)
标识默认值说明
repo
（位置参数）		必填仓库格式为
owner/name
--chart
关闭生成PNG格式趋势图表
--ascii
关闭强制输出ASCII格式柱状图
--days
30
图表中包含的天数
--history-dir
~/.github-traffic/
历史数据存储目录
--output
<repo>_traffic.png
图表输出路径
--snapshot
关闭仅获取并存储数据（不显示结果）

Examples

使用示例

bash
undefined
bash
undefined

Quick traffic summary

快速查看流量汇总

python .../github_traffic.py zilliztech/memsearch
python .../github_traffic.py zilliztech/memsearch

Weekly trend chart

生成周度趋势图表

python .../github_traffic.py zilliztech/memsearch --chart --days 7
python .../github_traffic.py zilliztech/memsearch --chart --days 7

Monthly trend chart, custom output path

生成月度趋势图表，自定义输出路径

python .../github_traffic.py zilliztech/memsearch --chart --days 30 --output ./reports/traffic.png
python .../github_traffic.py zilliztech/memsearch --chart --days 30 --output ./reports/traffic.png

Just store a snapshot (for cron jobs)

仅存储快照（用于cron任务）

python .../github_traffic.py zilliztech/memsearch --snapshot
python .../github_traffic.py zilliztech/memsearch --snapshot

ASCII chart when matplotlib is not available

当未安装matplotlib时生成ASCII格式图表

python .../github_traffic.py zilliztech/memsearch --ascii --days 14

---
python .../github_traffic.py zilliztech/memsearch --ascii --days 14

---

History & Long-Term Tracking

历史记录与长期追踪

Each run merges the current 14-day window into a persistent JSON file at 
~/.github-traffic/<owner>_<repo>_traffic.json
. The file contains:
  • Daily views: date → {views, unique}
  • Daily clones: date → {clones, unique}
  • Star snapshots: date → star count
  • Fetch metadata: timestamp, 14-day totals, stars, forks
To build meaningful 30/90-day charts, run the script at least every 14 days (daily is ideal). Gaps longer than 14 days will show as missing data in charts.
每次运行脚本时，会将当前14天的窗口数据合并到持久化JSON文件中，文件路径为
~/.github-traffic/<owner>_<repo>_traffic.json
。该文件包含：
  • 每日浏览量：日期 → {views, unique}
  • 每日克隆量：日期 → {clones, unique}
  • 星标快照：日期 → 星标数量
  • 获取元数据：时间戳、14天总计数据、星标数、复刻数
若要生成有意义的30/90天图表，至少每14天运行一次脚本（每日运行最佳）。若两次运行间隔超过14天，图表中会显示数据缺失。

Permissions

权限说明

The GitHub Traffic API requires push access to the repository. This means:
  • Repository owners and admins: full access
  • Collaborators with write/maintain role: full access
  • Read-only users and forkers: no access (API returns 403)
If you get a permission error, check your 
gh auth status
and ensure your token has the 
repo
scope.
GitHub Traffic API需要仓库的推送权限。这意味着：
  • 仓库所有者和管理员：拥有完整访问权限
  • 拥有写入/维护角色的协作者：拥有完整访问权限
  • 只读用户和复刻仓库用户：无访问权限（API返回403错误）
若遇到权限错误，请检查
gh auth status
并确保你的token拥有
repo
权限范围。

Troubleshooting

故障排查

ProblemSolution
"Must have push access" errorYou need write access to the repo. Check 
gh auth status
.
Chart shows only 14 daysGitHub only provides 14-day windows. Run 
--snapshot
regularly to accumulate history.
matplotlib not foundInstall with 
pip install matplotlib
. Or use 
--ascii
for text-based charts.
No data for some datesGitHub may not report days with zero traffic. These gaps are normal.
问题解决方案
“必须拥有推送权限”错误你需要仓库的写入权限。请检查
gh auth status
。
图表仅显示14天数据GitHub仅提供14天的窗口数据。定期运行
--snapshot
以积累历史数据。
未找到matplotlib使用
pip install matplotlib
安装。或使用
--ascii
参数生成文本格式图表。
部分日期无数据GitHub可能不会报告流量为零的日期。此类数据缺失属于正常情况。