【Git 学习笔记】第五章 在 Git 仓库存入附加信息（下）

5.3 从远程库读取 Git 笔记

由于 git 笔记并非 git 的默认项，因此同步远程库的笔记，或者推送本地笔记到远程库与之前的操作不太一样。

本节将以本地 chapter5 为远程库，演示 git 笔记从远程库读取的操作流程。

# Prepare locat remote repo 
# (you must follow the operations demonstrated from previous sections in this chapter)
$ git clone clone https://github.com/eclipse-jgit/jgit.git chapter5
$ cd chapter5
# checkout the master branch
$ git checkout master
# Checkout stable-3.1 for use
$ git branch stable-3.1 origin/stable-3.1
$ git branch
* master
  myNotes
  notesMessage
  notesReferences
  stable-3.1
# clone repo from chapter5 locally
$ cd ..
$ git clone ./chapter5 shareNotes
$ cd shareNotes
# Check remote branches
$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/myNotes
  remotes/origin/notesMessage
  remotes/origin/notesReferences
  remotes/origin/stable-3.1

注意：之所以要在 chapter5 签出 master 分支和 stable-3.1 分支，是因为本节示例要将 chapter5 仓库作为远程库，而 git clone 命令默认会将 refs/heads/* 下的所有分支克隆出去，作为目标仓库的远程分支。

先看看克隆出的仓库直接查看 git 笔记的情形：

# within shareNotes repo
$ git log -1 b4f07df --notes=alsoCherryPick
warning: notes ref refs/notes/alsoCherrypick is invalid
commit b4f07df357fccdff891df2a4fa5c5bd9e83b4a4a
Author: Matthias Sohn <matthias.sohn@sap.com>
... (more output omitted)

根据第一句的提示，shareNotes 库中的自定义笔记类型 alsoCherrypick 无效，然而它在 chapter5 库中确实存在。这时需要新增一条 fetch 规则，先来看看默认的设置：

$ git config --get remote.origin.fetch
+refs/heads/*:refs/remotes/origin/*

结果显示，chapter5 的 refs/heads/* 被 fetch 到了 shareNotes 库的 refs/remotes/origin/*。新增如下 notes 配置项：

$ git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'
# Check the config
$ git config --get-all  remote.origin.fetch
+refs/heads/*:refs/remotes/origin/*
+refs/notes/*:refs/notes/*
# then fetch
$ git fetch
From C:/Users/ad/Desktop/./chapter5
 * [new ref]             refs/notes/alsoCherrypick -> refs/notes/alsoCherrypick
 * [new ref]             refs/notes/commits        -> refs/notes/commits
 * [new ref]             refs/notes/defect         -> refs/notes/defect
# retry
$ git log -1 b4f07df --notes=alsoCherryPick --oneline
b4f07df35 Prepare re-signing pgm's ueberjar to avoid SecurityException
Notes (alsoCherrypick):
    570bba5

这样，通过新增 fetch 规则，就能从远程库拉取 git 笔记数据。

小结

1. fetch 默认将 refs/heads/* 拉取到本地远程跟踪分支 refs/remotes/origin/*
2. 要想 fetch 远程 notes，需要创建 fetch 规则，将远程 refs/notes/* 拉取到本地的 refs/notes/*；
3. 配置具有多个值的 git 配置项时，需要加 --add，否则不会追加，而是覆盖；同样的，查看所有配置的值，需要加 --get-all 参数，否则只显示一个。

5.4 推送 Git 笔记到远程库

与获取远程笔记类似，推送笔记到远程库也需要手动指定：(git push origin refs/notes/*)

# Add a new local git note in category of verified
$ git notes --ref verified add -m 'Verified by john.doe@example.com' 871ee53b52a
# Check note locally
$ git log -1 871ee53b52a --notes=verified --oneline
871ee53b5 Reset internal state canonical length in WorkingTreeIterator when moving
Notes (verified):
    Verified by john.doe@example.com
# try default push
$ git push
# specify notes reference by hand
$ git push origin refs/notes/*
# Check in remote repo
$ cd ../chapter5
$ git log --notes=verified -1 871ee53b52a --oneline
871ee53b5 Reset internal state canonical length in WorkingTreeIterator when moving
Notes (verified):
    Verified by john.doe@example.com

小结：由于 git notes 不是 git 的常规分支，与远程库的数据交互要繁琐些。一个推荐做法是搭建一套工具来添加 git 笔记，这样只用新增一个处理笔记的服务器即可。

同时，作为一个有效补充，笔记内容也可以关联 Jenkins 构建工具或测试套件，尤其是后期需要追加笔记内容时用处很大，可以直观查看哪些版本执行了哪些测试。

5.5 为 commit 版本添加标签

项目发布时，就会用到标签（git tags）。标签是对仓库中的软件发布版本的描述，分为 轻量级标签 和 带注解标签 两种。轻量级标签就是一个具名引用，如 refs/tags/version123。该标签指向一个目标 commit；而一个本地签出的分支的引用，是 refs/heads/version123。

标签和分支的区别在于，分支的引用会随工作的推进不断前进，而标签永远指向创建时指向的目标 commit 版本。

本节示例，将基于 chapter5 的 stable-2.3 分支，同时要在落后 stable-2.3 10 个版本的位置添加标签：

# repo init
$ git checkout stable-2.3 
# list the latest 11 commits without merged commits
$ git log -11 --no-merges --oneline
# find the target commit (ea060dd)
$ git tag 'v2.3.0.201302061315rc1' ea060dd
# query a tag by wildcards
$ git tag -l "v2.3.0.2*"
# show the detail
$ git show v2.3.0.201302061315rc1
# It should behave the same as using SHA-1
$ git show ea060dd
# Create an annotated tag with --annotate
# Here -m means --message, which would bring up an default editor view when left out
$ git tag --annotate -m "Release Maturity rate 97%" 'v2.3.0.201409022257rc2' 1c4ee41
# Check the new tag
$ git show 'v2.3.0.201409022257rc2'

Git 标签可以提供很多关键信息，可以作为代码库的正式发布版本使用，因此其标签内容及发布需要引起高度重视。

这里有个细节需要特别注意：如果将发布到线上的某个 tag 版本，重新指向另一个 commit 位置，那么对于已经拉取该版本到本地的开发人员而言，fetch 操作不会同步 tag 到最新的指向上，除非在本地删除该标签后重新拉取。

验证如下：

# remove the tag
$ git tag -d v1.3.0.201202121842-rc4
# then update it to point to HEAD
$ git tag -a -m "Local created tag" v1.3.0.201202121842-rc4
# fetch from remote
$ git fetch
# verify tag (still the local one)
$ git show v1.3.0.201202121842-rc4
# then delete a tag
$ git tag -d v1.3.0.201202121842-rc4
# fetch again
$ git fetch
# Check again
$ git show v1.3.0.201202121842-rc4

这样才能同步到新标签。这也给我们提了个醒：不要擅自改动发布到线上的标签版本。否则提前同步过这一版本的开发者无法及时获知版本更新，除非手动删除重新同步或重新克隆远程库。

章节综述

本章学习了添加 tag 标签和 note 笔记的各种方法。提交一个版本前，应提供该版本的关键信息，写明这个版本做了什么，以及为什么要这样做：

• 如果正在解决一个 bug，应该列出 bug ID；
• 如果运用了特殊的方法来解决问题，应该描述清楚这么做的缘由

这样在回顾 commit 版本时，就能了解到当时为何采取不同方案的基本情况。