codeyear 0.2.14__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codeyear/__init__.py +3 -0
- codeyear/__main__.py +6 -0
- codeyear/card.py +720 -0
- codeyear/cli.py +450 -0
- codeyear/config.py +114 -0
- codeyear/github_public.py +590 -0
- codeyear/gui.py +960 -0
- codeyear/html_report.py +1663 -0
- codeyear/i18n.py +345 -0
- codeyear/keywords.py +98 -0
- codeyear/languages.py +132 -0
- codeyear/personas.py +171 -0
- codeyear/poster.py +992 -0
- codeyear/profile.py +180 -0
- codeyear/report_theme.py +890 -0
- codeyear/runner.py +304 -0
- codeyear/scanner.py +491 -0
- codeyear/server.py +293 -0
- codeyear/stats.py +736 -0
- codeyear/updater.py +238 -0
- codeyear/wizard.py +221 -0
- codeyear-0.2.14.dist-info/METADATA +559 -0
- codeyear-0.2.14.dist-info/RECORD +27 -0
- codeyear-0.2.14.dist-info/WHEEL +5 -0
- codeyear-0.2.14.dist-info/entry_points.txt +5 -0
- codeyear-0.2.14.dist-info/licenses/LICENSE +21 -0
- codeyear-0.2.14.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,559 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codeyear
|
|
3
|
+
Version: 0.2.14
|
|
4
|
+
Summary: Local-first annual coding report generated from your own git history.
|
|
5
|
+
Author: CodeYear contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Qiongkura/codeyear
|
|
8
|
+
Project-URL: Repository, https://github.com/Qiongkura/codeyear
|
|
9
|
+
Project-URL: Issues, https://github.com/Qiongkura/codeyear/issues
|
|
10
|
+
Keywords: git,annual-report,developer-tools,privacy,local-first
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Environment :: Win32 (MS Windows)
|
|
14
|
+
Classifier: Environment :: X11 Applications
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
22
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: Pillow>=9.0
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=8; extra == "dev"
|
|
29
|
+
Requires-Dist: pytest-cov>=5; extra == "dev"
|
|
30
|
+
Requires-Dist: ruff>=0.6; extra == "dev"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
# CodeYear · 代码手账
|
|
34
|
+
|
|
35
|
+
[](https://github.com/Qiongkura/codeyear/actions/workflows/ci.yml)
|
|
36
|
+
[](https://github.com/Qiongkura/codeyear/releases/latest)
|
|
37
|
+
[](https://www.python.org/)
|
|
38
|
+
[](https://qiongkura.github.io/codeyear/index.html)
|
|
39
|
+
|
|
40
|
+
**简体中文** | [English](README.en.md) · [中文简介](docs/intro.zh.md)
|
|
41
|
+
|
|
42
|
+
> 扫描你本地的 git 仓库,生成一份**只属于你**的年度代码手账:中英双语 HTML 报告、
|
|
43
|
+
> 2400×3200 海报、完整长图,以及 GitHub 主页卡片。默认只读本地 git,不登录、不上传;
|
|
44
|
+
> 公开 GitHub 模式是可选联网功能。
|
|
45
|
+
|
|
46
|
+

|
|
47
|
+
|
|
48
|
+
**在线示例**:[https://qiongkura.github.io/codeyear/index.html](https://qiongkura.github.io/codeyear/index.html)
|
|
49
|
+
|
|
50
|
+
**示例报告**:[中文](docs/sample-report.html) · [English](docs/sample-report-en.html)
|
|
51
|
+
(脱敏演示数据,可直接浏览器打开)
|
|
52
|
+
|
|
53
|
+
## 下载 / 安装
|
|
54
|
+
|
|
55
|
+
**Windows(不需要 Python)**:从 [Releases](https://github.com/Qiongkura/codeyear/releases/latest)
|
|
56
|
+
下载 `CodeYear.exe`,双击打开,选择项目目录即可。
|
|
57
|
+
|
|
58
|
+
**开发者**:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
pip install git+https://github.com/Qiongkura/codeyear.git
|
|
62
|
+
codeyear
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
也可以从 Release 下载 wheel:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
pip install https://github.com/Qiongkura/codeyear/releases/download/v0.2.14/codeyear-0.2.14-py3-none-any.whl
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
> exe 未做代码签名,Windows SmartScreen 可能提示;点「更多信息 → 仍要运行」。
|
|
72
|
+
> macOS / Linux 用 wheel 或源码运行。
|
|
73
|
+
|
|
74
|
+
## 30 秒上手
|
|
75
|
+
|
|
76
|
+
需要 Python 3.9+ 和 Git。把 `~/code` 换成你存放项目的文件夹(不是 CodeYear 仓库本身):
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
git clone https://github.com/Qiongkura/codeyear.git
|
|
80
|
+
cd codeyear
|
|
81
|
+
pip install -r requirements.txt
|
|
82
|
+
python -m codeyear scan ~/code --open
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
或者用 uv 一行免安装运行(需要先装 [uv](https://docs.astral.sh/uv/)):
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
uvx --from "https://github.com/Qiongkura/codeyear/releases/download/v0.2.14/codeyear-0.2.14-py3-none-any.whl" codeyear scan ~/code --open
|
|
89
|
+
# 或直接从源码运行:
|
|
90
|
+
uvx --from git+https://github.com/Qiongkura/codeyear.git codeyear scan ~/code --open
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
常用扫描参数与软件内更新:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
# 统计过去 365 天(年中复盘 / 入职一周年),排除练习或第三方仓库
|
|
97
|
+
codeyear scan ~/code --rolling --exclude "temp,*-demo" --open
|
|
98
|
+
|
|
99
|
+
# 检查或一键升级到最新版本(GUI 右上角也会自动提示新版)
|
|
100
|
+
codeyear update
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Windows 把 `~/code` 换成 `C:\code` 之类的路径。报告会生成到 `codeyear-output/`,
|
|
104
|
+
`--open` 会自动打开 HTML。
|
|
105
|
+
|
|
106
|
+
## 图形界面 / 交互式向导
|
|
107
|
+
|
|
108
|
+
想点选操作,直接运行:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
codeyear
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
会打开桌面窗口:添加多个目录、检查仓库数量、看进度条、选输出位置,完成后直接打开报告。
|
|
115
|
+
Windows 也可以在仓库根目录双击 `CodeYear.cmd`。
|
|
116
|
+
|
|
117
|
+
需要 Tkinter;Windows/macOS 的 Python 自带,Linux 装 `python3-tk`。安装后也可以运行 `codeyear-gui`。
|
|
118
|
+
|
|
119
|
+
## 界面语言
|
|
120
|
+
|
|
121
|
+
CLI 和终端向导默认跟随系统语言,也可以强制英文:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
codeyear --lang en scan ~/code --open
|
|
125
|
+
CODEYEAR_LANG=en codeyear scan ~/code --open
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`--lang` 要放在子命令前面。GUI 也跟随同一语言设置;报告本身一直是中英双语。
|
|
129
|
+
英文界面可以用 `codeyear --lang en gui`(或 `codeyear-gui --lang en`)启动,
|
|
130
|
+
GUI 的「打开报告」会直接打开英文 HTML;中英文两份报告始终都会生成,
|
|
131
|
+
英文界面还会额外生成英文 PNG 海报和长图。GUI 右上角的「English / 中文」
|
|
132
|
+
可以在窗口内直接切换语言,已选目录和参数会保留。
|
|
133
|
+
`--profile-repo` 会按这个语言选择写入主页的卡片:默认中文,`--lang en` 时写英文卡片。
|
|
134
|
+
|
|
135
|
+
喜欢终端就用:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
codeyear tui
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
终端向导同样支持多目录、仓库数量、进度条和输出目录。
|
|
142
|
+
|
|
143
|
+
## 公开 GitHub 模式(可选联网)
|
|
144
|
+
|
|
145
|
+
不想扫描本地仓库,可以先看一个公开账号:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
codeyear github Qiongkura --year 2026 --out ./codeyear-github
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
- 只读公开仓库,不会读取私有仓库。
|
|
152
|
+
- **口径**:只统计该账号名下的公开仓库(GitHub `type=owner`),以及 GitHub 能关联到该账号的提交;组织仓库、collaborator 仓库、未绑定 GitHub 账号的邮箱提交不计入,合并提交也不计入。需要完整历史请用本地 `scan`。
|
|
153
|
+
- 需要网络;默认最多拉 200 条提交详情,可用 `--max-commits` 调整。
|
|
154
|
+
- 没有 token 时最多 30 条,且容易触发 GitHub API 限流;建议设置 `GITHUB_TOKEN` 或传 `--token`。
|
|
155
|
+
- 公开仓库提交很多时,`GITHUB_TOKEN` 在 Actions 里通常只有 1,000 次/小时额度;可在
|
|
156
|
+
Profile 仓库添加 `CODEYEAR_TOKEN`(PAT)并在 workflow 里使用,避免统计被截断。
|
|
157
|
+
- 输出包含完整报告、海报、长图、卡片,以及 `codeyear-2026-embed.md`,可以直接粘到 Profile README。
|
|
158
|
+
- 只想要卡片:加 `--card-only`,跳过报告、海报和长图。
|
|
159
|
+
- 想直接更新 Profile 仓库:加 `--profile-repo ~/Qiongkura`(只写本地)或再加 `--push-profile`(联网推送)。
|
|
160
|
+
- 跨年自动更新:加 `--fallback-previous`,当年还没有提交时继续用上一年的卡片。
|
|
161
|
+
- 重复运行更快:加 `--cache-dir ~/.cache/codeyear` 缓存 commit 详情(按 SHA,不会过期)。
|
|
162
|
+
- 卡片主题:`--theme paper|mono|forest|ocean`;[主题预览](docs/themes.md)。
|
|
163
|
+
- 本地 `scan` 仍是默认模式,代码不会上传。
|
|
164
|
+
|
|
165
|
+
**公开模式的数据边界**
|
|
166
|
+
|
|
167
|
+
- 只统计账号名下的公开仓库,组织仓库、collaborator 仓库、私有仓库不包含;只算 GitHub 能关联到该账号的提交,merge 也不计。
|
|
168
|
+
- 每条 commit 详情是 1 次 API 请求,`--max-commits` 是本次运行的硬上限,默认 200;Profile Action 模板设为 5,000。
|
|
169
|
+
- Actions 内置 `GITHUB_TOKEN` 通常只有 1,000 次/小时/仓库;添加 `CODEYEAR_TOKEN`(PAT)后通常有 5,000 次/小时。
|
|
170
|
+
- 缓存会复用已拉取的 commit 详情,所以日常增量更新很快;缓存上限为 5,000 条。
|
|
171
|
+
- 公开模式的提交时间会按运行机器的本地时区换算;“深夜/作息”统计取决于 `TZ`。
|
|
172
|
+
Profile 模板默认 `TZ=Asia/Shanghai`,其他时区改这一行即可。
|
|
173
|
+
也可以用 `--tz UTC+8` / `CODEYEAR_TZ=Asia/Shanghai` 显式指定;在线服务支持
|
|
174
|
+
`/card.svg?...&tz=Asia/Shanghai`。
|
|
175
|
+
- 超过 5,000 次/年、或需要统计组织/私有仓库时,用本地 `codeyear scan`,没有这些 API 上限。
|
|
176
|
+
|
|
177
|
+
### 在线卡片服务
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
codeyear serve --port 8000
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
打开 `http://127.0.0.1:8000`,输入用户名即可生成卡片;服务端带 1 小时 LRU 缓存和每 IP 限流。
|
|
184
|
+
|
|
185
|
+
部署到 Render / Railway / Fly / VPS:设置 `GITHUB_TOKEN`,启动命令:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
codeyear serve --host 0.0.0.0 --port $PORT --max-commits 500
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
仓库里带 `Dockerfile` 和 `render.yaml`,Render 可以直接识别。镜像也会发布到 GHCR
|
|
192
|
+
(包默认私有,需要在 GitHub 的 Package settings 里设为 Public 后匿名拉取):
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
docker run -p 8000:8000 -e GITHUB_TOKEN=your_token ghcr.io/qiongkura/codeyear:latest
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
```text
|
|
199
|
+
https://your-host/card.svg?username=Qiongkura&year=2026
|
|
200
|
+
https://your-host/card-dark.svg?username=Qiongkura&year=2026
|
|
201
|
+
https://your-host/card.svg?username=Qiongkura&year=2026&lang=en
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`--max-commits` 是每次最多拉多少条提交详情,不是 GitHub 的总提交数;每条详情一次 API 请求。
|
|
205
|
+
默认 200,无 token 会自动降为 30。要更完整就设置 token 并调大;完整本地历史仍用 `scan`。
|
|
206
|
+
|
|
207
|
+
[](https://render.com/deploy?repo=https://github.com/Qiongkura/codeyear)
|
|
208
|
+
|
|
209
|
+
如果只有 Cloudflare,可以用 Tunnel 把本机服务暴露出去:
|
|
210
|
+
[Cloudflare Tunnel 部署步骤](docs/cloudflare.md)。
|
|
211
|
+
|
|
212
|
+
> Action 和在线服务都只使用公开 GitHub 数据;要自动更新包含私有项目的本地卡片,
|
|
213
|
+
> 需要本机定时任务或自托管 runner。
|
|
214
|
+
>
|
|
215
|
+
> Action 会自动把卡片块写进 Profile README(首次运行也会插入),并使用带版本号的
|
|
216
|
+
> 文件名绕过 GitHub 的图片缓存;无需手动粘贴 embed 片段。模板默认每天 04:00 UTC
|
|
217
|
+
> 更新;改 workflow 里的 `cron` 可切成每周一 `0 4 * * 1` 或每月 1 日 `0 4 1 * *`。
|
|
218
|
+
> 跨年时如果新的一年还没有提交,`--fallback-previous` 会继续显示上一年的卡片。
|
|
219
|
+
> 模板直接安装 Release 里的 wheel;升级时改 `CODEYEAR_VERSION`(当前 `0.2.14`)。
|
|
220
|
+
> 提交量大的账号建议在 Profile 仓库添加 `CODEYEAR_TOKEN`(PAT)secret;模板会优先使用它,
|
|
221
|
+
> 否则回退到 `GITHUB_TOKEN`。`GITHUB_TOKEN` 在 Actions 里通常只有 1,000 次/小时额度,
|
|
222
|
+
> 超过这个量时提交详情会被截断。
|
|
223
|
+
|
|
224
|
+
GitHub Action 自动更新模板:[docs/codeyear-card.yml](docs/codeyear-card.yml)。
|
|
225
|
+
|
|
226
|
+
用法:
|
|
227
|
+
|
|
228
|
+
1. 在 `<用户名>/<用户名>` 仓库新建 `.github/workflows/codeyear-card.yml`
|
|
229
|
+
2. 粘贴模板内容
|
|
230
|
+
3. 在 Actions 页面手动运行一次 `Update CodeYear card`
|
|
231
|
+
|
|
232
|
+
之后按 cron 自动更新;README 里没有卡片块时会自动插入,有旧年份引用时会自动替换。
|
|
233
|
+
|
|
234
|
+
## 它是什么
|
|
235
|
+
|
|
236
|
+
CodeYear 是给开发者做的「年度报告」。官方的 Wrapped 通常只覆盖公开数据、还要授权;
|
|
237
|
+
而大多数人的代码在私有仓库、公司内网或 Gitee。CodeYear 直接读本机的 `.git`,
|
|
238
|
+
所以私有项目、离线环境、公司电脑都能用。
|
|
239
|
+
|
|
240
|
+
它默认**只统计你本人作者的提交**(按 git `user.name` / `user.email` 识别),
|
|
241
|
+
并且会把同一个项目的多个副本(`work/`、`backup/`、fork)合并成一个,不会重复计数。
|
|
242
|
+
|
|
243
|
+
## 报告里有什么
|
|
244
|
+
|
|
245
|
+
**年度概览**
|
|
246
|
+
- 一个总结称号,按数据选(夜里出活的人、主要在和 bug 打交道的人、删代码比写代码还多的人…)
|
|
247
|
+
- 4 个指标标签(提交 / 语言 / 仓库 / 活跃日)+ 一段数字总结
|
|
248
|
+
|
|
249
|
+
**年度之最**
|
|
250
|
+
- 最忙的一天 / 一周、最长连续、最长空窗、最大单次提交、最长的 commit
|
|
251
|
+
- 第一次与最后一次提交的时间、仓库
|
|
252
|
+
|
|
253
|
+
**仓库档案**(提交最多的 3 个仓库)
|
|
254
|
+
- 提交数、行变更、主要语言、首次→最近提交
|
|
255
|
+
- 最常改的文件、最近 3 条真实 commit
|
|
256
|
+
- 简介直接引用该仓库 README 的第一行
|
|
257
|
+
|
|
258
|
+
**全部仓库索引**
|
|
259
|
+
- 每个仓库的 README 一句话、技术栈、自有代码、最近提交、活跃状态
|
|
260
|
+
- 可按主要语言筛选、按关键词搜索;没写 README 的会如实标注
|
|
261
|
+
|
|
262
|
+
**数据分析**
|
|
263
|
+
- 月度节奏、7×24 提交时钟、全年热力图
|
|
264
|
+
- 代码构成(按行数排序)、语言构成、**语言栈季度变化**
|
|
265
|
+
- 提交规模分布、提交类型、高频词、**消息长度分布**
|
|
266
|
+
- 增删比(含删除最多的仓库)、**编码会话**(间隔 ≤ 2 小时的提交算一次)
|
|
267
|
+
- 仓库生命周期甘特图、**仓库墓园**(30 天没动)
|
|
268
|
+
- 最常改的文件(完整路径)
|
|
269
|
+
- 本地仓库考古:全历史提交总数、最早一次提交(码龄)、今年新开的仓库、版本 tag
|
|
270
|
+
(仓库口径,与只统计你本人的年度数字分开展示)
|
|
271
|
+
- 同比去年:`--compare` 会多扫一年;封面显示摘要,数据分析区有 10 项指标对照和 12 个月双柱图
|
|
272
|
+
|
|
273
|
+
**设计**
|
|
274
|
+
- 纸面档案:暖纸底、墨色、朱红强调,衬线大标题 + 等宽数据,方角、hairline
|
|
275
|
+
- 版式:书脊式目录、超大年份封面(标注本次扫描目录)、浅色四格统计条;
|
|
276
|
+
每节末尾「下一节」,滚动时目录高亮,右下角一键回到顶部
|
|
277
|
+
- 动效:整页轻微淡入,目录高亮和链接颜色有短过渡;不做滚动弹跳、数字滚动;尊重 `prefers-reduced-motion`
|
|
278
|
+
- 中英双语:同时生成中文和英文报告,页内可切换
|
|
279
|
+
- 纯 vanilla JS,不依赖任何第三方前端库;尊重 `prefers-reduced-motion`
|
|
280
|
+
- 字体:系统衬线(Georgia / Songti / SimSun)+ 等宽(Consolas),不加载任何外部字体
|
|
281
|
+
- GitHub 卡片:640×1254 海报式布局,透明底、无整块底色,中英文各一组浅色/深色版本,靠大字号、细线和一个陶土色强调区分层级
|
|
282
|
+
- 卡片内有 8 条大白话分析:主攻项目、写码时段、改动大小、一次写多久、写删比例、最忙月份、精力集中度、提交说明
|
|
283
|
+
- 卡片主题:paper / mono / forest / ocean;公开卡片服务支持 `theme` 参数
|
|
284
|
+
- 报告可直接通过浏览器打印/导出 PDF
|
|
285
|
+
- 可访问性:跳过导航链接、键盘焦点样式、图表 aria-label
|
|
286
|
+
|
|
287
|
+
## 安装与输出
|
|
288
|
+
|
|
289
|
+
上面的命令只会安装 Pillow。想把 CodeYear 安装成全局命令:
|
|
290
|
+
|
|
291
|
+
```bash
|
|
292
|
+
pip install -e .
|
|
293
|
+
codeyear scan ~/code --year 2026 --open
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
输出默认在 `./codeyear-output/`:
|
|
297
|
+
|
|
298
|
+
```text
|
|
299
|
+
codeyear-2026.html 中文报告,浏览器直接打开
|
|
300
|
+
codeyear-2026-en.html 英文报告,同一份数据
|
|
301
|
+
codeyear-2026.png 2400×3200 海报(2× 渲染),直接发图
|
|
302
|
+
codeyear-2026-en.png 英文海报(界面为英文时额外生成)
|
|
303
|
+
codeyear-2026-long.png 2400×5330 完整长图,适合发长图/存档
|
|
304
|
+
codeyear-2026-en-long.png 英文完整长图(界面为英文时额外生成)
|
|
305
|
+
codeyear-2026-card.svg 640×1254 海报式 GitHub 卡片(透明底 · 浅色)
|
|
306
|
+
codeyear-2026-card-dark.svg 640×1254 同一张卡片的深色版(透明底)
|
|
307
|
+
codeyear-2026-card-en.svg 640×1254 英文版 GitHub 卡片(透明底 · 浅色)
|
|
308
|
+
codeyear-2026-card-en-dark.svg 640×1254 英文版卡片的深色版(透明底)
|
|
309
|
+
codeyear-2026.json 原始统计数据,方便二次开发
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
海报示例(同一份数据):
|
|
313
|
+
|
|
314
|
+
<img src="docs/sample.png" width="420" alt="CodeYear PNG 海报示例">
|
|
315
|
+
|
|
316
|
+
完整长图示例:[docs/sample-long.png](docs/sample-long.png)
|
|
317
|
+
|
|
318
|
+
英文海报示例:[docs/sample-en.png](docs/sample-en.png) · [英文长图](docs/sample-en-long.png)
|
|
319
|
+
|
|
320
|
+
## 挂到 GitHub 主页
|
|
321
|
+
|
|
322
|
+
扫描时会额外生成中英文各一组浅色/深色卡片,都没有背景色。把对应语言的两个文件
|
|
323
|
+
一起提交到你的 Profile 仓库(仓库名与用户名相同,例如 `Qiongkura/Qiongkura`),
|
|
324
|
+
在 README 里用 `<picture>` 按主题切换(下面是中文版;英文主页把文件名换成
|
|
325
|
+
`codeyear-2026-card-en.svg` / `-card-en-dark.svg`):
|
|
326
|
+
|
|
327
|
+
```md
|
|
328
|
+
<picture>
|
|
329
|
+
<source media="(prefers-color-scheme: dark)" srcset="./codeyear-2026-card-dark.svg">
|
|
330
|
+
<img src="./codeyear-2026-card.svg" width="640" alt="CodeYear 2026">
|
|
331
|
+
</picture>
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
使用 `<picture>` 时,GitHub 在浅色/深色主题下会自动选对应版本;如果只写 `<img>`,
|
|
335
|
+
深色主题下会显示浅色版。卡片是静态文件,重新运行扫描并提交即可更新。
|
|
336
|
+
|
|
337
|
+
> 注意:GitHub 会通过图片代理缓存 README 里的图片。用 `--profile-repo` 或下面的
|
|
338
|
+
> Action 时,CodeYear 会自动使用带版本号的文件名并同步改 README,避免主页显示旧图;
|
|
339
|
+
> 手动提交时则需要自己重命名文件或加查询参数。
|
|
340
|
+
|
|
341
|
+
### 自动更新到 Profile 仓库
|
|
342
|
+
|
|
343
|
+
如果本地已经有 Profile 仓库的 clone:
|
|
344
|
+
|
|
345
|
+
```bash
|
|
346
|
+
# 私有项目:扫描本地代码,只写入 Profile 仓库(不联网)
|
|
347
|
+
codeyear scan ~/code --year 2026 --profile-repo ~/Qiongkura
|
|
348
|
+
|
|
349
|
+
# 确认后再提交并推送(联网)
|
|
350
|
+
codeyear scan ~/code --year 2026 --profile-repo ~/Qiongkura --push-profile
|
|
351
|
+
|
|
352
|
+
# 跨年定时任务:当年还没有提交时沿用上一年的卡片
|
|
353
|
+
codeyear scan ~/code --year 2026 --profile-repo ~/Qiongkura --push-profile --fallback-previous
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
只有公开数据也可以直接更新 Profile:
|
|
357
|
+
|
|
358
|
+
```bash
|
|
359
|
+
codeyear github Qiongkura --year 2026 --card-only \
|
|
360
|
+
--profile-repo ~/Qiongkura --push-profile
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
`--profile-repo` 要是本地 clone。默认只改本地文件;加 `--push-profile` 才会 commit/push,
|
|
364
|
+
且只包含卡片 SVG 和 Profile README,报告和 JSON 不会上传。每次更新会写入
|
|
365
|
+
`codeyear-2026-card-vN.svg` 并重写 README,同时清掉旧版本文件;跨年时也会把 README
|
|
366
|
+
里上一年的引用替换成新一年的卡片。
|
|
367
|
+
|
|
368
|
+
私有仓库要定时更新,可以用 Windows 任务计划、cron 或 self-hosted runner:
|
|
369
|
+
[定时更新私有项目卡片](docs/schedule.md)。
|
|
370
|
+
|
|
371
|
+
<picture>
|
|
372
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/sample-card-dark.svg">
|
|
373
|
+
<img src="docs/sample-card.svg" width="640" alt="CodeYear GitHub 主页卡片示例">
|
|
374
|
+
</picture>
|
|
375
|
+
|
|
376
|
+
## 只统计你自己的提交
|
|
377
|
+
|
|
378
|
+
- 自动读取全局 `git config user.name` / `user.email`,只保留你作为作者的提交。
|
|
379
|
+
- 想统计所有人:加 `--all-authors`。
|
|
380
|
+
- 想指定作者:加 `--author "you@example.com"`。
|
|
381
|
+
- 同一项目的副本(相同 `remote` 或相同首个 commit)只保留提交最多的一份。
|
|
382
|
+
- 「累计提交」与「最早提交」是仓库口径:按去重后的全部本地仓库统计,不按作者过滤;
|
|
383
|
+
年度提交数仍只统计你本人。
|
|
384
|
+
- 提交用了别的邮箱/名字时可能被过滤,可用 `--author` 或 `--all-authors` 覆盖。
|
|
385
|
+
- 保留旧邮箱/旧名字:`--alias "old@example.com"`,可重复;这些提交仍算你本人。
|
|
386
|
+
- 仓库里有 `.mailmap` 时会自动使用,把旧邮箱/名字映射到当前身份;不想用加 `--no-mailmap`。
|
|
387
|
+
- 默认只看当前分支;加 `--all-branches` 会统计所有本地分支/tag 的提交(合并提交仍不计入)。
|
|
388
|
+
GUI 里对应「旧邮箱/名字」输入框,多个用逗号分隔。
|
|
389
|
+
|
|
390
|
+
## 常用参数
|
|
391
|
+
|
|
392
|
+
| 参数 | 说明 |
|
|
393
|
+
| --- | --- |
|
|
394
|
+
| `--year 2026` | 统计年份,默认今年 |
|
|
395
|
+
| `--out ./out` | 输出目录 |
|
|
396
|
+
| `--author "you@example.com"` | 只统计匹配的 git author |
|
|
397
|
+
| `--all-authors` | 统计所有作者的提交(默认只统计你本人) |
|
|
398
|
+
| `--compare` | 同时扫描去年,生成同比数据(扫描时间翻倍) |
|
|
399
|
+
| `--fallback-previous` | 当年没有提交时回退到上一年,适合跨年定时任务 |
|
|
400
|
+
| `--alias "old@example.com"` | 额外作者邮箱/名字,可重复 |
|
|
401
|
+
| `--no-mailmap` | 忽略仓库里的 `.mailmap`(默认自动使用) |
|
|
402
|
+
| `--all-branches` | 统计所有本地分支/tag 的提交(默认只看当前分支) |
|
|
403
|
+
| `--max-depth 6` | 每个根目录向下查找仓库的最大文件夹层数 |
|
|
404
|
+
| `--timeout 300` | 单个仓库的扫描超时(秒) |
|
|
405
|
+
| `--jobs 4` | 并行扫描的仓库数,项目多时明显加快 |
|
|
406
|
+
| `--no-png` / `--no-html` | 跳过 PNG / HTML(可同时使用) |
|
|
407
|
+
| `--no-long` | 不生成完整版长图(默认生成) |
|
|
408
|
+
| `--no-card` | 不生成 GitHub 主页卡片 |
|
|
409
|
+
| `--profile-repo PATH` | 写入本地 Profile 仓库的卡片与 README(不联网) |
|
|
410
|
+
| `--push-profile` | 更新后提交并推送 Profile 仓库(联网) |
|
|
411
|
+
| `--open` | 生成后自动打开报告 |
|
|
412
|
+
| `--quiet` | 不打印扫描进度 |
|
|
413
|
+
|
|
414
|
+
示例:
|
|
415
|
+
|
|
416
|
+
```bash
|
|
417
|
+
# 只统计某个仓库
|
|
418
|
+
codeyear scan . --year 2026
|
|
419
|
+
|
|
420
|
+
# 多仓库 + 指定作者
|
|
421
|
+
codeyear scan D:\code --year 2026 --author "you@example.com"
|
|
422
|
+
|
|
423
|
+
# 包含团队里其他人的提交
|
|
424
|
+
codeyear scan D:\code --year 2026 --all-authors
|
|
425
|
+
|
|
426
|
+
# 多个根目录
|
|
427
|
+
codeyear scan D:\work E:\oss --year 2026
|
|
428
|
+
|
|
429
|
+
# 和去年对比
|
|
430
|
+
codeyear scan D:\code --year 2026 --compare
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
## 配置文件(可选)
|
|
434
|
+
|
|
435
|
+
常用参数可以写进 `~/.codeyear.json`(或用 `CODEYEAR_CONFIG` 指定路径):
|
|
436
|
+
|
|
437
|
+
```json
|
|
438
|
+
{
|
|
439
|
+
"roots": ["D:/code"],
|
|
440
|
+
"year": 2026,
|
|
441
|
+
"aliases": ["old@example.com"],
|
|
442
|
+
"compare": true,
|
|
443
|
+
"all_branches": true,
|
|
444
|
+
"jobs": 4,
|
|
445
|
+
"out": "codeyear-output"
|
|
446
|
+
}
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
支持 `roots / year / out / author / all_authors / aliases / compare /
|
|
450
|
+
fallback_previous / all_branches / no_mailmap / jobs / max_depth / timeout /
|
|
451
|
+
theme / max_commits / open`。命令行显式参数优先于配置文件;文件不存在或字段
|
|
452
|
+
类型不对时会自动忽略。
|
|
453
|
+
|
|
454
|
+
## 隐私
|
|
455
|
+
|
|
456
|
+
- 默认 `scan` 模式所有统计都在本地完成,**没有任何网络请求**。
|
|
457
|
+
- `github` 公开模式、`serve` 在线服务和 `--push-profile` 是可选联网功能;它们只读取公开 GitHub 数据或推送卡片,不会上传本地代码。
|
|
458
|
+
- 本地模式只读 `git log`、`git tag`、仓库根目录 README 的第一行和 `git remote`;不读取其它工作区文件。
|
|
459
|
+
- 输出文件默认忽略在 `.gitignore` 里。
|
|
460
|
+
- 本地报告页脚标注 `LOCAL ONLY · 数据未上传`;公开模式报告会标注公开数据来源。
|
|
461
|
+
- 遇到 git 的 `dubious ownership`(常见于拷贝来的仓库),只对当前仓库做一次
|
|
462
|
+
`safe.directory` 重试,不会改你的全局 git 配置。
|
|
463
|
+
|
|
464
|
+
## 已知限制
|
|
465
|
+
|
|
466
|
+
- 只统计 `--no-merges` 的提交;合并提交本身不计入。
|
|
467
|
+
- 使用 author date(`%ad`),跨时区协作时以提交者本地时间为准。
|
|
468
|
+
- 二进制、图片、锁文件和构建产物不参与语言/文件统计。
|
|
469
|
+
- 同一个 commit 出现在多个仓库时只计一次。
|
|
470
|
+
- “自有代码”按非空行统计,已排除第三方库、生成工程与模型目录;不同项目的口径
|
|
471
|
+
在报告「关于本报告」里也会写明。
|
|
472
|
+
|
|
473
|
+
## 工作原理
|
|
474
|
+
|
|
475
|
+
对每个仓库执行一次:
|
|
476
|
+
|
|
477
|
+
```text
|
|
478
|
+
git log --since=2026-01-01 --until=2027-01-01 \
|
|
479
|
+
--pretty=format:%H%x1f%ad%x1f%aE%x1f%aN%x1f%s \
|
|
480
|
+
--numstat --no-renames --no-merges
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
然后:
|
|
484
|
+
|
|
485
|
+
1. 按作者身份过滤,只保留你本人的提交;
|
|
486
|
+
2. 按 commit hash 去重,按项目血统合并副本;
|
|
487
|
+
3. 按天、小时、星期、季度、语言、文件聚合;
|
|
488
|
+
4. 生成纸面报告与海报。
|
|
489
|
+
|
|
490
|
+
语言根据扩展名映射;锁文件、构建产物、图片和二进制会被过滤掉,
|
|
491
|
+
避免 `package-lock.json` 抢走「最常改的文件」。
|
|
492
|
+
|
|
493
|
+
## 路线图
|
|
494
|
+
|
|
495
|
+
- [x] 纸面档案风格 HTML 报告 + 动效
|
|
496
|
+
- [x] 只统计本人提交(`--all-authors` 可关闭)
|
|
497
|
+
- [x] 项目副本按血统合并
|
|
498
|
+
- [x] 年度之最 / 7×24 / 编码会话 / 季度语言 / 仓库墓园
|
|
499
|
+
- [x] PNG 海报重绘为纸面主题
|
|
500
|
+
- [x] 同比去年(封面摘要 + 数据分析面板)
|
|
501
|
+
- [x] 文件级重构榜(被删最多的文件)
|
|
502
|
+
- [x] PyInstaller 打包 exe / 桌面壳
|
|
503
|
+
- [x] English README
|
|
504
|
+
- [x] 英文 HTML 报告
|
|
505
|
+
- [x] 可选同步 GitHub Profile(仅本地 / 提交推送)
|
|
506
|
+
- [x] 每日自动更新 GitHub 主页卡片(GitHub Action)
|
|
507
|
+
- [x] 交互式向导(多目录 / 仓库数量 / 进度条 / 输出位置)
|
|
508
|
+
- [x] 桌面 GUI(Tkinter,可双击)
|
|
509
|
+
- [x] GitHub 公开数据模式(输入用户名即可生成)
|
|
510
|
+
- [x] 在线卡片服务(Render / Docker / Cloudflare Tunnel)
|
|
511
|
+
- [x] 卡片主题(paper / mono / forest / ocean)与报告内交互预览/下载
|
|
512
|
+
- [x] 过去 365 天滚动统计(`--rolling`)与排除指定仓库(`--exclude`)
|
|
513
|
+
- [x] 软件内自动检测新版与一键更新(`codeyear update` / GUI)
|
|
514
|
+
- [x] 仓库搜索与打印样式
|
|
515
|
+
- [x] 多目录 CLI
|
|
516
|
+
- [x] pytest 测试 + GitHub Actions CI
|
|
517
|
+
|
|
518
|
+
## 开发
|
|
519
|
+
|
|
520
|
+
```bash
|
|
521
|
+
# 本地生成一份报告
|
|
522
|
+
python -m codeyear scan I:\projects --year 2026 --out ./out
|
|
523
|
+
|
|
524
|
+
# 语法检查
|
|
525
|
+
python -m compileall -q codeyear
|
|
526
|
+
|
|
527
|
+
# 代码风格
|
|
528
|
+
ruff check codeyear tests tools
|
|
529
|
+
|
|
530
|
+
# 测试 + 覆盖率(CI 门槛 75%,UI/海报模块不计入)
|
|
531
|
+
pip install -e ".[dev]"
|
|
532
|
+
pytest -q --cov=codeyear --cov-report=term-missing
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
代码结构:
|
|
536
|
+
|
|
537
|
+
```text
|
|
538
|
+
codeyear/
|
|
539
|
+
scanner.py 找仓库 + 解析 git log + README 首行
|
|
540
|
+
stats.py 聚合统计 / 身份过滤 / 副本合并 / 指标
|
|
541
|
+
keywords.py 提交关键词提取
|
|
542
|
+
languages.py 扩展名 → 语言映射与过滤
|
|
543
|
+
html_report.py 纸面档案 HTML 报告(内联 CSS/JS)
|
|
544
|
+
report_theme.py 新版报告主题 / 英文版
|
|
545
|
+
card.py GitHub 主页卡片
|
|
546
|
+
poster.py PNG 海报(Pillow)
|
|
547
|
+
personas.py 代码人格
|
|
548
|
+
github_public.py 公开 GitHub 数据模式
|
|
549
|
+
runner.py 扫描 + 渲染流水线(GUI/向导共用)
|
|
550
|
+
gui.py Tkinter 桌面界面
|
|
551
|
+
wizard.py 终端交互向导
|
|
552
|
+
server.py 公开卡片 HTTP 服务
|
|
553
|
+
profile.py 本地 / 推送 Profile 卡片同步
|
|
554
|
+
cli.py 命令行
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
## License
|
|
558
|
+
|
|
559
|
+
MIT
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
codeyear/__init__.py,sha256=veS98FiNc5E-VafvacO0cXRLcFkrMjeEtRG6tle1kxc,86
|
|
2
|
+
codeyear/__main__.py,sha256=naVorla9HJUMMwWULKYS7aTdHZH71KgbAnY0tuH9ZsM,116
|
|
3
|
+
codeyear/card.py,sha256=NbM4fK9TPLrN4GcUijzWqHapPxUj3jV-GctUpWKalIc,26487
|
|
4
|
+
codeyear/cli.py,sha256=KMCnEhZ5NYaWbvs6M14ay82rtRyDDM1uRdIUzYDrqlk,20044
|
|
5
|
+
codeyear/config.py,sha256=G9KR84x59vsXbrizPp0-JVLZ45iTfzvgdOTYL-8q4IQ,3243
|
|
6
|
+
codeyear/github_public.py,sha256=-74U1BAhx0UIBS84q50HmS1GIOYZMvfhJ1KFI8ELfaU,19886
|
|
7
|
+
codeyear/gui.py,sha256=wGYHTr55-tDTlFRvICNuc7_LGfEoUOihNmwogawbCiY,38148
|
|
8
|
+
codeyear/html_report.py,sha256=NBL8UyeArA7tHgHuVpJ-bPrEWnQk069_jXSrr4UkDzA,75164
|
|
9
|
+
codeyear/i18n.py,sha256=OBhDf4lH6hcscVt9TXkPp66SvbHX-xzFEIVgylM002o,16982
|
|
10
|
+
codeyear/keywords.py,sha256=84Dv3idVIYOIWWFZ77qr2_DO6MiZ_eeB9apU8tCPsmY,5287
|
|
11
|
+
codeyear/languages.py,sha256=YFOg-WlVRHz0O84qIBCfP1N8ygbXwPj-HiYXqU74z1E,5223
|
|
12
|
+
codeyear/personas.py,sha256=X7MyAkE3lJDVp_BsLrykXcSkfENWfMXwlg50fcAjo5w,5405
|
|
13
|
+
codeyear/poster.py,sha256=1eG1uAfSNkQgrVdr0vdTSy1UKkcdx4j6CSb1nZ1eUG4,40079
|
|
14
|
+
codeyear/profile.py,sha256=aA58vjVgqAtayigKrG2y70YO0JpQ-Q5VenHt217rTKQ,6737
|
|
15
|
+
codeyear/report_theme.py,sha256=5uPqbsRwOBYukIznCrLLVtvluD4A1WDN9DgSTquwP2c,41801
|
|
16
|
+
codeyear/runner.py,sha256=YWuMKvjQODbTqwA7lnqZkuBkkiEiuw34hEEP0EgBVY4,9998
|
|
17
|
+
codeyear/scanner.py,sha256=rs00jgQSqf1yOT0bxNZ0IIO-MwTclD5BGuV6Tb_nFBQ,15301
|
|
18
|
+
codeyear/server.py,sha256=51haZ-t-04wV2yuvx0Tb7EfJvz8q7faUaBdgpM3VyzY,10777
|
|
19
|
+
codeyear/stats.py,sha256=EaMDlb7Bo6kKZ91RSXNvN3R5kbuHLnJNimN9kuy5LTs,26790
|
|
20
|
+
codeyear/updater.py,sha256=blzPOvWn-dHNWUpcY6TMf_Uejp66_3glSdu9uYaUO9U,8242
|
|
21
|
+
codeyear/wizard.py,sha256=hwXSl1QZxWBk2Pcxhp1D2tmdanvFq3u-677nzPgRPRU,7981
|
|
22
|
+
codeyear-0.2.14.dist-info/licenses/LICENSE,sha256=vSWUTJF997ZFtVY3IKiG5iLbst5ALn5hWnO36Oo3ceA,1078
|
|
23
|
+
codeyear-0.2.14.dist-info/METADATA,sha256=0kSW05wckgJM50B0zeu4VG8veTJZGlRjngLvgLjSf8w,25418
|
|
24
|
+
codeyear-0.2.14.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
25
|
+
codeyear-0.2.14.dist-info/entry_points.txt,sha256=BWJlyVNLAzwzI76TDVm1D5bNdx4HU4mGgVreZ8uzRbk,95
|
|
26
|
+
codeyear-0.2.14.dist-info/top_level.txt,sha256=Yl-LvB3W0UaYGNg3nGv1YEtnZIchp61SjUtuuHRo8Uk,9
|
|
27
|
+
codeyear-0.2.14.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 CodeYear contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
codeyear
|