如远程有分支branch_a，克隆下来后使用git branch -av命令查看所有分支没有显示该分支，该如何解决？

git remote set-branches origin 'branch_a'
git fetch -v

本文翻译自官方教程Git - MyFirstContribution，原文包含开发到提交的整个周期。但是想要提交的人应该都已经开发完代码了，所以本文用自己的实际例子重新写了一遍，省去了开发代码等流程，重点介绍如何使用 git send-email。

环境准备

下载 OpenSBI 仓库

git clone https://github.com/riscv-software-src/opensbi.git
cd opensbi

安装依赖

要从源代码构建 OpenSBI：

make

注：OpenSBI 的构建是可并行的。上面的命令可以添加-j#参数，如-j12。

确认要解决的问题

在本文档中，我们将模拟提交一个简单的 Patch，.gitignore文件可以过滤不必要的文件，现在使用 VSCode 的用户越来越多，使用 VSCode 开发时常常会生成.vscode目录，但是这些文件不该被推送至远程，原仓库中的.gitignore文件中没有过滤该文件，我们给他加上。

为了能够模拟一次发送多个commit的场景，我们将再添加一个.so用来过滤编译过程中生成的.so文件。

建立工作空间

让我们先建立一个开发分支来进行我们的修改。

git checkout -b update_gitignore origin/master

我们将在这里做一些提交，以演示如何将一个带有多个补丁的主题同时送审。

实现代码

过滤 .vscode

打开文件.gitignore，为该文件添加/.vscode/：

# Object files
*.o
*.a
*.dep

#Build & install directories
build/
install/

# Development friendly files
tags
cscope*

/.vscode/

为以上修改做一次提交：

$ git status
On branch update_gitignore
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   .gitignore
$ git add .gitignore
$ git commit -s

执行以上命令后将会弹出编辑框用来编写提交信息。主题行要少于 50 个字符，然后是一个空行（必须），然后是您的提交消息的正文。请记住要明确并提供更改的原因（理由），特别是如果无法从您的差异中轻松理解你的提交内容时。编辑提交消息时，不要删除上面 Signed-off-by 添加的 trailer。（由上面命令-s参数生成）。

其他规范请详细查阅目标社区的提交规范，如OpenSBI要求主题行需要以 lib:， platform:, firmware:, docs:, utils: 或者 top:为前缀，修改.gitignore属于top范畴，所以我们需要将其加在主题行上。

top: filter .vscode folder

Filter the workspace's '.vscode' directory by adding '/.vscode/' to the.gitignore file.

Signed-off-by: Dominic Zhang <Dominic Zhang@gmail.com>

继续用 git show 检查您的新提交。尤其不要出现不需要在本次提交的内容。通常使用不同的 IDE 都可能会无意间生成一些配置文件等，请注意将其剔除。

commit 5dc340c29979d4c5d8c4d5a6e881348239714434 (HEAD -> update_gitignore)
Author: Dominic Zhang <Dominic Zhang@gmail.com>
Date:   Fri Nov 18 16:06:21 2022 +0800

    top: filter .vscode folder
    
    Filter the workspace's '.vscode' directory by adding '/.vscode/' to the.gitignore file.
    
    Signed-off-by: Dominic Zhang <Dominic Zhang@gmail.com>

diff --git a/.gitignore b/.gitignore
index 95692bb..90cf552 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,5 @@ install/
 # Development friendly files
 tags
 cscope*
+
+/.vscode/

过滤 .cache

与上一节步骤类似，我们在.gitignore文件中再添加一个/.cache/字段用来过滤.cache文件夹。

# Object files
*.o
*.a
*.dep

#Build & install directories
build/
install/

# Development friendly files
tags
cscope*

/.vscode/
/.cache/

添加完我们就即使保存工作进度，新生成一个commit。

git add .gitignore
git commit -s

top: filter .cache folder

Filter the workspace's '.cache' directory by adding '/.cache/' to the.gitignore file.

Signed-off-by: Dominic Zhang <Dominic Zhang@gmail.com>

以上我们就已经准备好所有的代码了，在大部分场景下可能修改的是.c或者.h等源文件，这就需要我们能够使代码编译、运行并且测试通过后再提交。

这里为了演示提交流程，就没有涉及这些步骤。接下来我们就要准备提交的补丁文件了。

准备提交补丁

OpenSBI 项目是通过电子邮件发送补丁来进行代码审查的，当补丁准备好并得到社区认可后，维护者就会应用（Apply）这些补丁。OpenSBI 项目不接受来自 Pull Request 的贡献，而且通过电子邮件发送的补丁需要以指定的方式进行审核。

在研究如何将你的提交转化为电子邮件的补丁之前，让我们先分析一下最终的结果，即补丁系列（Patch Series）是什么样子。下面是 OpenSBI 邮件列表存档的网页界面上的补丁系列的摘要视图的一个例子。

我们可以注意几点：

• 每次提交都是以单独的邮件形式发送，提交信息的标题为主题，前缀为[PATCH i/n]，代表n个提交系列中的第 i 个提交。
• 每个补丁都是作为对cover letter的回复，cover letter的前缀为[PATCH 0/n]，序号为 0 的标题。
• 补丁系列的后续迭代被标记为 PATCH v2、PATCH v3，等等，以代替 PATCH。例如，[PATCH v2 1/3]将是第二次迭代中三个补丁的第一个补丁。每次迭代都有一个新的cover letter（如上面的[PATCH v2 0/3]），本身就是对前一次迭代的cover letter的回复（下面会有更多介绍）。

