简体中文 ▾ 主题 ▾ 最新版本 ▾ git-fsck 上次更新于 2.53.0

名称

git-fsck - 验证数据库中对象的连通性和有效性

概要

git fsck [--tags] [--root] [--unreachable] [--cache] [--no-reflogs]
	 [--[no-]full] [--strict] [--verbose] [--lost-found]
	 [--[no-]dangling] [--[no-]progress] [--connectivity-only]
	 [--[no-]name-objects] [--[no-]references] [<object>…​]

描述

验证数据库中对象的连通性和有效性。

选项

<object>

视为不可达跟踪起点的对象。

如果没有给定对象，git fsck 默认使用索引文件、refs 命名空间中的所有 SHA-1 引用，以及所有引用日志（reflogs，除非指定了 --no-reflogs）作为起点。

--unreachable

打印出存在但无法从任何引用节点到达的对象。

--dangling
--no-dangling

打印出存在但从未直接使用的对象（默认）。--no-dangling 可用于在输出中忽略此信息。

--root

报告根节点。

--tags

报告标签。

--cache

将索引中记录的任何对象也视为不可达跟踪的头节点。

--no-reflogs

不将仅由引用日志条目引用的提交视为可达。此选项仅用于搜索那些过去在引用中、现在已不在，但仍存在于对应引用日志中的提交。

--full

不仅检查 GIT_OBJECT_DIRECTORY ($GIT_DIR/objects) 中的对象，还检查 GIT_ALTERNATE_OBJECT_DIRECTORIES 或 $GIT_DIR/objects/info/alternates 中列出的备用对象池，以及 $GIT_DIR/objects/pack 中的打包 Git 存档和备用对象池中相应的 pack 子目录。这现在是默认设置；可以使用 --no-full 关闭。

--connectivity-only

仅检查可达对象的连通性，确保可达标签、提交或树引用的任何对象都存在。这通过完全避免读取二进制大对象（blob）来加快操作速度（尽管它仍然会检查所引用的 blob 是否存在）。这将检测提交和树中的损坏，但不会进行任何语义检查（例如格式错误）。不会检测 blob 对象中的损坏。

不可达的标签、提交和树也将被访问，以找到历史记录中悬空片段的尖端。如果您不关心此输出并希望进一步加速，请使用 --no-dangling。

--strict

启用更严格的检查，即捕获由旧版本 Git 创建的设置了 g+w 位的记录文件模式。现有的仓库（包括 Linux 内核、Git 本身和稀疏仓库）都有会触发此检查的旧对象，但建议对新项目使用此标志进行检查。

--verbose

输出详细信息。

--lost-found

将悬空对象写入 .git/lost-found/commit/ 或 .git/lost-found/other/，具体取决于类型。如果对象是 blob，则将其内容写入文件，而不是其对象名称。

--name-objects

当显示可达对象的名称时，除 SHA-1 外，还显示描述它们如何可达的名称，与 git-rev-parse[1] 兼容，例如 HEAD@{1234567890}~25^2:src/。

--progress
--no-progress

默认情况下，当连接到终端时，进度状态会报告在标准错误流上，除非指定了 --no-progress 或 --verbose。即使标准错误流未指向终端，--progress 也会强制显示进度状态。

--references
--no-references

控制是否通过 git refs verify 检查引用数据库的一致性。有关详细信息，请参阅 git-refs[1]。默认是检查引用数据库。

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

fsck.<msg-id>

在 fsck 期间，git 可能会发现当前版本 git 不会生成的遗留数据问题，如果设置了 transfer.fsckObjects，这些数据也不会通过网络发送。此功能旨在支持处理包含此类数据的遗留仓库。

设置 fsck.<msg-id> 将被 git-fsck[1] 拾取，但要接受此类数据的推送，请设置 receive.fsck.<msg-id>，或者要克隆或获取它，请设置 fetch.fsck.<msg-id>。

