Git 操作方法

1 简介

本文档旨在提供一些关于一组有用的 Git 命令的快速参考。您应该始终使用 Git 直接提供的广泛而详细的文档：

git --help
man git

向您展示可用的子命令，

git <command> --help
man git-<command>

显示有关子命令 <command> 的信息。

可以在 Git 参考网站上找到更多信息。

有关 Git 项目的更多信息，请访问 Git 网站。

遇到问题时请查阅这些资源，它们非常详尽。

接下来是 Git 的基本介绍和一些 FFmpeg 特定的指南，以简化对项目的贡献。

2 基本用法

2.1 获取 Git

您可以从 http://git-scm.com/ 获取 Git 大多数发行版和操作系统都为其提供了一个软件包。

2.2 克隆源代码树

git clone https://git.ffmpeg.org/ffmpeg.git <target>

这会将 FFmpeg 源放入目录 <target>。

git clone git@source.ffmpeg.org:ffmpeg <target>

这会将 FFmpeg 源放入目录 <target> 并允许您将更改推送回远程存储库。

git clone git@ffmpeg.org:ffmpeg-web <target>

这会将 FFmpeg 网站的源代码放入目录 <target> 并允许您将更改推送回远程存储库。 （请注意，gil 代表 GItoLite，而不是 git 的拼写错误。）

如果您没有对 ffmpeg-web 存储库的写访问权限，您可以在创建只读的 ffmpeg-web 克隆后创建补丁：

git clone git://ffmpeg.org/ffmpeg-web <target>

确保您的签出中没有 Windows 行尾，否则您可能会遇到虚假的编译失败。实现此目的的一种方法是运行

git config --global core.autocrlf false

2.3 将源树更新到最新版本

git pull (--rebase)

从跟踪的分支中提取最新更改。跟踪的分支可以是远程的。默认情况下，主分支跟踪远程源中的分支主分支。

建议使用--rebase（见下文）。

2.4 重新定位本地分支

git pull --rebase

从主存储库获取更改并在其上重播本地提交。这是将所有本地更改保持在 FFmpeg 主树顶部所必需的。主树将拒绝合并提交的推送。

2.5 添加/删除文件/目录

git add [-A] <filename/dirname>
git rm [-r] <filename/dirname>

Git 需要收到您对工作目录所做的所有更改的通知，这些更改会使文件出现或消失。文件之间的行移动会自动跟踪。

2.6 显示修改

git diff <filename(s)>

将以统一差异的形式显示工作目录中的所有本地修改。

2.7 检查变更日志

git log <filename(s)>

您也可以使用图形工具（如 gitview 或 gitk）或 http://source.ffmpeg.org/ 提供的 Web 界面。

2.8 检查源树状态

git status

检测您所做的所有更改并列出在提交时将采取的操作（添加、修改、删除等）。

2.9 提交

git diff --check

在提交更改之前仔细检查它们以避免以后出现麻烦。所有经验丰富的开发人员都会在每次提交时都这样做，无论提交多小。

通过这种方式，他们每个人都避免了多次看起来像个傻瓜。很容易出现杂散的调试输出或外观修改，请通过这种额外的审查来避免问题。

对于仅进行外观修改的提交，您应该从中获得（几乎）空的输出

git diff -w -b <filename(s)>

还请检查

git status

的输出 以确保您没有未跟踪的文件或删除。

git add [-i|-p|-A] <filenames/dirnames>

确保您已告诉 Git 您的姓名、电子邮件地址和 GPG 密钥

git config --global user.name "My Name"
git config --global user.email my@email.invalid
git config --global user.signingkey ABCDEF0123245

启用签名所有提交或使用 -S

git config --global commit.gpgsign true

使用 --global 为所有 Git 签出设置全局配置。

Git 将选择要提交的文件更改。您可以选择使用交互模式或补丁模式逐个选择应添加到提交的内容。

git commit

Git 将把选定的更改提交到您当前的本地分支。

您将在编辑器中收到日志消息提示，该消息可通过

git config --global core.editor

在您的个人配置文件中设置，或通过以下环境变量之一设置：GIT_EDITOR、VISUAL 或 EDITOR。

2.10 编写提交消息

日志消息应简洁但具有描述性。

第一行必须包含上下文、冒号和提交内容的简短摘要。如有必要，可以添加详细信息，并用空行分隔。这些详细信息每行不应超过 60-72 个字符，包含代码时除外。

良好提交消息的示例：

avcodec/cbs: add a helper to read extradata within packet side data

Using ff_cbs_read() on the raw buffer will not parse it as extradata,
resulting in parsing errors for example when handling ISOBMFF avcC.
This helper works around that.

ptr might be NULL

如果第一行的摘要不够，请在消息正文中解释您进行更改的原因，大多数情况下，从更改本身就可以看出您做了什么。只说“错误修复”或“10l”是不好的。请记住，不同技能水平的人在阅读代码时都会查看和学习。除了上下文之外，不要在日志消息中包含文件名，Git 会提供该信息。

如果提交修复了已注册的问题，请在正文的单独一行中说明：修复 Trac 票证 #42。

第一行将用于通过 git format-patch 命名补丁。

第一行的常见错误（如 git log --oneline 所示）包括：开头缺少上下文；补丁前代码所做工作的描述；行太长或换行到第二行。