注：单一补丁的主题是以[PATCH]、[PATCH v2]等发送的，没有 i/n 编号。如上图中的第四个 Patch，就是一个单一补丁。

什么是 cover letter

除了给每个补丁发一封邮件外，OpenSBI 社区还希望你的补丁能附带一封 cover letter。这是修改提交的一个重要组成部分，因为它概括了你想要做什么，以及为什么要这样做，比仅仅看你的补丁更明显。

你的 cover letter 的标题应该是能简洁地涵盖你整个主题分支的目的。就像我们的提交信息标题一样。下面是我们的系列标题。

Update gitignore ---

cover letter 的正文是用来给评审员提供额外的背景。一定要解释任何你的补丁自己没有说清楚的东西，但要记住，由于 cover letter 没有记录在提交历史中，任何可能对未来版本库历史的读者有用的东西也应该在你的提交信息中出现。

下文我们将介绍如何生成 cover letter 以及如何填写 cover letter。

用 git send-email 发送补丁

前提条件 - 设置 git send-email

对 send-email 的配置会根据你的操作系统和电子邮件供应商而有所不同，配置可以参考文档如何使用 git-send-mail 给开源社区提交 Patch - 如云泊。

准备初始补丁集

在准备邮件本身之前，你需要准备补丁。

git format-patch --cover-letter -o update_gitignore/ --base=auto  update_gitignore@{u}..update_gitignore

• --cover-letter 选项告诉 format-patch 为你创建一个 cover letter 模板。在你准备发送之前，你将需要填写该模板。
• -o update_gitignore/ 选项告诉 format-patch 把补丁文件放到目录update_gitignore中。这样发送多个commit时就可以使用命令一次性发送，因为 git send-email 可以接收一个目录并从那里发送所有补丁。
• --base=auto 选项告诉命令记录”基本提交”，接收者将在此基础上应用补丁系列。自动值将使 format-patch 自动计算基本提交，即远程跟踪分支的最新提交和指定修订范围的合并基数。
• update_gitignore@{u}..update_gitignore 选项告诉 format-patch 为你在 update_gitignore 分支上创建的提交生成补丁，因为它是从上游分叉出来的。@{u}的意思就是从分叉开始到最新的提交。

执行完该命令我们看看生成了哪些内容。

$ git status
On branch update_gitignore
Your branch is ahead of 'origin/master' by 2 commits.
  (use "git push" to publish your local commits)

Untracked files:
  (use "git add <file>..." to include in what will be committed)

        update_gitignore/

$ ls update_gitignore 
0000-cover-letter.patch  0001-top-filter-.vscode-folder.patch  0002-top-filter-.cache-folder.patch

该命令将为每次提交制作一个补丁文件。运行后，您可以用您喜欢的文本编辑器看一下每个补丁，确保一切正常。可以看到创建了一个-o参数中的update_gitignore文件夹，该文件夹下有三个文件，分别是 cover letter 和上文我们做的两次提交对应的补丁文件。

分别打开他们，结果如下：

From 30614e5469be4a2f930cca570836627a4e91f1d1 Mon Sep 17 00:00:00 2001
From: Dominic Zhang <Dominic Zhang@gmail.com>
Date: Fri, 18 Nov 2022 16:41:32 +0800
Subject: [PATCH 0/2] *** SUBJECT HERE ***

*** BLURB HERE ***

Dominic Zhang (2):
  top: filter .vscode folder
  top: filter .cache folder

 .gitignore | 3 +++
 1 file changed, 3 insertions(+)


base-commit: 880685586dcee950d209088a461443449a1693ce
-- 
2.17.1

From 5dc340c29979d4c5d8c4d5a6e881348239714434 Mon Sep 17 00:00:00 2001
From: Dominic Zhang <Dominic Zhang@gmail.com>
Date: Fri, 18 Nov 2022 16:06:21 +0800
Subject: [PATCH 1/2] top: filter .vscode folder

Filter the workspace's '.vscode' directory by adding '/.vscode/' to the.gitignore file.

Signed-off-by: Dominic Zhang <Dominic Zhang@gmail.com>
---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 95692bb..90cf552 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,5 @@ install/
 # Development friendly files
 tags
 cscope*
+
+/.vscode/
\ No newline at end of file
-- 
2.17.1

From 30614e5469be4a2f930cca570836627a4e91f1d1 Mon Sep 17 00:00:00 2001
From: Dominic Zhang <Dominic Zhang@gmail.com>
Date: Fri, 18 Nov 2022 16:20:37 +0800
Subject: [PATCH 2/2] top: filter .cache folder

Filter the workspace's '.cache' directory by adding '/.cache/' to the.gitignore file.

Signed-off-by: Dominic Zhang <Dominic Zhang@gmail.com>
---
 .gitignore | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.gitignore b/.gitignore
index 90cf552..bf9d716 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,4 +11,5 @@ install/
 tags
 cscope*
 
-/.vscode/
\ No newline at end of file
+/.vscode/
+/.cache/
\ No newline at end of file
-- 
2.17.1

注：另外，你也可以使用 --rfc 参数，在你的补丁主题前加上[RFC PATCH]，而不是[PATCH]。RFC 是”请求评论”的意思，表示虽然你的代码还没有准备好提交，但你想开始代码审查过程。你也可能在列表中看到标有”WIP”的补丁，这意味着他们还没有完成，但希望审查者能看看他们目前的成果。你可以用--subject-prefix=WIP来添加这个标志。