文档的其余部分为简洁起见讨论了 fsck.*，但这同样适用于相应的 receive.fsck.* 和 fetch.fsck.* 变量。

与 color.ui 和 core.editor 等变量不同，如果未设置 receive.fsck.<msg-id> 和 fetch.fsck.<msg-id> 变量，它们不会回退到 fsck.<msg-id> 配置。要在不同情况下统一配置相同的 fsck 设置，必须将这三个变量全部设置为相同的值。

当设置了 fsck.<msg-id> 时，可以通过配置 fsck.<msg-id> 设置将错误切换为警告，反之亦然，其中 <msg-id> 是 fsck 消息 ID，值可以是 error、warn 或 ignore。为了方便起见，fsck 在错误/警告前加上消息 ID，例如 "missingEmail: invalid author/committer line - missing email" 意味着设置 fsck.missingEmail = ignore 将隐藏该问题。

通常，最好使用 fsck.skipList 列出存在问题的现有对象，而不是列出这些有问题的对象所共有的破坏类型以进行忽略，因为这样做会允许相同破坏的新实例未被发现。

设置未知的 fsck.<msg-id> 值会导致 fsck 终止，但对 receive.fsck.<msg-id> 和 fetch.fsck.<msg-id> 执行相同的操作只会导致 git 发出警告。

有关 <msg-id> 的支持值，请参阅 git-fsck[1] 的 Fsck Messages 部分。

fsck.skipList