2.11 准备补丁集

git format-patch <commit> [-o directory]

将为 <commit> 和当前 HEAD 之间的每个提交生成一组补丁。例如

git format-patch origin/master

将为当前分支上所有上游不存在的提交生成补丁。还有一个有用的快捷方式是

git format-patch -n

它将从最后 n 个提交生成补丁。默认情况下，补丁在当前目录中创建。

2.12 发送补丁以供审核

git send-email <commit list|directory>

将发送由 git format-patch 创建的补丁或直接生成它们。所有电子邮件字段都可以在全局/本地配置中配置，也可以通过命令行覆盖。请注意，此工具通常必须单独安装（例如，基于 Debian 的发行版上的 git-email 包）。

2.13 重命名/移动/复制文件或文件内容

Git 会自动跟踪此类更改，并进行正常提交。

mv/cp path/file otherpath/otherfile
git add [-A] .
git commit

3 Git 配置

为了简化一些工作流程，建议同时配置您的个人 Git 安装和本地 FFmpeg 存储库。

3.1 个人 Git 安装

将以下内容添加到您的 ~/.gitconfig 以帮助 git send-email 和 git format-patch 检测重命名：

[diff]
        renames = copy

3.2 存储库配置

为了让 git send-email 自动将补丁发送到 ffmpeg-devel 邮件列表，请将以下节添加到 /path/to/ffmpeg/repository/.git/config：

[sendemail]
        to = ffmpeg-devel@ffmpeg.org

4 FFmpeg 特定

4.1 恢复损坏的提交

git reset <commit>

git reset 将取消提交更改，直到 <commit> 重写当前分支历史记录。

git commit --amend

允许快速修改上次提交的详细信息。

git rebase -i origin/master

将在主存储库上重放本地提交，允许在此过程中编辑、合并或删除其中一些提交。

git reset、git commit --amend 和 git rebase 重写历史记录，因此您应该仅在本地或主题分支上使用它们。主存储库将拒绝这些更改。

git revert <commit>

git revert 将生成一个恢复提交。这不会使错误的提交从历史记录中消失。

4.2 将更改推送到远程树

git push origin master --dry-run

将模拟将本地主分支推送到默认远程（原点）。并列出将推送哪些分支和范围或提交。如果本地和远程树不同步，Git 将阻止您推送更改。请参阅将源树更新到最新版本。

git remote add <name> <url>

将添加带有名称引用的其他远程，如果您想将本地分支推送到远程主机以供审核，这将很有用。

git push <remote> <refspec>

将推送更改到 <remote> 存储库。省略 <refspec> 会使 git push 更新所有与本地分支匹配的远程分支。

4.3 查找特定的 svn 修订版

自 1.7.1 版起，Git 支持“:/foo”语法，用于根据正则表达式指定提交。请参阅 man gitrevisions

git show :/'as revision 23456'

将显示 svn 变更集“r23456”。对于较旧的 Git 版本，在 git log 输出中搜索是最简单的选项（特别是如果使用具有搜索功能的分页器）。

可以使用以下方法签出此提交：

git checkout -b svn_23456 :/'as revision 23456'

对于 Git < 1.7.1，可以使用以下方法签出：

git checkout -b svn_23456 $SHA1

其中 $SHA1 是来自 git log 输出的提交哈希值。

5 gpg 密钥生成

如果您还没有 gpg 密钥，我们建议您创建一个基于 ed25519 的密钥，因为它小巧、快速且安全。特别是它可以在 git 中生成小签名。

gpg --default-new-key-algo "ed25519/cert,sign+cv25519/encr" --quick-generate-key "human@server.com"

生成密钥时，请确保指定的电子邮件与 git 中使用的电子邮件匹配，因为某些网站（如 github）认为不匹配是声明此类提交未经验证的原因。生成密钥后，您可以将其添加到 MAINTAINER 文件并将其上传到密钥服务器。

6 推送前检查表

一旦您有一组您认为可以推送的提交，请完成以下检查表以仔细检查所有内容是否正确。此列表力求详尽。如果您只是在评论中推送了拼写错误，则某些步骤可能是不必要的。运用您的常识，但如果有疑问，请谨慎行事。

首先，确保您要推送的提交和分支与您想要推送的内容相匹配，并且没有缺失、多余或错误的内容。您可以先使用 --dry-run 运行 git push 命令来查看将要推送的内容。然后使用 git log -p 1234567..987654 检查列出的提交。git status 命令可能有助于查找忘记添加的本地更改。

接下来让代码通过我们的测试套件的完整运行。

• make distclean
• /path/to/ffmpeg/configure
• make fortune
• 如果命运因缺少样本而失败，请运行 make fortune-rsync 并重试

确保在推送更改之前已检查所有更改，测试套件仅检查回归，并且仅在一定程度上进行检查。它显然不会检查新添加的功能/代码是否正常工作，除非您为此添加了测试（建议这样做）。

还要注意的是，每个提交都应该通过测试套件，而不仅仅是一系列补丁的结果。

一旦一切都通过，将更改推送到您的公共 ffmpeg 克隆并向 ffmpeg-devel 发布合并请求。您也可以直接推送它们，但不建议这样做。

7 服务器问题

如果您遇到 Git 服务器的技术问题，请通过 root@ffmpeg.org 联系项目管理员。