检查并确保你的补丁和 cover letter 模板存在于你指定的目录中，这就完成所有准备了。

准备邮件

由于你在调用 format-patch 时使用了--cover-letter，你已经准备好了一个 cover letter 模板。在你喜欢的编辑器中打开它。

你应该看到已经有一些标题存在。检查你的From:标题是否正确。然后修改你的Subject:。

确保保留[PATCH 0/X]的部分；这是向 Git 社区表明这封邮件是一个补丁系列的开始，许多审查者会根据这种类型的标记过滤他们的邮件。

接下来，你必须填写你的 cover letter 的正文。同样，关于应包括哪些内容，见上文。

最后，信中会包括用于生成补丁的 Git 的版本。你可以不用管这个字符串。

完善后的 cover letter 如下：

From 30614e5469be4a2f930cca570836627a4e91f1d1 Mon Sep 17 00:00:00 2001
From: Dominic Zhang <Dominic Zhang@gmail.com>
Date: Fri, 18 Nov 2022 16:41:32 +0800
Subject: [PATCH 0/2] Update gitignore

vscode is a very popular IDE, and it often needs to generate a.vscode. cache directory to hold workspace configuration files that should not be committed to a remote repository, so we made some modifications to the gitignore file to filter such directories.

Dominic Zhang (2):
  top: filter .vscode folder
  top: filter .cache folder

 .gitignore | 3 +++
 1 file changed, 3 insertions(+)


base-commit: 880685586dcee950d209088a461443449a1693ce
-- 
2.17.1

发送邮件

到这里，你应该有一个目录 update_gitignore/，里面包含你的补丁和一封 cover letter。是时候把它发出去了！你可以像这样发送。

