企业官网建设流程全解析

• 后端
• 数据分析
• 数据可视化
• 金融科技

导读

本文以仓库中的 docs/git-push-tag.md 为核心，系统讲解 PythonStock（stock）项目在版本发布时如何创建 Git Tag 并推送到远程仓库。读完本文，你将掌握带注释 Tag 与轻量 Tag 的区别、git tag与git push origin --tags的完整用法、Tag 的验证与管理，以及该项目在 Docker 镜像与更新日志中沉淀下来的版本号管理惯例。

1. 文档定位：项目发布流程的最小操作手册

在 PythonStock 仓库中，docs/目录存放项目设计与运维相关的说明文档，其中 git-push-tag.md 承担的是"版本发布操作手册"的角色，全文浓缩为一个动作闭环：

## 创建 tag 并发布到 github 上 git tag -a v2.0 -m "v2.0" git push origin --tags

短短两行命令，对应了版本发布的两个关键阶段：本地打 Tag与推送 Tag 到远程。它虽然简短，却与该项目的实际发布节奏一一对应——README 更新日志中记载了"发布一个 2.0 的版本 - 2021-10-11"（见 README.md），说明v2.0正是项目历史上真实使用过的版本号。

2. 创建 Tag：git tag -a v2.0 -m "v2.0"

2.1 带注释 Tag（Annotated Tag）

文档给出的第一条命令：

git tag -a v2.0 -m "v2.0"

其中各参数含义如下：

• -a（--annotate）：创建带注释的 Tag。它会为 Tag 生成一个完整的 Tag 对象，记录打 Tag 者、打 Tag 时间与注释信息，与 Git 提交对象结构一致，可被签名、可被引用。
• v2.0：Tag 名称。项目遵循语义化版本风格，即v+ 主版本号，例如v2.0。
• -m "v2.0"：Tag 的注释信息，相当于一次"发布说明"。示例中注释与 Tag 同名，实际使用中建议写清该版本的变更要点（例如"更换数据源为 akshare"），便于日后回溯。

执行后，Git 会在HEAD所指向的当前提交上打上v2.0标签。若需要为历史提交打 Tag，可在命令末尾追加提交 ID，例如：

git tag -a v2.0 -m "v2.0" 536fcf2

2.2 与轻量 Tag（Lightweight Tag）的取舍

若省略-a与-m，则创建的是轻量 Tag：

git tag v2.0

轻量 Tag 只是一个指向提交的固定引用，不包含任何附加元数据，适合临时标记；而带注释 Tag 携带作者、时间与说明，适合对外发布的正式版本。本文档选用-a加-m的组合，正是"对外正式发布"这一使用场景下的正确姿势。

3. 推送 Tag 到远程：git push origin --tags

Tag 创建后默认只存在于本地，并不会随git push自动同步到远程。文档第二条命令负责将其发布出去：

git push origin --tags

• origin：远程仓库名称，可通过git remote -v查看当前配置。在本仓库镜像中，origin指向https://gitcode.com/gh_mirrors/st/stock.git。
• --tags：一次性推送所有本地尚未存在于远程的 Tag。适合首次发布或批量补推。

3.1 推送单个 Tag

若只想推送某一个 Tag（例如刚创建、尚未发布的v2.0），更精确的写法是：

git push origin v2.0

推送成功后，远程仓库的 Releases/Tags 页面即可看到该版本。后续从别处检出时，执行git fetch --tags即可拉取全部远程 Tag。

4. 验证与管理 Tag

4.1 查看与验证

发布前后可用以下命令核对状态：

# 列出所有本地 Tag git tag -l # 查看指定 Tag 指向的提交及注释详情 git show v2.0 # 验证远程是否存在该 Tag git ls-remote --tags origin

git show v2.0会展示 Tag 对象本身（含注释）及其指向的提交信息，是验证发布结果最直接的途径。

4.2 修正与删除

若发现 Tag 打错位置，可删除并重新创建：

# 删除本地 Tag git tag -d v2.0 # 删除远程 Tag（谨慎使用，发布后的版本不建议回退） git push origin --delete v2.0

需要强调的是：Tag 一经推送，即为对外承诺的版本号，在多人协作或对外发布场景下应尽量避免删除或改名，否则会造成版本引用失效。

5. 项目中版本号的实践惯例

围绕v2.0这一 Tag，仓库中还沉淀了一整套版本管理惯例，可作为发布时的参照：

5.1 更新日志与版本对齐

README.md 的"更新日志"一节按编号记录了每次版本动作，例如第 15 条"发布一个 2.0 的版本 - 2021-10-11"，描述了 2.0 的核心变更：在基础镜像pythonstock/pythonstock:base-2021-09之上引入 akshare 1.1.9 替换 tushare 数据源、删除未使用的 ta-lib 与 jupyter 以缩小镜像体积。建议发布流程为：先更新 README 更新日志，再按 git-push-tag.md 创建 Tag 并推送，使版本号、镜像与文档三者保持一致。

5.2 Docker 镜像 Tag 的并行管理

项目的发布不仅涉及 Git Tag，还涉及 Docker 镜像 Tag，二者命名风格呼应：

• 顶层 build.sh 将构建产物固定为pythonstock/pythonstock:latest，对应日常滚动更新；
• docker/build.sh 使用NOW_MONTH=$(date "+%Y-%m")生成按月命名的基础镜像 Tag（如base-2021-09、base-2022-01），Dockerfile 中即通过FROM pythonstock/pythonstock:base-2022-01引用此类基础镜像；
• docker-compose.yml 中image: pythonstock/pythonstock:latest指定运行时镜像。

因此，一个完整的"2.0 发布"通常包含三件事：Git Tagv2.0（源码版本）、基础镜像 Tag（环境依赖基线）、latest滚动镜像（线上运行版本）。

5.3 远程仓库现状说明

根据 README.md 开头说明，该项目后续更新已迁移至新地址，GitHub 原仓库进入存档状态；本仓库镜像的origin配置为 gitcode 镜像地址。因此在执行git push origin --tags前，务必先通过git remote -v确认origin指向目标仓库，避免 Tag 被推送到非预期的远程。

6. 发布操作速查

将本文全部要点收敛为一份可直接照做的发布清单：

7. 结语

docs/git-push-tag.md 以最小篇幅给出了 PythonStock 版本发布的核心操作：本地创建带注释 Tag，再推送至远程。在真实项目中，这套命令与 README 更新日志、Docker 镜像 Tag 共同构成了完整的发布链路——Git Tag 锚定源码版本，基础镜像 Tag 锚定运行环境，三者同步更新，才能保证"发布一个 2.0 版本"从命令到产物的全流程闭环。

• 后端
• 数据分析
• 数据可视化
• 金融科技