指向对象名称列表的路径（即每行一个未缩写的 SHA-1），这些对象已知以非致命方式损坏，应被忽略。在 2.20 及更高版本的 Git 中，注释 (#)、空行以及任何前导和尾随空格都会被忽略。在旧版本中，除每行一个 SHA-1 之外的任何内容都会报错。

当一个成熟的项目尽管包含可以安全忽略的错误的早期提交（例如无效的提交者电子邮件地址）也应该被接受时，此功能非常有用。注意：损坏的对象无法通过此设置跳过。

像 fsck.<msg-id> 一样，此变量具有相应的 receive.fsck.skipList 和 fetch.fsck.skipList 变体。

与 color.ui 和 core.editor 等变量不同，如果未设置 receive.fsck.skipList 和 fetch.fsck.skipList 变量，它们不会回退到 fsck.skipList 配置。要在不同情况下统一配置相同的 fsck 设置，必须将这三个变量全部设置为相同的值。

旧版本的 Git（2.20 之前）记录了对象名称列表应该是排序的。这从来不是强制要求；对象名称可以以任何顺序出现，但在读取列表时，我们为了内部二叉搜索实现的目的跟踪了列表是否已排序，如果列表已经排序，可以节省一些工作。除非您有一个庞大的列表，否则没有理由特意预先排序列表。在 Git 2.20 版本之后使用了哈希实现，所以现在没有理由预先排序列表。

讨论

git-fsck 测试 SHA-1 和一般对象的健全性，并对产生的连通性等进行全面跟踪。它会打印出发现的任何损坏（缺失或错误的对象），如果您使用 --unreachable 标志，它还会打印出存在但无法从任何指定的头节点（或上述默认集合）到达的对象。

任何损坏的对象都必须在备份或其他存档中找到（即，您可以删除它们，并希望通过 rsync 与其他站点同步，以防其他人拥有您损坏的对象）。

如果 core.commitGraph 为真，还将使用 git commit-graph verify 检查提交图文件。请参阅 git-commit-graph[1]。

提取的诊断信息

unreachable <type> <object>

<type> 对象 <object> 在所见的任何树或提交中均未直接或间接提及。这可能意味着存在您未指定的另一个根节点，或者树已损坏。如果您没有遗漏根节点，那么最好删除不可达节点，因为它们无法被使用。

missing <type> <object>

<type> 对象 <object> 被提及，但在数据库中不存在。

dangling <type> <object>

<type> 对象 <object> 存在于数据库中，但从未使用过。一个悬空的提交可能是一个根节点。

hash mismatch <object>

数据库中有一个对象的哈希值与对象数据库中的值不匹配。这表明存在严重的数据完整性问题。

FSCK 消息

以下列出了 git fsck 检测到的错误类型及其含义，以及它们的默认严重性。除标记为 "(FATAL)" 的错误外，错误的严重性可以通过设置相应的 fsck.<msg-id> 配置变量来进行微调。

badDate

(ERROR) 作者/提交者行中的日期格式无效。

badDateOverflow

(ERROR) 作者/提交者行中的日期值无效。

badEmail

(ERROR) 作者/提交者行中的电子邮件格式无效。

badFilemode

(INFO) 树中包含错误的文件模式条目。

badGpgsig

(ERROR) 标签包含错误（截断）的签名（例如 gpgsig）头。

badHeadTarget

(ERROR) HEAD 引用是一个不指向分支的符号引用。

badHeaderContinuation

(ERROR) 延续头（例如对于 gpgsig）被意外截断。

badName

(ERROR) 作者/提交者姓名为空。

badObjectSha1

(ERROR) 对象具有错误的 sha1。

badPackedRefEntry

(ERROR) "packed-refs" 文件包含无效条目。

badPackedRefHeader

(ERROR) "packed-refs" 文件包含无效头。

badParentSha1

(ERROR) 提交对象具有错误的父 sha1。

badRefContent

(ERROR) 引用内容错误。

badRefFiletype

(ERROR) 引用具有错误的文件类型。

badRefName

(ERROR) 引用格式无效。

badRefOid

(ERROR) 引用指向无效的对象 ID。

badReferentName

(ERROR) 符号引用的引用目标名称无效。

badReftableTableName

(WARN) reftable 表名无效。

badTagName

(INFO) 标签格式无效。

badTimezone

(ERROR) 在作者/提交者行中发现了无效的时区。

badTree

(ERROR) 无法解析树。

badTreeSha1

(ERROR) 树格式无效。

badType

(ERROR) 发现了无效的对象类型。

duplicateEntries

(ERROR) 树包含重复的文件条目。

emptyName

(WARN) 路径包含空名称。

emptyPackedRefsFile

(INFO) "packed-refs" 文件为空。如果您看到此错误，请向 git@vger.kernel.org 邮件列表报告。由于只有非常早期的 Git 版本会创建这样的空 "packed_refs" 文件，我们将来可能会收紧此规则。

extraHeaderEntry

(IGNORE) 在 tagger 后发现了额外的头。

fullPathname

(WARN) 路径包含了以 "/" 开头的完整路径。

gitattributesBlob

(ERROR) 在 .gitattributes 处发现了非 blob 对象。

gitattributesLarge

(ERROR) .gitattributes blob 太大。

gitattributesLineLength

(ERROR) .gitattributes blob 包含过长的行。

gitattributesMissing

(ERROR) 无法读取 .gitattributes blob。

gitattributesSymlink

(INFO) .gitattributes 是一个符号链接。

gitignoreSymlink

(INFO) .gitignore 是一个符号链接。

gitmodulesBlob

(ERROR) 在 .gitmodules 处发现了非 blob 对象。

gitmodulesLarge

(ERROR) .gitmodules 文件太大，无法解析。

gitmodulesMissing

(ERROR) 无法读取 .gitmodules blob。

gitmodulesName

(ERROR) 子模块名称无效。

gitmodulesParse

(INFO) 无法解析 .gitmodules blob。

gitmodulesPath

(ERROR) .gitmodules 路径无效。

gitmodulesSymlink

(ERROR) .gitmodules 是一个符号链接。

gitmodulesUpdate

(ERROR) 发现了无效的子模块更新设置。

gitmodulesUrl

(ERROR) 发现了无效的子模块 URL。

hasDot

(WARN) 树中包含名为 . 的条目。

hasDotdot

(WARN) 树中包含名为 .. 的条目。

hasDotgit

(WARN) 树中包含名为 .git 的条目。

largePathname

(WARN) 树中包含具有非常长路径名的条目。如果 fsck.largePathname 的值包含冒号，则该值将用作最大允许长度（例如 "warn:10" 会对任何 11 个或更多字节的路径组件发出警告）。默认值为 4096。

mailmapSymlink

(INFO) .mailmap 是一个符号链接。

missingAuthor

(ERROR) 缺少作者。

missingCommitter

(ERROR) 缺少提交者。

missingEmail

(ERROR) 作者/提交者行中缺少电子邮件。

missingNameBeforeEmail

(ERROR) 作者/提交者行中电子邮件前缺少名称。

missingObject

(ERROR) 标签对象中缺少 object 行。

missingSpaceBeforeDate

(ERROR) 作者/提交者行中日期前缺少空格。

missingSpaceBeforeEmail

(ERROR) 作者/提交者行中电子邮件前缺少空格。

missingTag

(ERROR) 标签对象中 type 行后出现意外结束。

missingTagEntry

(ERROR) 标签对象中缺少 tag 行。

missingTaggerEntry

(INFO) 标签对象中缺少 tagger 行。

missingTree

(ERROR) 提交对象中缺少 tree 行。

missingType

(ERROR) 标签对象中 type 行的类型值无效。

missingTypeEntry

(ERROR) 标签对象中缺少 type 行。

multipleAuthors

(ERROR) 在提交中发现了多个作者行。

nulInCommit

(WARN) 在提交对象主体中发现了 NUL 字节。

nulInHeader

(FATAL) 对象头中存在 NUL 字节。

nullSha1

(WARN) 树包含指向空 sha1 的条目。

packedRefEntryNotTerminated

(ERROR) "packed-refs" 文件包含一个未以换行符终止的条目。

packedRefUnsorted

(ERROR) "packed-refs" 文件未排序。

refMissingNewline

(INFO) 松散引用不以换行符 (LF) 结尾。由于有效的 Git 实现从不创建此类松散引用文件，因此将来它可能会成为错误。如果您看到此错误，请向 git@vger.kernel.org 邮件列表报告，因为我们需要知道是什么工具创建了此类文件。

symlinkRef

(INFO) 符号链接被用作符号引用。如果您看到此错误，请向 git@vger.kernel.org 邮件列表报告，因为我们正在评估放弃支持创建符号链接作为符号引用的可行性。

symrefTargetIsNotARef

(INFO) 符号引用的目标既不指向根引用，也不指向以 "refs/" 开头的引用。尽管我们允许通过使用 git symbolic-ref 创建指向 "ref" 之外引用目标的符号引用，但将来可能会收紧此规则。如果您看到此错误，请向 git@vger.kernel.org 邮件列表报告，因为我们需要知道是什么工具创建了此类文件。

trailingRefContent

(INFO) 松散引用包含尾随内容。由于有效的 Git 实现从不创建此类松散引用文件，因此将来它可能会成为错误。如果您看到此错误，请向 git@vger.kernel.org 邮件列表报告，因为我们需要知道是什么工具创建了此类文件。

treeNotSorted

(ERROR) 树未正确排序。

unknownType

(ERROR) 发现了未知的对象类型。

unterminatedHeader

(FATAL) 对象头中缺少行尾。

zeroPaddedDate

(ERROR) 在作者/提交者行中发现了零填充的日期。

zeroPaddedFilemode

(WARN) 在树中发现了零填充的文件模式。

环境变量

GIT_OBJECT_DIRECTORY

用于指定对象数据库根目录（通常为 $GIT_DIR/objects）

GIT_INDEX_FILE

用于指定索引文件

GIT_ALTERNATE_OBJECT_DIRECTORIES

用于指定额外的对象数据库根目录（通常未设置）

GIT

Git[1] 套件的一部分