git send-email --to=target@example.com update_gitignore/*.patch

注：请查看 git help send-email 中的一些其他选项，你可能会发现这些选项很有价值，比如改变回复地址或添加更多的抄送地址或密送地址。

注：当你发送一个真正的补丁时，它将被发送到 opensbi@lists.infradead.org - 但请不要把你的补丁集从教程中发送到真正的邮件列表中！现在你可以把它发送给你自己，以确保你了解它的形式。

在你运行上面的命令后，你会为每个即将发出的补丁看到一个交互提示。这给了你最后一次机会来编辑或放弃发送一些东西（但还是那句话，不要用这种方式编辑代码）。一旦你在这些提示下按下 y 或 a，你的邮件就会被发送出去！Congratulation!

发送补丁的更新版本

本节将重点介绍如何发送你的补丁集的 v2 版。我们将在 v2 版中重新使用我们的 update_gitignore 分支。在我们做任何改动之前，我们先新建一个名为update_gitignore-v1的分支，这个分支是我们没有做新的改动的分支。这样在后面我们就可以方便的进行对比差异。

git checkout update_gitignore
git branch update_gitignore-v1

在更新补丁时，我们可能会遇到两种情况，一种是社区的意见只让修改最新的一个提交，一种是修改历史记录中的 commit。我们分别来处理这两种情况。

如何修改最新的提交

比如只需要修改top: filter .cache folder这个 commit。因为它在我们的修改中是最新的 commit，所以我们可以直接对代码修改。比如我们做一个简单的修改，给修改的内容/.cache加个注释。

# Object files
*.o
*.a
*.dep

#Build & install directories
build/
install/

# Development friendly files
tags
cscope*

/.vscode/

# Cache file
/.cache/

git add .gitignore
git commit --amend

注意！我们不需要生成新的commit，所以使用 --amend参数修改最新的commit message即可。执行这条命令会弹出编辑窗口，因为修改内容已经很明确，我们不需要在commit message里再做额外说明，直接保存退出即可。如果修改内容比较大，需要重新编写commit message。

以上我们就完成了一次更新。

如何修改历史记录中的提交

如果很不巧，社区要求修改的是top: filter .vscode folder这个提交的内容，那怎么办，因为它不是最新的提交，而是上一个提交，我们无法使用git commit --amend来直接对他修改，好在 Git 十分强大，不需要我们reset就可以完成这样的工作。

同样我们也做一个简单的修改，为/.vscode/也添加一个注释。首先我们需要使用到git rebase这个强大的命令。本文只介绍使用到的功能，其他功能需要大家自行摸索。

git rebase -i

这条命令会弹出编辑窗口，-i参数表示以交互式方式进行变基（rebase）操作。弹出窗口内容如下：

pick 7175772 top: filter .vscode folder
pick 52b63f3 top: filter .cache folder

# Rebase 8806855..52b63f3 onto 8806855 (2 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

窗口会显示所有未提交到远程的 commit，下面的注释也告诉了我们该如何使用。我们找到edit的行，可以看到解释为使用当前的 commit，但是在变基过程中会停下来让我们修改。这正是我们想要的。我们编辑当前的内容如下：

edit 7175772 top: filter .vscode folder
pick 52b63f3 top: filter .cache folder

表示我们需要编辑历史记录中的top: filter .vscode folder提交，但是另一个 commit 我们不做改变。保存并退出当前窗口后，会有如下提示。

Stopped at 7175772...  top: filter .vscode folder
You can amend the commit now, with

  git commit --amend 

Once you are satisfied with your changes, run

  git rebase --continue

根据提示，我们可以进行一系列修改了，修改完使用git commit --amend保存，如果一切符合自己要求了，再使用git rebase --continue完成变基操作。

我们先修改代码，可以看到代码已经回到了没有/.cache/的状态，我们添加一行注释：

# Object files
*.o
*.a
*.dep

#Build & install directories
build/
install/

# Development friendly files
tags
cscope*

# VSCode config file
/.vscode/

git add .gitignore
git commit --amend

同样弹出窗口后我们直接保存退出，如果修改幅度较大，可以进一步补充说明。然后使用以下命令继续完成变基。

git rebase --continue

此时我们可以看到我们不仅修改了历史记录中的 commit，还保证了最新的 commit 没有丢失或者更改。

准备更新版本的补丁集

 $ git format-patch -v2 --cover-letter -o update_gitignore/   master..update_gitignore-v1
update_gitignore/v2-0000-cover-letter.patch
update_gitignore/v2-0001-top-filter-.vscode-folder.patch
update_gitignore/v2-0002-top-filter-.cache-folder.patch

--range-diff master..update_gitignore-v1 参数告诉 format-patch 在 cover letter 中包括 update_gitignore-v1 和 update_gitignore 两个分支之间的差异。这有助于告诉评审人你的 v1 和 v2 补丁之间的差异。

-v2 参数告诉 format-patch 将你的补丁输出为 v2 版本。例如，你可能注意到你的 v2 版补丁都被命名为 v2-000n-my-commit-subject.patch。-v2 也会将你的补丁格式化，在前面加上[PATCH v2]，而不是[PATCH]。

运行此命令后，format-patch 会将补丁输出到 update_gitignore/ 目录，与 v1 版的补丁一起。使用一个目录可以方便在校对 v2 补丁时参考旧的 v1 补丁，但你需要注意只发送 v2 补丁。我们将使用 update_gitignore/v2-.patch这样的模式（而不是 update_gitignore/.patch，这将匹配 v1 和 v2 补丁）。

再次编辑你的 cover letter。现在是一个很好的时间来提及你的上一个版本和现在有什么不同，如果它是重要的东西。你不需要在你的第二封 cover letter 中使用完全相同的内容；重点是向审查人员解释你所做的可能不那么明显的变化。

我们就简单的写一下添加了注释。

From 30614e5469be4a2f930cca570836627a4e91f1d1 Mon Sep 17 00:00:00 2001
From: Dominic Zhang <Dominic Zhang@gmail.com>
Date: Fri, 18 Nov 2022 19:35:06 +0800
Subject: [PATCH v2 0/2] Update gitignore

Add a comment for the folder name.

Dominic Zhang (2):
  top: filter .vscode folder
  top: filter .cache folder

 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

-- 
2.17.1

发送更新版本时你需要将新版本抄送给提出建议的人，你可以在你的 cover letter 中直接添加这些抄送行，在 Subject 行上面写上这样一行。

CC: Name <name@example.com>

例如，把更新的邮件抄送给我自己：

From 30614e5469be4a2f930cca570836627a4e91f1d1 Mon Sep 17 00:00:00 2001
From: Dominic Zhang <Dominic Zhang@gmail.com>
CC: Dominic Zhang <Dominic Zhang@gmail.com>
Date: Fri, 18 Nov 2022 19:35:06 +0800
Subject: [PATCH v2 0/2] Update gitignore

Add a comment for the folder name.

Dominic Zhang (2):
  top: filter .vscode folder
  top: filter .cache folder

 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

-- 
2.17.1

现在再次发送电子邮件，注意你传入的参数。

git send-email --to target@example.com update_gitignore/v2-*.patch

恭喜你完成了一次补丁版本更新。

对于一些社区，要求更新的版本需要在同一个 thread 上进行。如下示例这样：

[PATCH 0/2] Here is what I did...
  [PATCH 1/2] Clean up and tests
  [PATCH 2/2] Implementation
  [PATCH v2 0/3] Here is a reroll
    [PATCH v2 1/3] Clean up
    [PATCH v2 2/3] New tests
    [PATCH v2 3/3] Implementation

就是更新的版本需要关联到之前的版本，而不能作为单独的一个列表。

你还需要去找到你之前的 cover letter 的 Message-Id。你可以在发送第一个补丁系列时，从 git send-email 的输出中记下它。 例如：

$ git send-email --to Dominic Zhang@gmail.com update_gitignore/v2-*.patch 

update_gitignore/v2-0000-cover-letter.patch
update_gitignore/v2-0001-top-filter-.vscode-folder.patch
update_gitignore/v2-0002-top-filter-.cache-folder.patch
(mbox) Adding cc: Dominic Zhang <Dominic Zhang@gmail.com> from line 'From: Dominic Zhang <Dominic Zhang@gmail.com>'
(mbox) Adding cc: Dominic Zhang <254758318@qq.com> from line 'CC: Dominic Zhang <254758318@qq.com>'

From: Dominic Zhang@gmail.com
To: Dominic Zhang@gmail.com
Cc: Dominic Zhang <254758318@qq.com>
Subject: [PATCH v2 0/2] Update gitignore
Date: Fri, 18 Nov 2022 19:54:54 +0800
Message-Id: <20221118115456.2242-1-Dominic Zhang@gmail.com>
X-Mailer: git-send-email 2.17.1

你也可以从社区的邮箱列表中找到 Message ID，因为 OpenSBI 不要求在同一个 thread 回复，所以没有相关信息，这里以Git 社区的邮箱列表为例。随便点击一个补丁主题，在页面中找到permalink或者raw，点击打开即可找到 Message ID 信息。

它的格式一般如下：

Message-Id: <foo.12345.author@example.com>

如果要发送更新版本，那么我们就需要找到上一版本的 Message ID。如发送的是 V3 版本，那么我们需要找到 V2 版本的 Message ID。并且在发送邮件时添加如下参数：

$ git send-email --to Dominic Zhang@gmail.com 
                 --in-reply-to="<foo.12345.author@example.com>" 
                 update_gitignore/v2-*.patch 

只有一个 Patch 的更改

在某些情况下，你的非常小的变化可能只包括一个补丁。这时，你只需要发送一封邮件。你的提交信息应该已经很有意义了，你只需要生成补丁文件就可以发送了。

git format-patch -o update_gitignore/  HEAD^

• HEAD^参数表示生成与上一个提交之间的差异。

如果参与 Linux、QEMU 或者 OpenSBI 等开源项目，不能通过在 GitHub 或者 Gitlab 平台提交pull request。而是需要将修改的代码，通过 Patch 形式提交到对应的listserv供 Maintainer 审核。那么如何创建 Patch 并发送呢？

这里以向 OpenSBI 提交一个 Patch 为例。

创建 Patch

首先将官方 Repository，Fork 到自己的 GitHub：

回到自己的主页，找到刚刚 Fork 的 Repository，将其 Clone 到本地：

修改代码与正常开发流程一直，修改完在git commit时需要加上Signed-off-by字段，因为 Merge 代码的人通常不是提交代码的人，有该字段才能证明是你修改了对应的代码。

-s参数会自动加上Signed-off-by字段：

$ git commit -s

doc:fix some typos

Signed-off-by: dominic <dominic@gmail.com>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# Date:      Tue Sep 27 21:11:41 2022 +0800
#
# On branch master
# Your branch is up to date with 'origin/master'.
#
# Changes to be committed:
#       modified:   docs/domain_support.md
#       modified:   docs/library_usage.md
#       modified:   docs/platform_requirements.md
#       modified:   docs/pmu_support.md

生成.patch文件：

$ git format-patch HEAD^
0001-doc-fix-some-typos.patch

在当前目录下会生成一个0001-doc-fix-some-typos.patch文件：

$ git status 
On branch master
Your branch is up to date with 'origin/master'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        0001-doc-fix-some-typos.patch

nothing added to commit but untracked files present (use "git add" to track)

这个文件就是我们要发送的文件，文件内容就是我们的代码修改，以及作者等信息：

$ cat 0001-doc-fix-some-typos.patch 
From d404cb82f4c4aca15dcd35855d0bc96c5b4431d5 Mon Sep 17 00:00:00 2001
From: Dunky-Z <xxxxxxxxx@qq.com>
Date: Tue, 27 Sep 2022 21:11:41 +0800
Subject: [PATCH] doc:fix some typos

Signed-off-by: dominic <dominic@gmail.com>
---
 docs/domain_support.md        |  6 +++---
 docs/library_usage.md         |  2 +-
 docs/platform_requirements.md |  2 +-
 docs/pmu_support.md           | 10 +++++-----
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/domain_support.md b/docs/domain_support.md
index 73931f1..8963b57 100644
--- a/docs/domain_support.md
+++ b/docs/domain_support.md
@@ -2,7 +2,7 @@ OpenSBI Domain Support
 ======================
...

配置 send-email

安装 git-email

通过git直接发送 Patch 需要使用git-email工具，得手动安装：

sudo apt install git-email

Windows 平台在安装 Git 时默认已安装

生成 smtp 授权码

登录QQ 邮箱 - 帐户：

开启 IMAP/SMTP 服务，并生成授权码：

根据提示发送短信：

记录下生成的授权码：

配置.gitconfig

Ubuntu 平台：~/.gitconfig Windows 平台：C:\Users\用户名\.gitconfig

[sendemail]
 smtpencryption = tls
    smtpserver = smtp.qq.com
    smtpuser = dominic_riscx@qq.com
 smtpserverport = 587
    from = dominic_riscx@qq.com
 smtppass = xxxxxx
 cc = dominic@gmail.com
 #to = opensbi@lists.infradead.org

为了方便复制，单独注释：

[sendemail]
 smtpencryption = # 加密方式，保持默认
    smtpserver =     # smtp 服务器地址，保持默认
    smtpuser =       # 邮箱地址，改为 QQ 邮箱地址，也就是用哪个邮箱发送，就填哪个
 smtpserverport = # 端口号，保持默认
    from =           # 同 smtpuser
 smtppass =       # 上文生成的 smtp 授权码
 cc =             # 抄送的邮箱地址
 #to = opensbi@lists.infradead.org 
    # 要发送的地址，这个字段我注释了，因为怕以后发邮件默认发到这个地址，这个字段可以在发送时单独填写

发送 Patch

#$ git send-email patch文件名
$ git send-email  0001-doc-fix-some-typos.patch
0001-doc-fix-some-typos.patch
# 提示往哪里发送，填写要接收的邮箱即可，我这里填写的是OpenSBI接收Patch的地址
To whom should the emails be sent (if anyone)? opensbi@lists.infradead.org

Message-ID to be used as In-Reply-To for the first email (if any)? 
# 回车，保存默认（我还不清楚这里的作用）

(mbox) Adding cc: Dunky-Z <xxxxxxxxx@qq.com> from line 'From: Dunky-Z <xxxxxxxxx@qq.com>'
(body) Adding cc: dominic <dominic@gmail.com> from line 'Signed-off-by: dominic <dominic@gmail.com>'   

From: dominic_riscx@qq.com
To: opensbi@lists.infradead.org
Cc: dominic@gmail.com,
        Dunky-Z <xxxxxxxxx@qq.com>
Subject: [PATCH] doc:fix some typos
Date: Wed, 28 Sep 2022 10:35:30 +0800
Message-Id: <20220928023530.2344-1-dominic_riscx@qq.com>
X-Mailer: git-send-email 2.34.1.windows.1
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

    The Cc list above has been expanded by additional
    addresses found in the patch commit message. By default
    send-email prompts before sending whenever this occurs.
    This behavior is controlled by the sendemail.confirm
    configuration setting.

    For additional information, run 'git send-email --help'.
    To retain the current behavior, but squelch this message,
    run 'git config --global sendemail.confirm auto'.

Send this email? ([y]es|[n]o|[e]dit|[q]uit|[a]ll): y

# y 确认发送

OK. Log says:
Server: smtp.qq.com
MAIL FROM:<dominic_riscx@qq.com>
RCPT TO:<opensbi@lists.infradead.org>
RCPT TO:<dominic@gmail.com>
RCPT TO:<xxxxxxxxx@qq.com>
From: dominic_riscx@qq.com
To: opensbi@lists.infradead.org
Cc: dominic@gmail.com,
        Dunky-Z <xxxxxxxxx@qq.com>
Subject: [PATCH] doc:fix some typos
Date: Wed, 28 Sep 2022 10:35:30 +0800
Message-Id: <20220928023530.2344-1-dominic_riscx@qq.com>
X-Mailer: git-send-email 2.34.1.windows.1
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit

Result: 250

# 发送成功

前往The opensbi Archives，找到对应的月份，点击Theread，即可找到自己发送的 Patch，每个开源社区一般都会在如何提交 PR 的文档里公开 Patch Archive 网址，这里是以 OpenSBI 的网址。

前往邮箱发送记录中也可以找到对应的 Patch 信息：

以上就是完整的提交 Patch 过程。

Git 能在特定的重要动作发生时触发自定义脚本。比如，commit之前检查commit message是否符合约定的格式，push之前检查代码格式是否正确，是否编译通过等等。Git 就提供了hooks这样的机制。

我们在哪能找到hooks呢？在初始化代码仓库git init时，Git 会自动为我们创建一个.git/hooks目录，里面存放了所有的钩子。因为.git是隐藏目录，显示隐藏目录后就可以找到hooks这个目录。

在 VSCode 里一般默认把.git目录排除显示，所以打开项目目录时不会显示该目录，我们可以收到在 VSCode 显示.git目录：打开设置界面，搜索exclude找到图中的设置，将.git目录从排除列表中移除，即可在 VSCode 中显示.git目录。

现在我们找到了hooks，该如何使用呢？ 所有默认的hooks都是以.sample为后缀，只需要移除.sample即可激活hooks。

随便打开一个hooks文件，我们可以发现，实际是hooks就是一个个shell脚本。这些脚本会在特定的动作发生时被执行。示范的这些hooks都是shell脚本，实际上只要是文件名正确的可执行脚本都可以使用，如将pre-push内容改为python, Ruby等等脚本都可以。

如何使用一个 hooks

以pre-commit这个hooks为例，来示范一下如何使用 Git hooks。

• 打开.git/hooks/pre-commit.sample，这个hooks的大体功能是检查文件名是否包含非ASCII字符，如果包含，则无法执行commit操作，并提示用户修改文件名。

• 删除pre-commit.sample的后缀

  ➜ mv .git/hooks/pre-commit.sample .git/hooks/pre-commit
  

• 添加一个有汉字的文件名，如测试.md

  ➜  touch 测试.md
  

• 将新文件提交

  ➜ git add 测试.md
  ➜ git commit -m "测试"
  Error: Attempt to add a non-ASCII file name.
  
  This can cause problems if you want to work with people on other platforms.
  
  To be portable it is advisable to rename the file.
  
  If you know what you are doing you can disable this check using:
  
  git config hooks.allownonascii true
  

  如果无法执行pre-commit可能未被赋予执行权限，修改一下权限即可：chmod +x .git/hooks/pre-commit

我们可以发现，在进行commit操作时被中断了，会提示用户修改文件名。其他的hooks用法类似，我们可以自定义在什么时候可以push，什么时候可以rebase等等。

hooks通常会被用来做提交代码前的一个检查，比如风格是否统一，编译是否通过等等。如果团队合作时，这样的检查最好能够与成员保持一致，但是hooks所在的.git目录是不会被Git自己版本管理的，换句话说，它不能推送到远端与成员共享。那么如何解决这个问题呢？

如何同步hooks文件

方案一：与源码放在一起

代码仓库中新建一个hooks目录，将该目录同步到远程。其他成员下载代码时也会下载hooks目录，通过脚本的方式将hooks目录覆盖本地的.git/hooks目录。

#!/bin/bash
cp -r ./hooks/ .git/hooks/
chmod +x -R .git/hooks
echo 'Hooks sync to remote success!'
exit 0

方案二：使用pre-commit框架

pre_commit 是 pre-commit 同名的开源应用，使用pre-commit，代码仓库里只需要有一个配置文件，所有成员都可以根据配置文件，使用pre_commit生成统一的hooks。

pre-commit随着发展，已经不单单只能用于git hooks的pre-commit阶段，而是能作用于所有git hooks的所有阶段，如上面说的prepare-commit-msg, commit-msg, post-commi等。

安装pre-commit

pip install pre-commit

在项目目录下，添加配置文件 .pre-commit-config.yaml

touch .pre-commit-config.yaml

• 首先了解配置的格式

  • 顶层有一个参数名为 repos
  • repos 中每个元素为 repo ，代表一个代码库，一般是github或gitlab链接。在使用时会从对应地址下载，如果出现下载慢的情况，可以在gitee搜索是否有相关镜像。
  • 每个 repo 中有一个或多个 hook ，每个 hook 代表一个任务。
  • 每个任务里可理解为一个命令行指令，例如flake8/yapf/black。

• pre_commit官方提供了各种配置，我们可以根据需要选择一个合适的。比如我需要一个格式化C语言代码的配置，选择了mirrors-clang-format，还选了一个用来删除行尾空格的。

  repos:
  -   repo: https://github.com/pre-commit/pre-commit-hooks
      rev: v4.3.0
      hooks:
      - id: trailing-whitespace
  
  - repo: https://github.com/pre-commit/mirrors-clang-format
      rev: v14.0.6
      hooks:
      - id: clang-format
          types_or: [c]
  

  参数的含义可以参考pre-commit的文档。每个id对应的其实都是一个程序，为了保证都能正常运行，还需要安装这些程序。一般在仓库的README中都会有提示如何安装。

• 根据配置文件安装hooks 在项目根目录下运行：

  pre-commit install
  

• 在执行git commit命令时将会自动检查。这个过程中，pre-commit会从仓库里下载代码，然后根据里面的配置执行相应的脚本。完成各种检查。

常用命令

# 手动对所有的文件执行 hooks，新增 hook 的时候可以执行，使得代码均符合规范。直接执行该指令则无需等到 pre-commit 阶段再触发 hooks
pre-commit run --all-files
# 执行特定 hooks
pre-commit run <hook_id>
# 将所有的hook更新到最新的版本/tag
pre-commit autoupdate
# 指定更新 repo
pre-commit autoupdate --repo https://github.com/pre-commit/mirrors-clang-format

参考资料

1. C++ 项目中使用 Pre-commit 协助实现代码规范检查_清欢守护者的博客-CSDN 博客

2. git push 之前自动编译验证 - 简书

3. 使用 pre-commit 实现代码检查_清欢守护者的博客-CSDN 博客

4. pre-commit

5. Git 基本原理介绍 (32)——git hook 和 python_哔哩哔哩_bilibili

git pull == git fetch + git merge
git pull --rebase == git fetch + git rebase

拆解来看这两个命令就是在拉取远端代码后，是合并还是进行变基操作。

假设当前有三个提交A,B,C，并且分支feature都与远程代码同步。

我们在feature上做了一些修改，并产生了E提交，远程也有用户进行了更新到了D提交。

此时我们需要git fetch获取最新的代码，然后git merge解决冲突后重新git add git commit，得到F提交。最后git push即可成功推送，得到如下的关系

而使用git rebase将会创建一个新的提交F，F的文件内容和上面F的一样，但我们将 E 提交废除，当它不存在（图中用虚线表示）。由于这种删除，避免了菱形的产生，保持提交曲线为直线。

在rebase的过程中，有时也会有冲突，这时 Git 会停止rebase并让用户去解决冲突，解决完冲突后，用git add添加修改的文件，然后不用执行git commit，直接执行git rebase --continue，这样 git 会继续 apply 余下的补丁。

拉取最新代码后发现有相同的文件，只是文件名不同。index1.htm和index2.htm两个文件内容是完全相同的。

查看当前状态，可知有其他想把文件名修改为index2.htm。此时只需要根据提示，删除index.htm。协商后决定保留哪一个文件，比如我们决定保留index1.htm。那么删除index2.htm。

最后在commit一次，即可顺利推送。

用户二修改了文件内容，也进行了推送，

当然会被无情拒绝，

解决这个问题也十分简单，Git 可以智能的感知到只是文件名被修改，只需要一个git pull命令就可以解决。弹出弹窗可以直接保存退出，默认不变就行。

首先拉取远端最新的代码，会提示有冲突的文件，

打开冲突的文件，git 会对冲突区域进行标记，<<<<<<到======区域表示远端的代码。======到>>>>>>>表示本地的代码。这时候就需要自己来判断需要哪些代码，也可以增删一些内容，修改完成后将这些标识符号删除，然后保存退出。

git status查看当前状态，提示还有未合并的路径，需要进行commit操作。

及时git push当前代码。

以最近三次提交为例，假设想要修改第二个提交的message。可以使用git rebase命令

git rebase -i 27d2f

• -i交互式变基
• 27d2f需要改变message的提交的父节点

弹出页面可以使用提供的命令进行操作，比如pick意思就是挑选需要的commit。本次任务需要修改message，从下方帮助文档里可以找到reword命令，可以保留commit，只修改message。

保存退出后，会弹出另外一个界面。

在这里就可以真正修改需要更新的message。保存退出即可。

git commit --amend

弹出页面就和git commit操作时的一样，将其改为新内容即可。

因为现在大部分情况下是先从远程 Clone 下来代码，所以这一功能用的不多。但是如果自己想把本地已有的代码同步到远程，本文就可以解决这一的需求。

方法

• GitHub 新建一个仓库，并复制 SSH 地址

  git@github.com:git201901/git_learning.git
  

• git remote add 名称

  pc:git-learning suling$ git remote add github git@github.com:git201901/git_learning.git
  

  这里的github就是自定义的一个名称，用于替换后面的远程地址。方便后续git push github以及git fetch github。

同一个项目，不同的开发者修改了不同的文件，如何解决同步冲突。

模拟

用户一修改

第一个用户新建一个分支，

以上命令就是新建一个分支feature/add_git_commands 将其与远端分支origin/feature/add_git_commands相关联，并切换到该分支。

修改 readme 文件，并推送到远端。因为新建分支时已经做了与远端关联，所以可以直接git push。

用户二修改

第二个用户，首先拉取远端分支。

git branch -v查看本地分支，保持不变，但是git branch -av查看所有分支，可以发现多了两个远端分支。

新建本地分支，保持与远端分支名相同。

此时再对与 readme 不同的文件进行修改，提交，推送都会比较顺利。因为当前分支保持fast forward。

用户二继续做开发，但是没再往远端推送代码。在此期间，用户一对远端代码进行了更新。用户二想再次推送代码，将会报错，提示当前提交不再fast forward。

解决方法

• git fetch远端分支

  

• git merge合并远端分支

  

因为两个用户修改的不同文件，所以合并不会产生冲突。

在使用Git版本控制时，必须要用.gitignore这个文件来告诉Git那些文件或目录不需要添加到版本控制中。通俗点说，就是不需要git push到远程仓库。

在平时开发过程中，开发目录下会有各种格式的文件，比如 C 语言除了.c源码，还会有.o目标文件，没有后缀的可执行程序等等，假如你要进行深度学习类的开发，如图像识别，需要训练大量数据，如果这些训练数据也到跟踪管理，那push一次就可以下班回家了。

但是我们怎么让Git知道哪些文件需要跟踪，哪些文件不需要呢，这时候.gitignore文件就起作用了。

常用规则

简单介绍一下常用的规则，虽然后面有现成的模板，但是我们还是了解一下常用规则，能看得懂.gitignore里写了啥。也方便自己编写一些规则适应自己的工作。

/test/              # 过滤整个test文件夹
*.o                 # 过滤所有.o文件
/test/hello.o       # 过滤test文件夹下hello.o这个文件
!src/               # 不过滤src这个文件夹
!*.c                # 不过滤.c文件

通过 gitignore 文件更新远程仓库

上面说到我们在不同环境下需要制定不同的规则，但是每次都要重新写一遍，又或者不知道制定什么样的规则，还是挺麻烦的。

首先推荐一个.gitignore模板仓库，在平时工作学习中遇到的各种语言环境下的模板都能找到。这是广大开发人员总结的一些规则。

最近在学习Qt，在所有模板中搜索关键字，找到了Qt.gitignore这个模板打开并复制，在自己本地仓库里新建一个.gitignore文件，将复制的内容粘贴进去。

现在就要解决如何更新远程仓库的内容，因为我在使用.gitignore文件之前已经向远程push过了，现在需要删除不需要的文件。

git rm -r --cached .

rm就是Linux下常用的删除命令，-r表示递归删除，--cached表示需要在本地端（工作区）保留文件，.表示所有文件。

git add .   # 重新添加所有文件到暂存区，然后提交，推送
git commit -m "update"
git push

好在可以通过一些小技巧，下载国内镜像，进行加速。但是下载项目时，只是主体是国内的镜像，子模块仍然下载很慢。首先解决获取国内镜像的问题。有三个方法：

• 在码云 Gitee 上搜索下载

  在码云上搜索同样的项目，然后用码云git 的地址下载。

• 加上.cnpmjs.org后缀

  在地址后面加上后缀，如git clone https://github.com.cnpmjs.org/riscv/riscv-binutils-gdb.git。

• 使用油猴脚本获取镜像地址

  如果你有油猴插件可以去greasyfork搜索安装GitHub镜像访问，加速下载这个脚本，刷新GitHub仓库界面就会多出几个镜像地址，一般下载都会快好几倍。

  

再来解决子模块下载速度慢的问题，下载项目时，先不加--recursive参数，只下载项目的本题。

下载完后找到.gitmodules文件，这是一个隐藏文件，需要显示隐藏文件，Linux 下使用快捷键Ctrl+H。用vim打开后可以得到：

这个文件里写入了子模块的下载信息，url就是下载地址。我们把所有子模块中的 URL 地址同样加上.cnpmjs.org后缀。或者使用上述三种方式得到的镜像地址。

然后利用git submodule sync更新子项目对应的url

最后再git submodule update --init --recursive，即可快速下载所有子项目。

# 注意有个点“.”
取消版本控制
git rm -r --cached .
重新添加
git add -A
重新提交
git commit -m "update .gitignore"

Git rm 和 rm –cached 区别

rm ：当需要删除暂存区或分支上的文件，同时工作区不需要这个文件

rm --cached：当需要删除暂存区或分支上的文件，同时工作区需要这个文件，但是不需要被版本控制。就是本地需要保留，但是远程不保留

推送空文件夹到远程仓库

在需要推送的空文件下创建".gitkeep"文件 在".gitignore"文件中编写规则 !.gitkeep

克隆指定分支代码

 git clone  -b master https://github.com/Dunky-Z/Dunky-Z.github.io.git

master就是分支名