Magit 用户手册

• magit-display-buffer buffer &optional display-function [Function] 此函数是 display-buffer 的包装器, 用于显示任何 Magit buffer. 它在某个窗口中显示 BUFFER, 并且与 display-buffer 不同, 只要 magit-display-buffer-noselect 为 nil, 它还会选中该窗口. 它还运行下面提到的 hooks. 如果可选的 DISPLAY-FUNCTION 为非 nil, 则使用它来显示 buffer. 通常它是 nil, 并使用 magit-display-buffer-function 指定的函数.
• magit-display-buffer-noselect [Variable] 当此变量为非 nil 时, magit-display-buffer 仅显示 buffer 但放弃选中窗口. 此变量不应全局设置, 它仅旨在由自动更新 "另一个窗口" 的代码进行 let-bound. 例如, 当你在 log buffer 中移动时更新 revision buffer 时会用到它.
• magit-display-buffer-function [User Option] 此处指定的函数由 magit-display-buffer 调用, 带有一个参数 (一个 buffer), 以实际显示该 buffer. 此函数应调用 display-buffer, 将该 buffer 作为第一个参数, 并将显示操作列表作为第二个参数.

Magit 提供了下面列出的几个函数, 它们是此选项的合适值. 如果你想使用不同的规则, 那么一个好的方法是从复制其中一个函数开始, 然后根据你的需要进行调整.

不使用 display-buffer 的包装器, 也可以直接使用该函数本身, 在这种情况下, 必须通过将显示操作添加到 display-buffer-alist 来指定它们.

要了解显示操作, 请参阅 elisp 中的 "Choosing Window" 一节.

• magit-display-buffer-traditional buffer [Function] 此函数是选项 magit-display-buffer-function 的当前默认值. 在添加该选项和此函数之前, 行为被硬编码在代码库的许多地方, 但现在所有规则都包含在这个函数中 (除了上面提到的 "noselect" 特殊情况).
• magit-display-buffer-same-window-except-diff-v1 [Function] 此函数在当前选定的窗口中显示大多数 buffers. 如果 buffer 的模式派生自 magit-diff-mode 或 magit-process-mode, 则在另一个窗口中显示.
• magit-display-buffer-fullframe-status-v1 [Function] 此函数在显示 status buffer 时填充整个 frame. 否则, 它的行为类似于 magit-display-buffer-traditional.
• magit-display-buffer-fullframe-status-topleft-v1 [Function] 此函数在显示 status buffer 时填充整个 frame. 它的行为类似于 magit-display-buffer-fullframe-status-v1, 除了它将派生自 magit-diff-mode 或 magit-process-mode 的 buffers 显示在当前 buffer 的上方或左侧, 而不是下方或右侧. 结果是, Magit buffers 倾向于在与使用 magit-display-buffer-traditional 时相同的一侧弹出.
• magit-display-buffer-fullcolumn-most-v1 [Function] 此函数显示大多数 buffers 以填充 frame 的整个高度. 但是, 如果 (1) buffer 的模式派生自 magit-process-mode, 或 (2) buffer 的模式派生自 magit-diff-mode, 前提是当前 buffer 的模式派生自 magit-log-mode 或 magit-cherry-mode, 则 buffer 显示在另一个窗口中.
• magit-pre-display-buffer-hook [User Option] 此 hook 由 magit-display-buffer 在显示 buffer 之前运行.
• magit-save-window-configuration [Function] 此函数保存当前窗口配置. 稍后当 buffer 被 bury 时, 可以通过 magit-restore-window-configuration 恢复它.
• magit-post-display-buffer-hook [User Option] 此 hook 由 magit-display-buffer 在显示 buffer 后运行.
• magit-maybe-set-dedicated [Function] 此函数记住是否必须创建一个新窗口来显示 buffer, 或者是否重用了现有窗口. 此信息稍后由 magit-mode-quit-window 使用, 以确定在其最后一个 Magit buffer 被 bury 时是否应删除该窗口.

• magit-generate-buffer-name-function [User Option] 用于生成 Magit buffers 名称的函数. 这样的函数应该考虑选项 magit-uniquify-buffer-names 以及 magit-buffer-name-format. 如果不这样做, 则应在 doc-string 中明确说明. 如果它支持除 magit-buffer-name-format 选项文档中提到的那些之外的 %-sequences, 则其自己的 doc-string 应该描述添加的内容.
• magit-generate-buffer-name-default-function mode [Function] 此函数返回适用于 major-mode 为 MODE 的 buffer 的名称, 该 buffer 显示有关 default-directory 所在仓库的信息. 此函数使用 magit-buffer-name-format 并支持该选项文档中提到的所有 %-sequences. 它也尊重选项 magit-uniquify-buffer-names.

• magit-buffer-name-format [User Option] 用于命名 Magit buffers 的格式字符串. 至少支持以下 %-sequences:

  • %m: major-mode 的名称, 但删除了 -mode 后缀.
  • %M: 类似 %m, 但将 magit-status-mode 缩写为 magit.
  • %v: buffer 被锁定到的值, 在括号中; 如果 buffer 未锁定到值, 则为空字符串.
  • %V: 类似 %v, 但字符串以空格为前缀, 除非它是空字符串.
  • %t: 仓库工作树的顶层目录, 或者如果 magit-uniquify-buffer-names 为非 nil, 则为其缩写.
  • %x: 如果 magit-uniquify-buffer-names 为 nil 则为 *, 否则为空字符串. 由于 uniquify 包的限制, buffer 名称必须以路径结尾.

  该值应始终包含 %m 或 %M, %v 或 %V, 以及 %t. 如果 magit-uniquify-buffer-names 为非 nil, 则该值必须以 %t 或 %t%x 结尾. 参见 issue #2841.

• magit-uniquify-buffer-names [User Option] 此选项控制 Magit buffers 的名称是否唯一化. 如果名称没有被唯一化, 那么它们包含相应仓库工作树顶层的完整路径. 如果它们被唯一化, 那么它们以顶层的 basename 结尾, 或者如果那会与其他 buffers 使用的名称冲突, 那么所有这些 buffers 的名称都会被调整直到不再冲突. 这是使用 uniquify 包完成的; 自定义其选项以控制 buffer 名称如何唯一化.

• q (magit-mode-bury-buffer) 此命令 bury (掩埋) 或 kill (杀死) 当前 Magit buffer. 由选项 magit-bury-buffer-function 指定的函数用于在不带前缀参数调用时 bury buffer, 或在带单个前缀参数调用时 kill 它. 当使用两个或更多前缀参数调用时, 它总是 kill 与当前项目关联的所有 Magit buffers, 包括当前 buffer.
• magit-bury-buffer-function [User Option] 用于实际 bury 或 kill 当前 buffer 的函数. magit-mode-bury-buffer 带一个参数调用此函数. 如果参数为非 nil, 则该函数必须 kill 当前 buffer. 否则它必须 bury 它. 当前默认值是 magit-mode-quit-window.
• magit-restore-window-configuration kill-buffer [Function] 使用 quit-window bury 或 kill 当前 buffer, 该函数调用时将 KILL-BUFFER 作为第一个参数, 将选定窗口作为第二个参数. 然后恢复当前 buffer 在选定 frame 中显示之前存在的窗口配置. 不幸的是, 这也意味着 point 在选定 frame 中显示的所有 buffers 中都会被调整.
• magit-mode-quit-window kill-buffer [Function] 使用 quit-window bury 或 kill 当前 buffer, 该函数调用时将 KILL-BUFFER 作为第一个参数, 将选定窗口作为第二个参数. 然后, 如果该窗口最初是为了显示 Magit buffer 而创建的, 并且被 bury 的 buffer 是该窗口中显示过的最后一个剩余 Magit buffer, 也就是该窗口被删除.

运行可能改变当前仓库状态的命令后, 当前 Magit buffer 和相应的 status buffer 会被刷新. 只要 buffer 保存到相应仓库内的文件, status buffer 就可以自动刷新, 方法是添加一个 hook, 如下所示:

(with-eval-after-load 'magit-mode
  (add-hook 'after-save-hook 'magit-after-save-refresh-status t))

自动刷新 Magit buffers 确保显示的信息大部分时间是最新的, 但在大型仓库中可能会导致明显的延迟. 为了将延迟降至最低, 并且因为这样做有时可能是不希望的, 不会刷新其他 Magit buffers.

Buffers 也可以显式刷新, 这对于上次刷新期间不是当前 buffer 的 buffers 以及在 Magit 外部对仓库进行更改后非常有用.

• g (magit-refresh) 如果当前 buffer 的主模式派生自 magit-mode, 则刷新当前 buffer 以及相应的 status buffer. 如果选项 magit-revert-buffers 要求这样做, 那么它还会 revert 所有访问当前仓库中被跟踪文件的未修改 buffers.
• G (magit-refresh-all) 此命令刷新属于当前仓库的所有 Magit buffers, 并 revert 所有访问当前仓库中被跟踪文件的未修改 buffers. 即使 magit-revert-buffers 为 nil, 访问文件的 buffers 也总是被 reverted.
• magit-refresh-buffer-hook [User Option] 此 hook 在本次刷新期间刷新的每个 Magit buffer 中运行 - 通常是当前 buffer 和 status buffer.
• magit-refresh-status-buffer [User Option] 当此选项为非 nil 时, 除了总是自动刷新的当前 Magit buffer 之外, 在运行 git 产生副作用后, status buffer 也会自动刷新. 只有在用尽所有其他选项以提高性能后, 才将其设置为 nil.
• magit-after-save-refresh-status [Function] 此函数旨在添加到 after-save-hook. 这样做之后, 每当 buffer 保存到仓库内的文件时, 相应的 status buffer 就会被刷新. 请注意, 刷新 Magit buffer 是通过从头开始重新创建其内容来完成的, 这在大型仓库中可能会很慢. 如果你不满意 Magit 的性能, 那么你显然不应该将此函数添加到该 hook.

默认情况下, 访问文件的 buffers 会在特定时间点保存. 这并不能保证 Magit buffers 始终是最新的, 但是, 只要只在 Emacs 中编辑文件并仅使用 Magit 与 Git 交互, 就可以相当自信. 有疑问时或发生外部更改后, 输入 g (magit-refresh) 显式保存并刷新.

• magit-save-repository-buffers [User Option] 此选项控制在特定事件之前是否保存访问文件的 buffers. 如果此值为非 nil, 那么属于当前仓库的所有已修改的访问文件的 buffers 可能会在运行命令之前, 创建新 Magit buffers 之前以及显式刷新此类 buffers 之前被保存. 如果此值为 dontask, 则无需用户干预即可完成此操作. 如果为 t, 则用户必须确认每次保存.

默认情况下, Magit 会自动 revert 访问 Git 仓库中被跟踪文件的 buffers, 在它们在磁盘上发生更改后. 使用 Magit 时, 经常通过运行 Git (即 "在 Emacs 外部") 更改磁盘上的文件, 这使得这成为一个相当重要的功能. 例如, 如果你在 status buffer 中 discard 一个更改, 那么这是通过运行 git apply --reverse ... 完成的, Emacs 认为文件 "在磁盘上已更改". 如果 Magit 没有自动 revert buffer, 那么你必须在访问 buffer 中输入 M-x revert-buffer RET RET 才能继续进行更改.

• magit-auto-revert-mode [User Option] 启用此模式后, 访问被跟踪文件的 buffers 会在访问的文件在磁盘上更改后自动 reverted.
• global-auto-revert-mode [User Option] 启用此模式后, 任何访问文件的 buffer 都会在访问的文件在磁盘上更改后自动 reverted. 如果你喜欢访问被跟踪文件的 buffers 自动 reverted, 那么你可能也喜欢任何 buffer 被 reverted, 而不仅仅是那些访问被跟踪文件的 buffers. 如果是这种情况, 请启用此模式而不是 magit-auto-revert-mode.
• magit-auto-revert-immediately [User Option] 此选项控制 Magit 是否立即 reverts buffers. 如果此值为非 nil 并且启用了 global-auto-revert-mode 或 magit-auto-revert-mode, 那么 Magit 会在运行 Git 产生副作用后通过显式调用 auto-revert-buffers 立即 reverts buffers. 如果 auto-revert-use-notify 为非 nil (并且实际上支持文件通知), 那么 magit-auto-revert-immediately 不必为非 nil, 因为 reverts 无论如何都会立即发生. 如果 magit-auto-revert-immediately 和 auto-revert-use-notify 均为 nil, 那么 reverts 会在 auto-revert-interval 秒的用户不活动后发生. 这是不可取的.
• auto-revert-use-notify [User Option] 此选项控制是否应使用文件通知功能. 请注意, 即使在无法使用文件通知的系统上, 此变量不幸地默认为 t.
• magit-auto-revert-tracked-only [User Option] 此选项控制 magit-auto-revert-mode 是仅 reverts 被跟踪的文件, 还是位于 Git 仓库内的所有文件, 包括未跟踪的文件和位于 Git 控制目录内的文件.
• auto-revert-mode [User Option] 全局模式 magit-auto-revert-mode 通过在适当的 buffers 中打开此局部模式来工作 (但 global-auto-revert-mode 的实现方式不同). 你也可以手动打开或关闭它, 如果 Magit 没有注意到以前未跟踪的文件现在被跟踪了, 或者反之, 这可能是必要的.
• auto-revert-stop-on-user-input [User Option] 此选项控制用户输入的到达是否会暂停自动 reverts auto-revert-interval 秒.
• auto-revert-interval [User Option] 此选项控制 Emacs 在恢复暂停的 reverts 之前等待多少秒.
• auto-revert-buffer-list-filter [User Option] 此选项指定 auto-revert-buffers 使用的附加过滤器, 以确定是否应 revert buffer. 此选项由 Magit 提供, Magit 也会 advise auto-revert-buffers 遵守它. 不自己打开局部模式 auto-revert-mode 的 Magit 用户最好将该值设置为 magit-auto-revert-repository-buffer-p. 但是默认值为 nil, 以免打扰直接使用局部模式的用户. 如果你在运行 Magit 命令时遇到延迟, 那么你应该考虑使用 Magit 提供的谓词之一 - 特别是如果你也使用 Tramp. 在 Magit 没有为他们做的 buffers 中打开 auto-revert-mode 的用户, 可能不应该使用任何过滤器. 打开 global-auto-revert-mode 的用户不必担心此选项, 因为如果启用了全局模式, 它将被忽略.
• auto-revert-verbose [User Option] 此选项控制 Emacs 是否报告 buffer 何时被 reverted.

带有 auto-revert- 前缀的选项位于名为 auto-revert 的 Custom 组中. 其他特定于 Magit 的选项位于 magit 组中.

要在 section 内移动, 请使用常规键 (C-p, C-n, C-b, C-f 等), 其全局绑定未被遮蔽. 要移动到另一个 section, 请使用以下命令.

这里描述的 section 移动命令运行 hook magit-section-movement-hook. 请注意, 它们显式运行该 hook, 而 Emacs 和其他包定义的任意其他移动不运行该 hook. 该 hook, 以及可以添加到其中或作为其默认值一部分的 hook 函数, 如下所述.

• p (magit-section-backward) 如果不在 section 的开头, 则移动到当前 section 的开头. 如果在 section 的开头, 则移动到上一个可见 section 的开头.
• n (magit-section-forward) 移动到下一个可见 section 的开头.
• M-p (magit-section-backward-siblings) 移动到上一个同级 section 的开头. 如果没有上一个同级 section, 则移动到父 section.
• M-n (magit-section-forward-siblings) 移动到下一个同级 section 的开头. 如果没有下一个同级 section, 则移动到父 section.
• ^ (magit-section-up) 移动到当前 section 的父 section 的开头.

上述命令都调用 hook magit-section-movement-hook. 下面列出的任何函数都可以用作此 hook 的成员.

你可能想删除 Magit 使用 add-hook 添加的一些函数. 在这样做时, 你必须确保你不尝试删除尚未添加的函数, 例如:

(with-eval-after-load 'magit-diff
  (remove-hook 'magit-section-movement-hook
               'magit-hunk-set-window-start))

• magit-section-movement-hook [Variable] 此 hook 由所有上述 section 移动命令在到达目的地后运行. 它不由 Emacs 或第三方包提供的任意其他移动命令 (如 next-line) 运行.
• magit-hunk-set-window-start [Function] 此 hook 函数确保当前 section 的开头是可见的, 前提它是 hunk section. 否则, 它什么也不做. 加载 magit-diff 将此函数添加到 hook.
• magit-section-set-window-start [Function] 此 hook 函数确保当前 section 的开头是可见的, 无论 section 的类型如何. 如果你将此添加到 magit-section-movement-hook, 那么你必须依次删除 hunk-only 变体.
• magit-log-maybe-show-more-commits [Function] 此 hook 函数仅在 log buffers 中有效, 并且 point 在 "show more" section 上. 如果是这种情况, 那么它会将显示的提交数量加倍. 加载 magit-log 将此函数添加到 hook.
• magit-log-maybe-update-revision-buffer [Function] 在 log buffer 内移动时, 此函数会更新 revision buffer, 前提是它已在同一 frame 的另一个窗口中显示. 加载 magit-log 将此函数添加到 hook.
• magit-log-maybe-update-blob-buffer [Function] 在 log buffer 内移动且同一 frame 的另一个窗口显示 blob buffer 时, 此函数会在该窗口中显示 point 处 commit 的 blob buffer.
• magit-status-maybe-update-revision-buffer [Function] 在 status buffer 内移动时, 此函数会更新 revision buffer, 前提是它已在同一 frame 的另一个窗口中显示.
• magit-status-maybe-update-stash-buffer [Function] 在 status buffer 内移动时, 此函数会更新 stash buffer, 前提是它已在同一 frame 的另一个窗口中显示.
• magit-status-maybe-update-blob-buffer [Function] 在 status buffer 内移动且同一 frame 的另一个窗口显示 blob buffer 时, 此函数会在该窗口中显示 point 处 commit 的 blob buffer.
• magit-stashes-maybe-update-stash-buffer [Function] 在列出 stashes 的 buffer 内移动时, 此函数会更新 stash buffer, 前提是它已在同一 frame 的另一个窗口中显示.
• magit-update-other-window-delay [User Option] 自动更新另一个窗口之前的延迟. 使用 Magit 自己的 section 移动命令 (但不是其他移动命令) 在某些 buffers 中移动时, 可以选择性地更新在另一个窗口中显示的某些其他 buffers, 以显示有关 point 处 section 的信息. 当按住键移动超过一个 section 时, 这将为途中的每个 section 更新该 buffer. 为了防止这种情况, 更新 revision buffer 会延迟, 此选项控制延迟多长时间. 为了获得最佳体验, 你可能需要调整此延迟和/或图形环境或操作系统的键盘重复率和延迟.

Magit 提供了许多用于更改 sections 可见性的命令, 但你只需要接下来的两个即可开始使用.

• TAB (magit-section-toggle) 切换当前 section 主体的可见性.
• C-c TAB (magit-section-cycle)
• C-<tab> (magit-section-cycle) 循环当前 section 及其子项的可见性. 如果使用 C-<tab> 调用此命令, 并且该键全局绑定到 tab-next, 那么此命令将转向表现得像那个命令, 你必须改为使用 C-c TAB 来循环 section 可见性. 如果你想继续使用 C-<tab> 循环 section 可见性, 但也想使用 tab-bar-mode, 那么你必须阻止该模式使用此键, 并将另一个键绑定到 tab-next. 因为 tab-bar-mode 不使用模式映射而是操纵全局映射, 这涉及 advising tab-bar--define-keys.
• M-<tab> (magit-section-cycle-diffs) 循环当前 buffer 中 diff 相关 sections 的可见性.
• S-<tab> (magit-section-cycle-global) 循环当前 buffer 中所有 sections 的可见性.
• 1 (magit-section-show-level-1)
• 2 (magit-section-show-level-2)
• 3 (magit-section-show-level-3)
• 4 (magit-section-show-level-4) 显示当前 section 周围直到 N 级的 sections.
• M-1 (magit-section-show-level-1-all)
• M-2 (magit-section-show-level-2-all)
• M-3 (magit-section-show-level-3-all)
• M-4 (magit-section-show-level-4-all) 显示所有 sections 直到 N 级.

一些用于实现上述命令的函数也作为命令本身公开. 默认情况下, 没有键绑定到这些命令, 因为它们通常被认为不太有用. 但你的情况可能有所不同.

• magit-section-show [Command] 显示当前 section 的主体.
• magit-section-hide [Command] 隐藏当前 section 的主体.
• magit-section-show-headings [Command] 递归显示当前 section 子项的标题. 仅显示标题. 以前显示的纯文本主体将被隐藏.
• magit-section-show-children [Command] 递归显示当前 section 子项的主体. 带有前缀参数时, 显示子项直到当前 section 的层级, 并隐藏更深的子项.
• magit-section-hide-children [Command] 递归隐藏当前 section 子项的主体.
• magit-section-toggle-children [Command] 切换当前 section 子项主体的可见性.

当 buffer 首次创建时, 一些 sections 显示为展开, 而其他则不显示. 这是硬编码的. 当 buffer 刷新时, 保留先前的可见性. 某些 sections 的初始可见性也可以使用 hook magit-section-set-visibility-hook 覆盖.

• magit-section-initial-visibility-alist [User Option] 此选项可用于覆盖 sections 的初始可见性. 将来它也将用于定义默认值, 但目前 section 的默认值仍是硬编码的. 值为一个 alist. 每个元素将 section 类型或谱系映射到此类 sections 的初始可见性状态. 状态必须是 show 或 hide 之一, 或返回这些符号之一的函数. 函数将 section 作为唯一参数调用. 使用命令 magit-describe-section-briefly 确定 section 的谱系或类型. 输出中的向量是 section 谱系, 类型是该向量的第一个元素. 可以使用通配符, 参见 magit-section-match.
• magit-section-cache-visibility [User Option] 此选项控制如果 section 消失并在稍后再次出现, 是否应恢复其先前的可见性状态. 值为布尔值或 section 类型的列表. 如果为 t, 则缓存所有 sections 的可见性. 否则仅针对类型与列出的类型之一匹配的 sections 执行此操作. 这要求函数 magit-section-cached-visibility 是 magit-section-set-visibility-hook 的成员.
• magit-section-set-visibility-hook [Variable] 此 hook 在首次创建 buffer 时以及刷新现有 buffer 时运行, 用于确定当前插入的 section 的可见性. 每个函数都带有一个参数 (正在插入的 section) 调用. 它应该返回 hide 或 show, 或者 nil 以保持可见性未定义. 如果没有函数决定可见性并且 buffer 正在刷新, 则保留可见性; 或者如果正在创建 buffer, 则使用硬编码的默认值. 通常这应该仅用于设置初始可见性, 而不在刷新期间使用. 如果 magit-insert-section--oldroot 为非 nil, 则 buffer 正在刷新, 这些函数应立即返回 nil.
• magit-section-visibility-indicators [User Option] 此选项控制是否以及如何指示 section 可以展开/折叠. 如果为 nil, 则不显示任何指示器. 否则值必须是一个包含两个元素的列表. 第一个控制图形 frames 中使用的指示器, 第二个控制终端 frames 中的指示器. 对于图形 frames, 以下所有形式均有效, 而终端 frames 没有 fringes, 因此不支持第一种形式.

  • (EXPANDABLE-BITMAP . COLLAPSIBLE-BITMAP) 这两个值必须是值为 fringe bitmaps 的变量. 在这种情况下, 每个可以展开或折叠的 section 在左 fringe 中都有一个指示器. 要在指示器周围提供额外的填充, 请在 magit-mode-hook 中设置 left-fringe-width, 例如:

    (add-hook 'magit-mode-hook
              (lambda () (setq left-fringe-width 20)))
    

  • (EXPANDABLE-CHAR . COLLAPSIBLE-CHAR) 在这种情况下, 每个可以展开或折叠的 section 在左 margin 中都有一个指示器.
  • (STRING . BOOLEAN) 在这种情况下, STRING (通常是省略号) 显示在每个折叠 section 的标题末尾. 展开的 sections 没有指示器. cdr 控制省略号的外观是否考虑 section 高亮. 这样做可能会对性能产生影响, 而不这样做有点丑陋.

哪些 sections 被插入到某些 buffers 中是由 hooks 控制的. 这包括 status 和 refs buffers. 对于其他 buffers, 例如 log 和 diff buffers, 这是不可能的. 命令 magit-describe-section 可用于查看哪个 hook (如果有) 负责在 point 处插入 section.

对于其 sections 可以由用户自定义的 buffers, 存在一个名为 magit-TYPE-sections-hook 的 hook 变量. 应使用 magit-add-section-hook 更改此 hook. 避免使用 add-hooks 或 Custom 接口.

各种可用的 section hook 变量将在本手册后面与相应的 "section 插入函数" 一起描述.

• magit-add-section-hook hook function &optional at append local [Function] 将函数 FUNCTION 添加到 section hook HOOK 的值中. 除非可选的 APPEND 为非 nil, 否则在 hook 列表的开头添加 FUNCTION, 在这种情况下, FUNCTION 添加在末尾. 如果 FUNCTION 已经是成员, 则将其移动到新位置. 如果可选的 AT 为非 nil 且是 hook 列表的成员, 则改为在其旁边添加 FUNCTION. 根据 APPEND 在 AT 之前或之后添加, 或者如果 APPEND 是符号 replace, 则用 FUNCTION 替换 AT. 对于任何其他非 nil 值, 将 FUNCTION 放在 AT 之后. 如果为 nil, 则将 FUNCTION 放在 AT 之前. 如果 FUNCTION 已经是列表的成员但 AT 不是, 则将 FUNCTION 留在原地. 如果可选的 LOCAL 为非 nil, 则修改 hook 的 buffer-local 值而不是其全局值. 这通过复制默认值使 hook 变为 local. 然后修改该副本. HOOK 应该是一个符号. 如果 HOOK 为 void, 则首先将其设置为 nil. HOOK 的值不能是单个 hook 函数. FUNCTION 应该是一个不带参数并在 point 处插入一个或多个 sections 并向前移动 point 的函数. 当插入 section 没有意义时, FUNCTION 可以选择不插入它的 section(s). 它不应该被滥用于其他副作用.

要从 section hook 中删除函数, 请使用 remove-hook.

每个 section 都有一个类型, 例如 hunk, file 和 commit. 某些 section 类型的实例也有一个值. 例如, file 类型 section 的值是一个文件名.

用户通常不必担心 section 的类型和值, 但有时了解它们会很方便.

• H (magit-describe-section) 此命令在一个单独的 buffer 中显示有关 point 处 section 的信息.
• magit-describe-section-briefly [Command] 此命令在 echo area 中显示有关 point 处 section 的信息, 格式为 #<magit-section VALUE [TYPE PARENT-TYPE...] BEGINNING-END>.

许多命令根据 point 处 section 的类型表现不同和/或以某种方式使用该 section 的值. 但这只是同一按键根据当前 section 执行不同操作的原因之一.

此外, 可能会为每种 section 类型定义一个 keymap, 命名为 magit-TYPE-section-map. 该 keymap 用作属于相应类型任何 section 的所有文本的文本属性 keymap. 如果某种类型不存在这样的 map, 那么你可以自己定义它, 它会被自动使用.

本节描述了对不仅仅某种类型 sections 有影响的选项. 正如你所见, 这样的选项并不多.

• magit-section-show-child-count [User Option] 是否将子项数量附加到 section 标题. 这仅影响可以从这些信息中受益的 sections.

默认情况下, 许多可能导致数据丢失的操作都必须得到确认. 这包括许多非常常见的操作, 因此这可能很快变得烦人. 许多这些操作可以撤消, 如果你考虑过如何撤消某些错误, 那么禁用相应操作的确认应该是安全的.

选项 magit-no-confirm 可用于告诉 Magit 执行某些操作而无需用户确认. 请注意, 虽然此选项仅用于禁用特定操作集的确认, 但下一节将解释另一种告诉 Magit 少问问题的方法.

• magit-no-confirm [User Option] 此选项的值是一个符号列表, 代表在执行之前无需用户确认的操作. 默认情况下, 许多潜在危险的命令会要求用户确认. 下面的每个符号都代表一个操作, 当无意中调用或未完全意识到后果时, 可能会导致流泪. 在许多情况下, 有几个命令执行某个操作的变体, 因此我们不使用命令名称, 而是使用更通用的符号.

  • 应用更改:
    • discard: 丢弃一个或多个更改 (即 hunks 或文件的完整 diff) 会丢失该更改, 很明显.
    • reverse: Reverting 一个或多个更改通常可以通过 reverting reversion 来撤消.
    • stage-all-changes, unstage-all-changes: 当同时存在 staged 和 unstaged 更改时, un-/staging 所有内容会破坏这种区别. 当然这也适用于 un-/staging 单个更改时, 但那时损失较小, 并且人们经常这样做, 每次都必须确认是不可接受的.
  • 文件:
    • delete: 当删除 Git 尚未跟踪的文件时, 它将完全丢失, 而不仅仅是最后的更改. 非常危险.
    • trash: 也可以将其移动到系统垃圾箱, 而不是删除文件. 显然比删除它危险性小得多. 另请参见选项 magit-delete-by-moving-to-trash.
    • resurrect: 删除的文件可以通过 "删除" 删除来轻松恢复, 这使用与最初用于删除该文件的相同命令来完成.
    • untrack: Untracking 一个文件可以通过再次 tracking 它来撤消.
    • rename: 重命名文件很容易撤消.
  • 序列:
    • reset-bisect: 中止 (Git 称为 "resetting") bisect 操作会丢失迄今为止收集的所有信息.
    • abort-cherry-pick: 中止 cherry-pick 会丢弃用户已经执行的所有冲突解决.
    • abort-revert: 中止 revert 会丢弃用户已经执行的所有冲突解决.
    • abort-rebase: 中止 rebase 会丢弃所有已修改的 commits, 但可以从 reflog 恢复这些 commits.
    • abort-merge: 中止 merge 会丢弃用户已经执行的所有冲突解决.
    • merge-dirty: 使用 dirty worktree 进行合并可能很难回到合并启动前的状态.
  • 引用:
    • delete-unmerged-branch: 一旦删除了分支, 只能使用 Git 提供的低级恢复工具来恢复. 甚至 reflog 也消失了. 用户总是必须通过接受默认选择 (或选择另一个分支) 来确认删除分支, 但当分支尚未合并时, 还要确保用户意识到这一点.
    • delete-pr-remote: 当删除从 pull-request 创建的分支时, 如果该 remote 上没有其他分支仍然存在, 那么 magit-branch-delete 提议也删除该 remote. 这应该是安全的, 因为它仅在 remotes 命名空间中不存在其他 refs 时发生, 并且如果需要, 你可以重新创建 remote.
    • drop-stashes: Dropping stash 是危险的, 因为 Git 将 stashes 存储在 reflog 中. 一旦删除了 stash, 不使用 Git 提供的低级恢复工具就无法恢复. 当 drop 单个 stash 时, 用户总是必须通过接受默认值 (或选择另一个) 来确认. 此操作仅涉及一次删除多个 stashes.
  • Publishing:
    • set-and-push: 当 push 到 upstream 或 push-remote 且实际上尚未配置时, 用户可以先设置目标. 如果他/她过快确认默认值, 那么他/她最终可能会 push 到错误的分支, 如果远程仓库配置为不允许修复此类错误, 那么这可能会非常尴尬和恼人.

  • 编辑已发布历史: 如果不在此处添加这些符号, 在编辑已推送到 magit-published-branches 中列出的分支之一的 commits 之前, 你将收到警告.

    • amend-published: 影响大多数 amend 到 "HEAD" 的命令.
    • rebase-published: 影响执行交互式 rebases 的命令. 这包括来自 commit transient 的修改 "HEAD" 以外 commit 的命令, 即各种 fixup 和 squash 变体.
    • edit-published: 影响命令 magit-edit-line-commit 和 magit-diff-edit-hunk-commit. 这两个命令使得很容易意外编辑已发布的 commit, 所以在配置它们不要求确认之前你应该三思.

    要完全禁用确认, 请在此处添加所有三个符号或将 magit-published-branches 设置为 nil.

  • 各种:
    • stash-apply-3way: 当不能使用 git stash apply 应用 stash 时, Magit 改用 git apply, 可能使用 --3way 参数, 这并不总是完全安全的. 另请参见 magit-stash-apply.
    • kill-process: 很少有理由 kill 一个进程.
  • 全局设置: 你可以将其设置为原子 t, 而不是将所有上述符号添加到此选项的值中, 这具有与添加所有上述符号相同的效果. 这样做肯定是一个坏主意, 特别是因为将来可能会添加其他符号. 所以即使你不想被要求确认任何这些操作, 你最好还是单独添加所有相应的符号.

  当启用 magit-wip-before-change-mode 时, 以下操作可以相当容易地撤消: discard, reverse, stage-all-changes 和 unstage-all-changes. 当且仅当启用了此模式时, safe-with-wip 具有与单独添加所有这些符号相同的效果.

许多 Magit 命令要求用户从可能的操作对象列表中进行选择, 同时提供最可能的选择作为默认值. 对于许多这些命令, 默认值是 point 处的对象, 前提是它实际上是一个有效的操作对象. 对于许多作用于分支的命令, 如果 point 处没有分支, 则当前分支用作默认值.

这些命令将询问确认和询问操作目标结合到一个动作中. 用户可以使用 RET 确认默认目标或使用 C-g 中止. 这类似于 y-or-n-p 提示, 但确认或中止的键不同.

同时, 用户也有机会选择另一个目标, 这很有用, 因为对于某些命令和/或在某些情况下, 你可能想在通过移动到目标选择它之前先选择动作.

但是你可能会发现, 对于某些命令, 你总是想使用默认目标 (如果有), 或者甚至你希望命令对默认值进行操作而无需任何确认. 选项 magit-dwim-selection 可用于配置某些命令以实现该效果.

注意, 当 region 处于活动状态时, 许多命令作用于使用基于 region 的机制选定的对象, 在许多情况下会询问确认. 这种基于 region 的机制称为 "selection" (选择), 下一节将详细描述. 当存在对调用的命令有效的 selection 时, 该命令从不提议对其他东西进行操作, 并且它是否要求确认不受此选项控制.

另请注意, Magit 会要求确认某些不与补全 (或 selection) 耦合的操作. 此类对话框也不受此选项影响, 并在上一节中进行了描述.

• magit-dwim-selection [User Option] 此选项可用于告诉某些命令使用 point 处的对象, 而不是要求用户选择要操作的候选对象, 无论是否确认. 值的形式为 ((COMMAND nil|PROMPT DEFAULT)...).
  • COMMAND 是不应提示选择的命令. 要产生效果, 该命令必须使用函数 magit-completing-read 或使用该函数的实用程序函数.
  • 如果命令多次使用 magit-completing-read, 那么 PROMPT 可用于仅影响其中一种使用. PROMPT 如果为非 nil, 是一个正则表达式, 用于匹配传递给 magit-completing-read 的 PROMPT 参数.
  • DEFAULT 指定如何使用默认值. 如果为 t, 则无需确认即可使用传递给 magit-completing-read 的 DEFAULT 参数. 如果为 ask, 则给用户中止的机会. DEFAULT 也可以为 nil, 在这种情况下条目无效.

如果 region 处于活动状态, 那么许多 Magit 命令将作用于使用基于 region 的机制选定的对象, 而不是单个对象. 当 region 不处于活动状态时, 这些命令作用于 point 处的对象或读取单个操作对象. 这在上一节中已有描述–本节仅涵盖如何选择多个对象, 如何将其可视化, 以及在这种情况下某些命令的行为方式.

Magit 的多对象选择机制 (或者更确切地说是代表这些对象的 sections) 基于 Emacs region, 但 Magit 认为选定的区域通常比 region 更大, 并且适用额外的限制.

Magit 区分有资格形成有效 Magit selection 的 region 和没有资格的 region. 如果 region 不符合资格, 则按其在其他 Emacs buffers 中的方式显示. 如果 region 确实符合 Magit selection 的资格, 则 selection 始终可视化, 而 region 本身仅在开始和结束于同一行时才可视化.

为了使 region 有资格作为 Magit selection, 它必须从一个 section 的标题开始, 并在同级 section 的标题结束. 注意, 如果 region 的结束处于 section 标题的最开始 (即, 在一行的最开始), 那么该 section 被认为在 selection 内.

这与 Emacs 中通常处理 region 的方式不一致–如果 region 在一行的开头结束, 那么该行在 region 之外. 由于 Magit 如何可视化 selection, 这种差异应该是显而易见的.

并非每个命令都对每个有效的 selection 起作用. 有些命令甚至不考虑 point 的位置, 其他命令可能作用于 point 处的 section 但不支持作用于 selection, 即使支持 selection 的命令当然也只有在它选择了它们可以操作的对象时才这样做.

这是 selection 必须包含 point 处 section 的主要原因. 即使存在 selection, 调用的命令也可能会忽略它, 在这种情况下它可能只作用于当前 section. 仅对当前 section 进行操作而不对其他选定的 sections 进行操作, 比对当前 section 进行操作而不是选定的 sections 进行操作要安全得多. 后者会非常令人惊讶, 如果当前 section 始终是 selection 的一部分, 那么这种情况就不会发生.

• magit-keep-region-overlay [Variable] 此变量控制即使存在有效的 Magit selection 或 hunk-internal region, region 是否也照常可视化. 有关更多信息, 请参阅 doc-string.

与上一节描述的 Magit selection 有些相关的是 hunk-internal region (块内区域).

像 selection 一样, hunk-internal region 基于 Emacs region, 但会导致该 region 不像在其他 Emacs buffers 中那样可视化, 并且即使它在行的最开始结束, 也包括 region 结束的那一行.

与基于必须从一个 section 的标题开始并在同级 section 的 section 结束的 region 的 selection 不同, hunk-internal region 必须从 hunk section 的主体 内 开始, 并在 同一 section 的主体中结束.

"Apply" 命令遵循 hunk-internal region, 这些命令除其他目标外还可以作用于 hunk. 如果 hunk-internal region 处于活动状态, 那么此类命令仅作用于 hunk 的标记部分, 而不是完整的 hunk.

内置选项 completing-read-function 指定 completing-read 用于要求用户从选项列表中进行选择的低级函数. 其默认值为 completing-read-default. 替代补全框架通常通过替换其自己的实现来激活自身.

主要是出于历史原因, Magit 提供了一个类似的名为 magit-completing-read-function 的选项, 它仅控制 magit-completing-read 使用的低级函数. 此选项还可以为 Magit 使用与 Emacs 其余部分不同的补全机制, 但不建议这样做.

你很可能不必自定义 Magit 特定选项来使用替代补全框架. 例如, 如果你启用了 ivy-mode, 那么 Magit 将尊重它, 如果你启用了 helm-mode, 那么你也完成了.

• magit-completing-read-function [User Option] 此变量的值是由使用 magit-completing-read (相对于内置 completing-read) 的代码用于执行补全的低级函数. 默认值 magit-builtin-completing-read 至少适用于标准补全机制, ivy-mode 和 helm-mode. 内置 completing-read 和 completing-read-default 不适合在此处使用. magit-builtin-completing-read 执行一些额外的工作, 任何用来代替它的函数也必须做同样的事情.
• magit-builtin-completing-read prompt choices &optional predicate require-match initial-input hist def [Function] 此函数使用内置 completing-read 执行补全, 并做一些额外的 Magit 特定工作.

• magit-completing-read prompt choices &optional predicate require-match initial-input hist def fallback [Function] 这是 Magit 命令在需要用户选择单个操作对象时使用的函数. 参数含义与 completing-read 相同, 除了 FALLBACK, 它是此函数独有的, 如下所述. 此函数可能不要求用户从可能的候选列表中进行选择, 而是仅返回 DEF 指定的默认值, 无论是否需要用户确认. 是否如此取决于 PROMPT, this-command 和 magit-dwim-selection. 有关更多信息, 请参阅后者的文档.

  如果在 minibuffer 中读取值, 则此函数的行为类似于 completing-read, 除了以下几点:

  • COLLECTION 必须是选项列表. 不支持函数.
  • 如果 REQUIRE-MATCH 为 nil 且用户未选择退出, 则返回 nil 而不是空字符串.
  • 如果 REQUIRE-MATCH 为 any, 则不需要匹配但需要非空输入 (或非 nil DEFAULT, 因为它被替换为空输入).
  • 如果 REQUIRE-MATCH 为非 nil 且用户未选择退出, 则引发用户错误.
  • FALLBACK 指定仅在主要默认值 DEF 为 nil 时使用的辅助默认值. 辅助默认值不受 magit-dwim-selection 的影响–如果 DEF 为 nil 但 FALLBACK 不为 nil, 那么此函数总是要求用户选择一个候选者, 就像两个默认值都为 nil 一样.
  • 在 PROMPT 和 DEF (如果 DEF 为 nil 则为 FALLBACK) 上调用 format-prompt. 这会将 ": " 附加到提示, 并且还可能将默认值添加到提示, 使用 minibuffer-default-prompt-format 指定的格式并取决于 magit-completing-read-default-prompt-predicate.

• magit-list-refs-sortby [User Option] 对于许多从用户读取 ref 或 refs 的命令, 此选项的值可用于控制 refs 的顺序. 有效值包括 git for-each-ref 的 --sort 标志接受的任何键. 默认情况下, refs 按其全名按字母顺序排序 (例如, "refs/heads/master").

Magit 运行 Git 要么是为了副作用 (例如, 推动时), 要么是为了获取一些值 (例如, 当前分支的名称).

当运行 Git 产生副作用时, 进程输出会记录在每个仓库的 log buffer 中, 当事情没有按预期进行时, 可以使用 magit-process-buffer 命令查阅.

保留多达 magit-process-log-max 个 Git 命令的输出/错误.

• $ (magit-process-buffer) 此命令显示当前仓库的 process buffer.

在该 buffer 内, 用于导航和显示 sections 的常用键绑定可用. 还有一个额外的命令.

• k (magit-process-kill) 此命令 kill (杀死) point 处 section 代表的进程.
• M-x magit-toggle-git-debug 此命令切换是否报告额外的 git 错误. Magit 基本上出于两个原因之一调用 git: 为了副作用或对其标准输出做某事. 当运行 git 产生副作用时, 其输出 (包括错误消息) 进入 process buffer, 使用 $ 时会显示该 buffer. 当 git 的输出以某种方式被消耗时, 将其也插入此 buffer 会太昂贵, 但是使用此命令可以暂时启用. 在这种情况下, 如果 git 以非零退出状态返回, 那么至少将其标准错误插入此 buffer. 还要注意, 仅仅因为 git 以非零状态退出并打印错误消息, 通常并不意味着就 Magit 而言这是一个错误, 这也是我们通常隐藏这些错误消息的另一个原因. 某些错误消息是否与某些意外行为相关, 必须根据具体情况进行判断.

当 Git 进程为副作用运行时, Magit 在 mode line 中使用 magit-mode-line-process face 显示一个指示器.

如果 Git 进程成功退出, 进程指示器将立即从 mode line 中移除.

在 Git 错误的情况下, 进程指示器不会被移除, 而是用 magit-mode-line-process-error face 高亮显示, 并且来自 process buffer 的错误详情作为工具提示提供给鼠标用户. 此错误指示器保留在 mode line 中, 直到下一次 magit buffer 刷新.

如果你不希望在 mode line 中指示进程错误, 请将 magit-process-display-mode-line-error 设置为 nil.

进程错误显示在 status buffer 的顶部和 echo area 中. 在这两个地方都附加了一个提示, 通知用户他们可以在 process buffer 中看到完整的输出以及如何显示该 buffer. 但是, 一旦你意识到了这一点, 你可能想将 magit-show-process-buffer-hint 设置为 nil.

虽然 Magit 提供了许多 Emacs 命令与 Git 交互, 但它并没有涵盖所有内容. 在这些情况下, 你现有的 Git 知识将派上用场. Magit 提供了一些命令, 通过在 minibuffer 中输入任意 Git 命令来运行它们, 而不必切换到 shell.

• ! (magit-run) 此 transient prefix 命令绑定以下 suffix 命令, 并在临时 buffer 中显示它们, 直到调用 suffix.
• ! ! (magit-git-command-topdir) 此命令从用户读取命令并在当前工作树的顶层目录中执行它. 字符串 "git " 用作提示用户输入命令时的初始输入. 可以将其删除以运行其他命令.
• : (magit-git-command)
• ! p 此命令从用户读取命令并在 default-directory 中执行它. 带有前缀参数时, 命令改为在当前工作树的顶层目录中执行. 字符串 "git " 用作提示用户输入命令时的初始输入. 可以将其删除以运行其他命令.
• ! s (magit-shell-command-topdir) 此命令从用户读取命令并在当前工作树的顶层目录中执行它.
• ! S (magit-shell-command) 此命令从用户读取命令并在 default-directory 中执行它. 带有前缀参数时, 命令改为在当前工作树的顶层目录中执行.
• magit-shell-command-verbose-prompt [User Option] 上述命令在读取 shell 命令时使用的提示是否显示将在其中运行它的目录.

这些 suffix 命令启动外部 GUI 工具.

• ! k (magit-run-gitk) 此命令在当前仓库中运行 gitk.
• ! a (magit-run-gitk-all) 此命令在当前仓库中运行 gitk --all.
• ! b (magit-run-gitk-branches) 此命令在当前仓库中运行 gitk --branches.
• ! g (magit-run-git-gui) 此命令在当前仓库中运行 git gui.
• ! m (magit-git-mergetool) 此命令在当前仓库中运行 git mergetool --gui. 带有前缀参数时, 这充当 transient prefix 命令, 允许用户选择 mergetool 并更改一些设置.

当 Magit 调用 Git 时, 它可以使用 git 可执行文件的绝对路径, 或者仅使用其名称.

当在本地运行 git 且 system-type 为 windows-nt (任何 Windows 版本) 或 darwin (macOS) 时, 加载 Magit 时 magit-git-executable 设置为绝对路径.

在 Windows 上, 必须使用绝对路径, 因为 Git 附带了几个用于实际 git 二进制文件的 wrapper 脚本, 这些脚本也放置在 $PATH 上, 使用这些 wrappers 之一而不是二进制文件会严重降低性能. 对于某些 macOS 用户, 仅使用可执行文件的名称同样性能极差, 因此我们也避免在该平台上这样做. 在其他平台上, 仅使用名称似乎工作正常.

在通过 Tramp 在远程机器上运行 git 时使用绝对路径, 使用适合本地机器的绝对路径会有问题, 因此使用单独的选项来控制在远程机器上使用的名称或路径.

• magit-git-executable [User Option] Magit 在本地主机上使用的 git 可执行文件. 这应该是可执行文件的绝对路径, 或者是字符串 "git" 以让 Emacs 自己找到可执行文件, 使用做这类事情的标准机制.
• magit-remote-git-executable [User Option] Magit 在通过 Tramp 的远程机器上使用的 git 可执行文件. 通常这应该只是字符串 "git". 考虑自定义 tramp-remote-path 而不是此选项.

如果 Emacs 无法找到正确的可执行文件, 那么你可以通过显式设置这两个选项之一的值来解决此问题. 这样做应该被视为一种权宜之计; 最好确保 exec-path 或 tramp-remote-path 中的顺序正确.

注意 exec-path 是基于 Emacs 启动时有效的 PATH 环境变量的值设置的. 如果你在 shell 的 init 文件中设置 PATH, 那么只有当你从该 shell 启动 Emacs 时才会对 Emacs 产生影响 (因为进程的环境只传递给其子进程, 而不传递给任意其他进程). 如果这不是你启动 Emacs 的方式, 那么 exec-path-from-shell 包可能会有所帮助; 虽然老实说我也认为这是一种权宜之计.

命令 magit-debug-git-executable 可用于找出 Emacs 在哪里搜索 git.

• M-x magit-debug-git-executable 此命令显示一个 buffer, 其中包含有关 magit-git-executable 和 magit-remote-git-executable 的信息.
• M-x magit-version 此命令在 echo area 中显示当前使用的 Magit, Git 和 Emacs 版本. 非交互式地这只返回 Magit 版本.

• magit-git-global-arguments [User Option] 此处设置的参数在每次 git 可执行文件作为子进程运行时使用. 它们放置在可执行文件本身之后和 git 命令之前 - 如 git HERE... COMMAND REST. 有关有效参数, 请参阅 git(1) manpage. 小心你在这里添加的内容, 特别是如果你使用 Tramp 连接到具有古老 Git 版本的服务器. 除非你真的知道你在做什么, 否则永远不要删除默认值的一部分. 并且在添加任何内容之前要非常仔细地考虑; 每次 Magit 出于任何目的运行 Git 时都会使用它.

Status buffers 的内容使用 hook magit-status-sections-hook 控制. 参见第 19 页的 [Section Hooks], 了解有关此类 hooks 以及如何自定义它们的信息.

• magit-status-sections-hook [User Option] 此 hook 运行以将 sections 插入 status buffer. 本节中描述的函数, 以及后续章节中描述的函数 magit-insert-status-headers 和 magit-insert-untracked-files, 都是此 hook 的成员. 可以添加到此 hook 的一些其他函数 (默认添加到其他 hooks) 列在第 57 页的 5.6 节 [References Buffer] 中.
• magit-insert-status-headers [Function] 插入适用于 magit-status-mode buffers 的 header sections. 通过运行 magit-status-headers-hook hook 上的函数来插入 sections. 参见第 37 页的 [Status Header Sections].
• magit-insert-merge-log [Function] 为正在进行的合并插入 section. 显示正在合并的 heads. 如果没有正在进行的合并, 则什么也不做.
• magit-insert-rebase-sequence [Function] 为正在进行的 rebase 序列插入 section. 如果没有此类序列正在进行, 则什么也不做.
• magit-insert-am-sequence [Function] 为正在进行的补丁应用序列插入 section. 如果没有此类序列正在进行, 则什么也不做.
• magit-insert-sequencer-sequence [Function] 为正在进行的 cherry-pick 或 revert 序列插入 section. 如果没有此类序列正在进行, 则什么也不做.
• magit-insert-bisect-output [Function] 在 bisecting 时, 插入包含 git bisect 输出的 section.
• magit-insert-bisect-rest [Function] 在 bisecting 时, 插入可视化 bisect 状态的 section.
• magit-insert-bisect-log [Function] 在 bisecting 时, 插入记录 bisect 进度的 section.
• magit-insert-unstaged-changes [Function] 插入显示 unstaged 更改的 section.
• magit-insert-staged-changes [Function] 插入显示 staged 更改的 section.
• magit-insert-stashes &optional ref heading [Function] 插入 stashes section, 显示 "refs/stash" 的 reflog. 如果可选的 REF 为非 nil, 则显示该 ref 的 reflog. 如果可选的 HEADING 为非 nil, 则使用它作为 section 标题, 而不是 "Stashes:".
• magit-insert-unpulled-from-upstream [Function] 插入显示尚未从 upstream 分支 pull 的提交的 section.
• magit-insert-unpulled-from-pushremote [Function] 插入显示尚未从 push-remote 分支 pull 的提交的 section.
• magit-insert-unpushed-to-upstream-or-recent [Function] 插入显示 unpushed 或其他最近提交的 section. 如果当前分支配置了 upstream 并且落后于当前分支, 则显示尚未 push 到 upstream 分支的提交. 如果未配置 upstream 或 upstream 不落后于当前分支, 则显示最后的 magit-log-section-commit-count 个提交.
• magit-insert-unpushed-to-upstream [Function] 插入显示尚未 push 到 upstream 的提交的 section.
• magit-insert-unpushed-to-pushremote [Function] 插入显示尚未 push 到 push-remote 的提交的 section.

这些函数遵循 buffer 的文件过滤器, 可以使用 D - - 设置.

• magit-insert-untracked-files [Function] 此函数可能会插入未跟踪文件的列表. 是否实际这样做取决于下一个描述的选项.

• magit-status-show-untracked-files [User Option] 此选项控制上述函数是否在 status buffer 中插入未跟踪文件的列表.

  • 如果为 nil, 不列出任何未跟踪文件.
  • 如果为 t, 列出未跟踪文件, 但如果目录不包含任何被跟踪文件, 则仅列出该目录, 而不列出包含的未跟踪文件.
  • 如果为 all, 则列出每个单独的未跟踪文件. 这可能非常慢, 不建议使用.

  Git 变量的对应值为 "no", "normal" 和 "all". 要在特定仓库中禁用列出未跟踪文件, 请将以下内容添加到 .dir-locals.el:

  ((magit-status-mode
    (magit-status-show-untracked-files . "no")))
  

  或者 (主要是出于历史原因), 可以使用 git config 设置仓库本地值: git config set --local status.showUntrackedFiles no 这不会覆盖此 Lisp 变量的 (如果有) 本地值, 但它确实会覆盖其全局值. 参见 git-status(1) manpage 的最后一节, 以加快 Git 负责的工作部分. 将该列表转换为 sections 也不是免费的, 因此 Magit 仅列出 magit-status-file-list-limit 个文件.

• magit-status-file-list-limit [User Option] 此选项控制在 status buffer 中列出文件的每个 section 中最多列出多少个文件. 出于性能原因, 建议不要增加此限制.

虽然上述函数默认是 magit-status-section-hook 的成员, 但必须由用户显式添加以下函数. 因为这会对性能产生负面影响, 建议不要这样做.

• magit-insert-tracked-files [Function] 插入被跟踪文件的列表.
• magit-insert-ignored-files [Function] 插入被忽略文件的列表.
• magit-insert-skip-worktree-files [Function] 插入 skip-worktree 文件的列表.
• magit-insert-assume-unchanged-files [Function] 插入假定未更改文件的列表.

• magit-insert-unpulled-or-recent-commits [Function] 插入显示 unpulled 或最近提交的 section. 如果当前分支配置了 upstream 并且领先于当前分支, 则显示缺失的提交. 否则, 显示最后的 magit-log-section-commit-count 个提交.
• magit-insert-recent-commits [Function] 插入显示最后 magit-log-section-commit-count 个提交的 section.
• magit-log-section-commit-count [User Option] magit-insert-recent-commits 和 magit-insert-unpulled-or-recent-commits (如果没有 unpulled 提交) 显示多少个最近提交.
• magit-insert-unpulled-cherries [Function] 插入显示 unpulled 提交的 section. 类似于 magit-insert-unpulled-commits, 但为每个尚未应用的提交 (即, 具有不与任何本地提交共享 patch-id 的提交) 加上 "+" 前缀, 所有其他的加上 "-" 前缀.
• magit-insert-unpushed-cherries [Function] 插入显示 unpushed 提交的 section. 类似于 magit-insert-unpushed-commits, 但为每个尚未应用到 upstream 的提交 (即, 具有不与任何 upstream 提交共享 patch-id 的提交) 加上 "+" 前缀, 所有其他的加上 "-" 前缀.

Status buffers 的内容使用 hook magit-status-sections-hook 控制 (见第 34 页的 [Status Sections]).

默认情况下 magit-insert-status-headers 是该 hook 变量的第一个成员.

• magit-insert-status-headers [Function] 插入适用于 magit-status-mode buffers 的 headers sections. 通过运行 magit-status-headers-hook hook 上的函数来插入 sections.
• magit-status-headers-hook [User Option] 运行此 hook 以将 headers sections 插入 status buffer. 此 hook 由 magit-insert-status-headers 运行, 而后者必须是 magit-status-sections-hook 的成员才能被使用.

默认情况下, 以下函数是上述 hook 的成员:

• magit-insert-error-header [Function] 插入显示刚刚发生的 Git 错误消息的 header line. 此函数仅知道 Git 为副作用运行时发生的最后一个错误. 例如, 如果在生成 diff 时发生错误, 则不会插入该错误. 刷新 status buffer 会导致此 section 再次消失.
• magit-insert-diff-filter-header [Function] 插入显示有效 diff 过滤器的 header line.
• magit-insert-head-branch-header [Function] 插入关于当前分支或 detached HEAD 的 header line.
• magit-insert-upstream-branch-header [Function] 插入关于通常 pull 到当前分支的分支的 header line.
• magit-insert-push-branch-header [Function] 插入关于当前分支通常 push 到的分支的 header line.
• magit-insert-tags-header [Function] 插入关于当前和/或下一个 tag 的 header line, 以及 tag 和 HEAD 之间的提交数量.

也可以将以下函数添加到上述 hook 中:

• magit-insert-repo-header [Function] 插入显示仓库顶层路径的 header line.
• magit-insert-remote-header [Function] 插入关于当前分支 remote 的 header line. 如果当前分支未配置 remote, 则回退显示 "origin" remote, 或者如果不存在则显示按字母顺序排列的第一个 remote.
• magit-insert-user-header [Function] 插入关于当前用户的 header line.

Status buffers 的内容使用 hook magit-status-sections-hook 控制 (见第 34 页的 [Status Sections]).

默认情况下 magit-insert-modules 不是该 hook 变量的成员.

• magit-insert-modules [Function] 插入 submodule sections. Hook magit-module-sections-hook 控制插入哪些 module sections, 选项 magit-module-sections-nested 控制它们是否包裹在一个额外的 section 中.
• magit-module-sections-hook [User Option] 由 magit-insert-modules 运行的 Hook.
• magit-module-sections-nested [User Option] 此选项控制 magit-insert-modules 是否将插入的 sections 包裹在一个额外的 section 中. 如果为非 nil, 则仅插入单个顶层 section. 如果为 nil, 则 magit-module-sections-hook 中列出的所有 sections 都成为顶层 sections.
• magit-insert-modules-overview [Function] 为所有 submodules 插入 sections. 为每个 section 插入路径, 分支和 git describe --tags 的输出, 或者如果失败, 则为缩写的 HEAD commit hash. 在此类 submodule section 上按 RET 以显示其自己的 status buffer. 在 "Modules" section 上按 RET 以在单独的 buffer 中显示 submodules 列表. 这显示了超级仓库的 status buffer 中未显示的附加信息.
• magit-insert-modules-unpulled-from-upstream [Function] 为尚未从 upstream pull 的 modules 插入 sections. 这些 sections 可以展开以显示相应的提交.
• magit-insert-modules-unpulled-from-pushremote [Function] 为尚未从 push-remote pull 的 modules 插入 sections. 这些 sections 可以展开以显示相应的提交.
• magit-insert-modules-unpushed-to-upstream [Function] 为尚未 push 到 upstream 的 modules 插入 sections. 这些 sections 可以展开以显示相应的提交.
• magit-insert-modules-unpushed-to-pushremote [Function] 为尚未 push 到 push-remote 的 modules 插入 sections. 这些 sections 可以展开以显示相应的提交.

• magit-status-margin [User Option] 此选项指定 margin 是否最初显示在 Magit-Status 模式 buffers 中以及其格式. 该值的形式为 (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).
  • 如果 INIT 为非 nil, 则最初显示 margin.
  • STYLE 控制如何格式化作者或提交者日期. 它可以是 age (显示提交的年龄), age-abbreviated (将时间单位缩写为一个字符), 或字符串 (适合 format-time-string) 以显示实际日期. 选项 magit-log-margin-show-committer-date 控制显示哪个日期.
  • WIDTH 控制 margin 的宽度. 这是为了向前兼容而存在的, 目前不应更改该值.
  • AUTHOR 控制是否默认也显示作者姓名.
  • AUTHOR-WIDTH 必须是整数. 当显示作者姓名时, 这指定用于执行此操作的空间.

另请参阅上一节中关于 status buffers 的更多选项.

Transient 前缀命令 magit-log-refresh (在 L 上) 可用于更改当前 buffer 中使用的 log 参数, 而不更改显示的 log. 这在专用 log buffers 中有效, 在 status buffer 中也有效.

• L (magit-log-refresh) 此 transient 前缀命令绑定以下 suffix 命令以及适当的 infix 参数, 并在临时 buffer 中显示它们, 直到调用 suffix.
• L g (magit-log-refresh) 此 suffix 命令设置当前 buffer 的本地 log 参数.
• L s (magit-log-set-default-arguments) 此 suffix 命令为与当前 buffer 类型相同的 buffers 设置默认 log 参数. 其他现有的相同类型的 buffers 不受影响, 因为它们的本地值已经初始化.
• L w (magit-log-save-default-arguments) 此 suffix 命令为与当前 buffer 类型相同的 buffers 设置默认 log 参数, 并保存该值以供将来会话使用. 其他现有的相同类型的 buffers 不受影响, 因为它们的本地值已经初始化.
• L L (magit-toggle-margin) 显示或隐藏 margin.

• L (magit-log-refresh) 此 transient 前缀命令绑定以下 suffix 命令以及适当的 infix 参数, 并在临时 buffer 中显示它们, 直到调用 suffix. 参见第 42 页的 [Refreshing Logs].
• q (magit-log-bury-buffer) 在同一 frame 中 bury 当前 buffer 或 revision buffer. 类似于 magit-mode-bury-buffer (见该条目), 但带有负前缀参数时, bury revision buffer (前提是它在当前 frame 中显示).
• C-c C-b (magit-go-backward) 在当前 buffer 的历史记录中向后移动.
• C-c C-f (magit-go-forward) 在当前 buffer 的历史记录中向前移动.
• C-c C-n (magit-log-move-to-parent) 移动到当前 commit 的父级. 默认情况下, 这是第一个父级, 但可以使用数字前缀指定另一个父级.
• j (magit-log-move-to-revision) 读取 revision 并在当前 log buffer 中移动到它. 如果选择的 reference 或 revision 未在当前 log buffer 中显示, 则通知用户并且不执行任何操作. 如果在任何 log buffer 之外调用, 则首先显示当前仓库的 log buffer; 必要时创建它.
• SPC (magit-diff-show-or-scroll-up) 更新 point 处对象的 commit 或 diff buffer. 要么在适当的 buffer 中显示 point 处的 commit 或 stash, 或者如果该 buffer 已经在当前 frame 中显示并且包含有关该 commit 或 stash 的信息, 则向上滚动 buffer. 如果 point 处没有 commit 或 stash, 则提示输入 commit.
• DEL (magit-diff-show-or-scroll-down) 更新 point 处对象的 commit 或 diff buffer. 要么在适当的 buffer 中显示 point 处的 commit 或 stash, 或者如果该 buffer 已经在当前 frame 中显示并且包含有关该 commit 或 stash 的信息, 则向下滚动 buffer. 如果 point 处没有 commit 或 stash, 则提示输入 commit.
• = (magit-log-toggle-commit-limit) 切换当前 log buffer 限制的提交数量. 如果提交数量当前受限, 则删除该限制. 否则将其设置为 256.
• + (magit-log-double-commit-limit) 将当前 log buffer 限制的提交数量加倍.
• - (magit-log-half-commit-limit) 将当前 log buffer 限制的提交数量减半.
• magit-log-auto-more [User Option] 当移动过最后一个条目时自动插入更多日志条目. 仅在使用 magit-goto-*-section 命令移动过最后一个条目时才考虑.
• magit-log-show-refname-after-summary [User Option] 是否在提交摘要后显示 refnames. 如果你使用非常长的分支名称, 这很有用.
• magit-log-show-color-graph-limit [User Option] 当显示超过此选项指定的提交时, 如果指定了 --color 参数, 则静默丢弃它. 这是必要的, 因为用于将控制序列转换为 faces 的 ansi-color 库太慢了.
• magit-log-show-signatures-limit [User Option] 当显示超过此选项指定的提交时, 如果指定了 --show-signature 参数, 则静默丢弃它. 这是必要的, 因为检查大量提交的签名太慢了.

Magit 在 logs 中显示 references 的方式与 Git 略有不同. 本地分支是蓝色的, 远程分支是绿色的. 当然这取决于使用的主题, 其他类型的 references 使用的颜色也是如此. 当前分支周围有一个框, 也是其各自 remote 的 HEAD 分支的远程分支.

如果本地分支及其 push-target 指向同一个 commit, 那么它们的名称会合并以节省空间并使这种关系可见. 例如: origin/feature [green][blue-] 代替 feature origin/feature [blue-] [green-------]

另请注意, 虽然 transient 具有 --show-signature 参数, 但启用时实际上不会使用它, 因为 Magit 默认每个 commit 仅使用一行. 相反, commit 会被着色以指示签名 commit 对象的有效性, 使用名为 magit-signature-* 的 faces (见这些 faces).

有关 magit-log-margin 的描述, 请参阅第 45 页的 [Log Margin].

在显示一个或多个 logs 的 buffers 中, 可以在 margin (边距) 中显示有关每个 commit 的附加信息. 用于配置 margin 的选项名为 magit-INFIX-margin, 其中 INFIX 与相应 major-mode magit-INFIX-mode 中的相同. 在常规 log buffers 中, 那将是 magit-log-margin.

• magit-log-margin [User Option] 此选项指定 margin 是否最初显示在 Magit-Log 模式 buffers 中以及其格式. 该值的形式为 (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).
  • 如果 INIT 为非 nil, 则最初显示 margin.
  • STYLE 控制如何格式化作者或提交者日期. 它可以是 age (显示提交的年龄), age-abbreviated (将时间单位缩写为一个字符), 或字符串 (适合 format-time-string) 以显示实际日期. 选项 magit-log-margin-show-committer-date 控制显示哪个日期.
  • WIDTH 控制 margin 的宽度. 这是为了向前兼容而存在的, 目前不应更改该值.
  • AUTHOR 控制是否默认也显示作者姓名.
  • AUTHOR-WIDTH 必须是整数. 当显示作者姓名时, 这指定用于执行此操作的空间.

你可以通过在加载 magit 之前自定义 magit-log-margin 来将所有 magit-INFIX-margin 选项的 STYLE 和 AUTHOR-WIDTH 更改为相同的值. 如果你这样做, 那么其他选项的相应值将默认为你为该变量设置的值. 同样, 如果你将 magit-log-margin 中的 INIT 设置为 nil, 那么这将在所有其他选项的默认值中使用. 但是将其设置为 t, 即重新强制该选项的默认值, 不会传递给其他选项.

• magit-log-margin-show-committer-date [User Option] 此选项指定是否在 margin 中显示提交者日期. 此选项仅控制是否显示提交者日期而不是作者日期. 是否在 margin 中显示某个日期以及是否显示 margin 完全由其他选项控制.
• L (magit-margin-settings) 此 transient 前缀命令绑定以下 suffix 命令, 每个命令都以某种方式更改 margin 的外观. 在一些支持 margin 的 buffers 中, L 改为绑定到 magit-log-refresh, 但该 transient 具有相同的命令, 以及一些其他不相关的命令.
• L L (magit-toggle-margin) 此命令显示或隐藏 margin.
• L l (magit-cycle-margin-style) 此命令循环 margin 使用的样式.
• L d (magit-toggle-margin-details) 此命令显示或隐藏 margin 中的详细信息.

当用户必须选择一个可从 HEAD 到达的最近 commit 时, 使用常规补全会很不方便 (因为大多数人无法记住 hashes 或 "HEAD~5", 至少在没有再次检查的情况下). 相反, 使用 log buffer 来选择 commit, 这具有按顺序显示 commits 并带有 commit 消息的优点.

此类选择 logs 用于选择 rebase 的开始以及选择要 squash 进入的 commit 时.

除了所有 log buffers 中可用的键绑定之外, 选择 log buffers 中还提供以下附加键绑定:

• C-c C-c (magit-log-select-pick) 选择 point 处的 commit 并对其进行操作. 使用选定的 commit 作为参数调用 magit-log-select-pick-function.
• C-c C-k (magit-log-select-quit) 中止选择 commit, 不对任何 commit 进行操作.
• magit-log-select-margin [User Option] 此选项指定 margin 是否最初显示在 Magit-Log-Select 模式 buffers 中以及其格式. 该值的形式为 (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).
  • 如果 INIT 为非 nil, 则最初显示 margin.
  • STYLE 控制如何格式化作者或提交者日期. 它可以是 age (显示提交的年龄), age-abbreviated (将时间单位缩写为一个字符), 或字符串 (适合 format-time-string) 以显示实际日期. 选项 magit-log-margin-show-committer-date 控制显示哪个日期.
  • WIDTH 控制 margin 的宽度. 这是为了向前兼容而存在的, 目前不应更改该值.
  • AUTHOR 控制是否默认也显示作者姓名.
  • AUTHOR-WIDTH 必须是整数. 当显示作者姓名时, 这指定用于执行此操作的空间.

另请参阅 git-reflog(1) manpage.

这些 reflog 命令可从 log transient 获得. 参见第 42 页的 5.3 节 [Logging].

• l r (magit-reflog-current) 显示当前分支的 reflog.
• l O (magit-reflog-other) 显示分支或另一个 ref 的 reflog.
• l H (magit-reflog-head) 显示 HEAD reflog.
• magit-reflog-margin [User Option] 此选项指定 margin 是否最初显示在 Magit-Reflog 模式 buffers 中以及其格式. 该值的形式为 (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).
  • 如果 INIT 为非 nil, 则最初显示 margin.
  • STYLE 控制如何格式化作者或提交者日期. 它可以是 age (显示提交的年龄), age-abbreviated (将时间单位缩写为一个字符), 或字符串 (适合 format-time-string) 以显示实际日期. 选项 magit-log-margin-show-committer-date 控制显示哪个日期.
  • WIDTH 控制 margin 的宽度. 这是为了向前兼容而存在的, 目前不应更改该值.
  • AUTHOR 控制是否默认也显示作者姓名.
  • AUTHOR-WIDTH 必须是整数. 当显示作者姓名时, 这指定用于执行此操作的空间.

Cherries 是尚未应用到 upstream (还) 的 commits, 通常使用 log 可视化. 每个 commit 都以 - 前缀 (如果在 upstream 中有等效项) 和 + 前缀 (如果没有, 即它是一个 cherry).

命令 magit-cherry 显示单个分支的 cherries, 但 references buffer (参见第 57 页的 5.6 节 [References Buffer]) 可以一次显示多个 "upstreams" 的 cherries.

另请参阅 git-reflog(1) manpage.

• Y (magit-cherry) 显示在某个分支中但尚未合并到 upstream 分支的 commits.
• magit-cherry-margin [User Option] 此选项指定 margin 是否最初显示在 Magit-Cherry 模式 buffers 中以及其格式. 该值的形式为 (INIT STYLE WIDTH AUTHOR AUTHOR-WIDTH).
  • 如果 INIT 为非 nil, 则最初显示 margin.
  • STYLE 控制如何格式化作者或提交者日期. 它可以是 age (显示提交的年龄), age-abbreviated (将时间单位缩写为一个字符), 或字符串 (适合 format-time-string) 以显示实际日期. 选项 magit-log-margin-show-committer-date 控制显示哪个日期.
  • WIDTH 控制 margin 的宽度. 这是为了向前兼容而存在的, 目前不应更改该值.
  • AUTHOR 控制是否默认也显示作者姓名.
  • AUTHOR-WIDTH 必须是整数. 当显示作者姓名时, 这指定用于执行此操作的空间.

Transient 前缀命令 magit-diff-refresh (在 D 上) 可用于更改当前 buffer 中使用的 diff 参数, 而不更改显示的 diff. 这在专用 diff buffers 中有效, 在 status buffer 中也有效.

(有一个例外; diff 参数不能在由 magit-merge-preview 创建的 buffers 中更改, 因为底层 Git 命令不支持这些参数.)

• D (magit-diff-refresh) 此 transient 前缀命令绑定以下 suffix 命令以及适当的 infix 参数, 并在临时 buffer 中显示它们, 直到调用 suffix.
• D g (magit-diff-refresh) 此 suffix 命令设置当前 buffer 的本地 diff 参数.
• D s (magit-diff-set-default-arguments) 此 suffix 命令为与当前 buffer 类型相同的 buffers 设置默认 diff 参数. 其他现有的相同类型的 buffers 不受影响, 因为它们的本地值已经初始化.
• D w (magit-diff-save-default-arguments) 此 suffix 命令为与当前 buffer 类型相同的 buffers 设置默认 diff 参数, 并保存该值以供将来会话使用. 其他现有的相同类型的 buffers 不受影响, 因为它们的本地值已经初始化.
• D t (magit-diff-toggle-refine-hunk) 此命令切换 hunk refinement (细化) 的开启或关闭.
• D r (magit-diff-switch-range-type) 此命令将 diff range 类型从 "revA..revB" 转换为 "revB…revA", 或反之亦然.
• D f (magit-diff-flip-revs) 此命令交换 diff range 中的 revisions, 从 "revA..revB" 到 "revB..revA", 或反之亦然.
• D F (magit-diff-toggle-file-filter) 此命令切换当前 buffer 中 diffs 的文件限制, 允许你在查看 commit 中的所有更改和受限子集之间快速切换. 作为特殊情况, 当从 log buffer 调用此命令时, 它会切换仓库 revision buffer 中的文件限制, 当你从限于一个或多个文件的 log buffer 中显示 revision 时, 这很有用.

除了上述允许更改任何支持参数的 transient 之外, 还有一些仅更改特定参数的命令.

• - (magit-diff-less-context) 此命令将 diff hunks 的上下文减少 COUNT 行.
• + (magit-diff-more-context) 此命令将 diff hunks 的上下文增加 COUNT 行.
• 0 (magit-diff-default-context) 此命令将 diff hunks 的上下文重置为默认高度.

以下命令快速更改显示的 diff, 而无需使用 diff transient 之一.

• C-c C-d (magit-diff-while-committing) 在提交时, 此命令显示即将提交的更改. 在 amending 时, 再次调用该命令可在仅显示新更改或显示将提交的所有更改之间切换. 此绑定在 diff buffer 以及 commit message buffer 中可用.
• C-c C-b (magit-go-backward) 此命令在当前 buffer 的历史记录中向后移动.
• C-c C-f (magit-go-forward) 此命令在当前 buffer 的历史记录中向前移动.

有些命令仅当 point 在 diff 内时才可用.

magit-diff-visit-file 和相关命令访问 point 处 diff 所关于的文件的适当版本. 同样 magit-diff-visit-worktree-file 和相关命令访问 point 处 diff 所关于的文件的 worktree 版本. 参见第 62 页的 [Visiting Files and Blobs from a Diff], 了解更多信息和键绑定.

• C-c C-t (magit-diff-trace-definition) 此命令显示 point 处定义的 log.
• magit-log-trace-definition-function [User Option] 此选项指定的函数由 magit-log-trace-definition 使用, 以确定 point 处的函数. 对于有特殊需求的 major-modes, 你可以使用该模式的 hook 设置本地值.
• C-c C-e (magit-diff-edit-hunk-commit) 从 hunk 中, 此命令编辑相应的 commit 并访问文件. 首先它使用 magit-diff-visit-file 在正确位置访问被 hunk 修改的文件. 这实际上是访问一个 blob. 当 point 在 diff header 上, 而不在单个 hunk 内时, 这访问第一个 hunk 所关于的 blob. 然后它调用 magit-edit-line-commit, 该命令使用交互式 rebase 使 commit 可编辑, 或者如果因为 commit 无法从 HEAD 到达而不可能, 则通过直接检出该 commit. 这也导致访问实际的 worktree 文件. 完成 rebase 后, 既不 kill blob 也不 kill 文件 buffer. 如果这是不希望的, 那么使用 magit-rebase-edit-commit 代替此命令可能更好.
• j (magit-jump-to-diffstat-or-diff) 此命令跳转到 diffstat 或 diff. 当 point 在 diffstat section 内的文件上时, 跳转到相应的 diff section. 否则, 跳转到 diffstat section 或其子项.

接下来的两个命令不是 Magit-Diff 模式 (或那件事的 Magit buffer) 特有的, 但这里也值得指出它们可用.

• SPC (scroll-up) 此命令向上滚动文本.
• DEL (scroll-down) 此命令向下滚动文本.

• magit-diff-refine-hunk [User Option] 是否在 diff hunks 中显示单词粒度的差异.
  • nil: 从不显示精细差异.
  • all: 为所有显示的 diff hunks 显示精细差异.
  • t: 一旦 hunk 成为当前 section, 就对其进行 refine. 当选择另一个 section 时保持 refinement. 刷新 buffer 会删除所有 refinement. 此变体仅出于性能原因提供.
• magit-diff-refine-ignore-whitespace [User Option] 是否在单词粒度差异中忽略空白更改.
• magit-diff-adjust-tab-width [User Option] 是否调整 diffs 中的 tabs 宽度. 确定正确的宽度可能很昂贵, 如果它需要打开大型和/或许多文件, 因此宽度缓存在变量 magit-diff--tab-width-cache 中. 将其设置为 nil 以使缓存无效.
  • nil: 从不调整 tab 宽度. 改为使用 Magit buffer 本身的 tab-width 值.
  • t: 如果相应的文件访问 buffer 存在, 则使用该 buffer 的 tab-width 值. 这样做很便宜, 因此即使存在相应的缓存条目也会使用此值.
  • always: 如果没有这样的 buffer, 则临时访问文件以确定该值.
  • NUMBER: 类似 always, 但不访问大于 NUMBER 字节的文件.
• magit-diff-paint-whitespace [User Option] 指定在哪里高亮显示空白错误. 参见 magit-diff-highlight-trailing, magit-diff-highlight-indentation. 符号 t 表示在所有 diffs 中, status 表示仅在 status buffer 中, nil 表示不在任何地方.
  • nil: 从不高亮显示空白错误.
  • t: 到处高亮显示空白错误.
  • uncommitted: 仅在显示未提交更改的 diffs 中高亮显示空白错误. 为了向后兼容, status 被视为同义词.
• magit-diff-paint-whitespace-lines [User Option] 指定在什么样的行中高亮显示空白错误.
  • t: 仅在添加的行中高亮显示.
  • both: 在添加和删除的行中高亮显示.
  • all: 在添加, 删除和上下文行中高亮显示.
• magit-diff-highlight-trailing [User Option] 是否在 diffs 中高亮显示行尾的空白. 仅当 magit-diff-paint-whitespace 为非 nil 时使用.
• magit-diff-highlight-indentation [User Option] 此选项控制如果使用了 "错误" 的缩进样式, 是否高亮显示缩进. 仅当 magit-diff-paint-whitespace 也为非 nil 时, 缩进才会被高亮显示. 该值是 ((REGEXP . INDENT)...) 形式的 alist. 当前仓库的路径与每个元素逆序匹配. 因此, 如果 REGEXP 匹配, 则不尝试较早的元素. 如果使用的 INDENT 是 tabs, 则使用 tabs 高亮显示缩进. 如果 INDENT 是整数, 则使用至少那么多空格高亮显示缩进. 否则, 都不高亮显示.
• magit-diff-hide-trailing-cr-characters [User Option] 是否在 diffs 中隐藏行尾的 ^M 字符.
• magit-diff-highlight-hunk-region-functions [User Option] 此选项指定用于高亮显示 hunk-internal region 的函数. magit-diff-highlight-hunk-region-dim-outside 用一个 face 覆盖 hunk 内部选择的外部, 使添加和删除的行具有与上下文行相同的背景颜色. 不应从此选项的值中删除此函数. magit-diff-highlight-hunk-region-using-overlays 和 magit-diff-highlight-hunk-region-using-underline 通过在其前后放置定界水平线来强调 region. 由于 Emacs 显示引擎的限制, 这两个函数都有无法修复的故障. 有关更多信息, 请参阅 https://github.com/magit/magit/issues/2758 等. 除了或代替使用定界水平线来强调边界, 你可能希望强调文本本身, 使用 magit-diff-highlight-hunk-region-using-face. 在终端 frames 中, 无法像 overlay 和 underline 变体通常那样绘制线条, 因此在那里它们回退到调用 face 函数.
• magit-diff-unmarked-lines-keep-foreground [User Option] 此选项控制 hunk-internal region 之外的添加和删除行是仅失去其独特的背景颜色还是也失去前景颜色. region 外部是否变暗完全取决于 magit-diff-highlight-hunk-region-functions.
• magit-diff-extra-stat-arguments [User Option] 此选项指定与 --stat 一起使用的附加参数. 该值是零个或多个参数的列表, 或者是不带参数并返回此类列表的函数. 这里允许这些参数: --stat-width, --stat-name-width, --stat-graph-width 和 --compact-summary. 另请参阅 git-diff(1) manpage.
• magit-format-file-function [User Option] 此函数用于格式化代表文件的行. 它用于 diffs 中的文件标题, diffstats 和文件列表 (例如未跟踪文件). 根据调用者, 它接收三个或五个参数; 签名必须是 (kind file face &optional status orig). KIND 是 diff, module, stat 和 list 之一.

• magit-revision-insert-related-refs [User Option] 是否在 revision buffers 中显示相关分支.
  • nil: 不显示任何相关分支.
  • t: 显示相关本地分支.
  • all: 显示相关本地和远程分支.
  • mixed: 显示所有包含分支和本地合并分支.
• magit-revision-show-gravatars [User Option] 是否在 revision buffers 中显示 gravatar 图像. 如果为 nil, 则不插入任何 gravatar 图像. 如果为 t, 则插入两个图像. 如果为 author 或 committer, 则仅插入相应的图像. 如果你自定义了选项 magit-revision-headers-format 并想插入图像, 那么你可能还需要指定在哪里这样做. 在这种情况下, 该值必须是两个正则表达式的 cons-cell. car 指定在哪里插入作者的图像. 图像的上半部分插入在匹配文本之后, 下半部分在下一行的同一列. cdr 指定在哪里插入提交者的图像, 依此类推. car 或 cdr 都可以为 nil.

• magit-revision-use-hash-sections [User Option] 是否将 commit message 中的 hashes 转换为 sections. 如果为非 nil, 那么 commit message 中的 hashes 将转换为 commit sections. 在性能和可靠性之间需要权衡:

  • slow: 对每个单词调用 git 以绝对确定.
  • quick: 跳过少于 7 个字符的单词.
  • quicker: 另外跳过不包含数字的单词.
  • quickest: 使用所有至少 7 个字符长且包含至少一个数字和一个字母的单词.

  如果为 nil, 则没有 hashes 转换为 sections, 但你仍然可以使用 "RET" 访问 point 处的 commit.

Revision buffer 中显示的 diffs 可以自动限制为更改文件的子集. 如果 revision buffer 是从 log buffer 显示的, 则 revision buffer 将共享与该 log buffer 相同的文件限制 (另请参见命令 magit-diff-toggle-file-filter).

• magit-revision-filter-files-on-follow [User Option] 当 log 参数包含 --follow 时, 从 log buffer 显示 commit 是否遵循 log 的文件过滤器. 当此选项为 nil 时, 如果 log 参数包含 --follow, 则从 log 显示 commit 会忽略 log 的文件过滤器. 这样做可以避免在重命名事件之前的 commits 的 revision buffers 中显示空 diff. 在这种情况下, 可以使用 log transient 的 --patch 参数以内联方式显示文件限制的 diffs. 将此选项设置为非 nil, 即使 log 参数中存在 --follow, 也保持 log 的文件限制.

如果 revision buffer 不是从 log buffer 显示的, 则文件限制照常确定 (参见第 21 页的 4.4 节 [Transient Arguments and Buffer Variables]).

References buffers 的内容使用 hook magit-refs-sections-hook 控制. 参见第 19 页的 [Section Hooks], 了解有关此类 hooks 以及如何自定义它们的信息. 以下所有函数都是默认值的成员. 请注意, 自定义此 hook 比自定义用于 status buffer 的相应 hook 意义要小得多.

• magit-refs-sections-hook [User Option] 运行此 hook 以将 sections 插入 references buffer.
• magit-insert-local-branches [Function] 插入显示所有本地分支的 sections.
• magit-insert-remote-branches [Function] 插入显示所有远程跟踪分支的 sections.
• magit-insert-tags [Function] 插入显示所有 tags 的 sections.

这些命令可用于在任何地方打开任何 blob. 默认情况下没有键绑定到这些命令, 但这可能会改变.

• magit-find-file [Command] 此命令从用户读取文件名和 revision, 并在 buffer 中访问相应的 blob. buffer 显示在选定窗口中.
• magit-find-file-other-window [Command] 此命令从用户读取文件名和 revision, 并在 buffer 中访问相应的 blob. buffer 显示在另一个窗口中.
• magit-find-file-other-frame [Command] 此命令从用户读取文件名和 revision, 并在 buffer 中访问相应的 blob. buffer 显示在另一个 frame 中.

这些命令仅当 point 在 diff 内时才可以使用. 在其他地方使用 magit-find-file.

• RET (magit-diff-visit-file) 此命令访问 point 处文件的适当版本. 在选定窗口中显示 buffer. 带有前缀参数 OTHER-WINDOW, 改为在另一个窗口中显示 buffer. 在访问的文件或 blob 中, 转到与 diff 中位置对应的位置. 如果 point 在添加行或上下文行上, 访问对应于我方 (即, 新/右侧) 的 blob. 如果 point 在删除行上, 访问对应于彼方 (即, 旧/左侧) 的 blob. 这也适用于 staged 和 unstaged 更改的 diffs. 对于 staged 更改, 双方是来自 index 和 HEAD commit 的 blobs. 对于 unstaged 更改, 双方是 worktree 中的实际文件和来自 index 的 blob. 要访问 worktree 中的文件, 无论当前 diff 是关于什么的, 请使用 magit-diff-visit-worktree-file, 如下所述.
• C-<return> (magit-diff-visit-worktree-file) 此命令访问适当文件的 worktree 版本. diff 内 point 的位置决定了访问哪个文件. 与 magit-diff-visit-file 不同, 它总是访问 worktree 中的 "真实" 文件, 即文件的 "当前版本". 在文件访问 buffer 中, 此命令转到与 diff 中 point 所在行对应的行. 工作树, index 和其间其他 commits 中添加或删除的行会自动被考虑在内. buffer 显示在选定窗口中. 带有前缀参数时, buffer 显示在另一个窗口中.

存在上述两个命令的变体, 它们改为在另一个窗口或另一个 frame 中访问文件. 如果你更喜欢这种行为, 那么你可能想更改上面的键绑定, 但请注意, 上述命令在使用前缀参数调用时也使用另一个窗口.

• magit-diff-visit-file-other-window [Command]
• magit-diff-visit-file-other-frame [Command]
• magit-diff-visit-worktree-file-other-window [Command]
• magit-diff-visit-worktree-file-other-frame [Command] 这些命令的行为类似于上述相应命令, 除了它们在另一个窗口或 frame 中显示 blob 或文件.
• magit-diff-visit-prefer-worktree [User Option] 此选项控制 magit-diff-visit-file 在从 staged 或 unstaged 更改的 hunk 中调用时, 是否总是访问 worktree 中的相应文件. 默认情况下 magit-diff-visit-file 不这样做. 相反, 它对 staged 和 unstaged 更改的行为就像对已提交更改一样, 通过访问旧/左侧或新/右侧的 blob, 具体取决于 point 是否在删除行上. 对于 staged 更改, 旧的一侧是来自 HEAD 的 blob, 右侧是来自 index 的 blob. 对于 unstaged 更改, 左侧是来自 index 的 blob (如果该文件在 index 中有任何更改, 否则是来自 HEAD 的 blob), 右侧是 worktree 中的文件. 能够从删除行跳转到 HEAD 或 index 非常有用, 因为它允许你例如使用 blame 来调查为什么添加了某行 (如果你已经删除了它). 但是如果你想对已经 staged 的更改进行进一步更改, 你当然需要转到 worktree 中的相应文件. 命令 magit-diff-visit-worktree-file 就是为此目的而创建的, 强烈建议你使用该命令, 即使你最初觉得必须记住使用 C-<return> 而不是 RET 这种情况下很不方便. 虽然不鼓励, 但你可以选择将此选项设置为 t, 这会导致 magit-diff-visit-file 即使从 staged 更改的 hunk 中调用, 也会转到 worktree 中的文件. 如果你这样做, 你将失去立即转到已删除行的能力.
• magit-diff-visit-previous-blob [User Option] 此选项控制当 point 在删除行上调用时, magit-diff-visit-file 是否访问前一个 blob. 当此值为 t (默认值) 且 point 在删除行上时, magit-diff-visit-file 访问来自旧/左侧 commit 的 blob (它仍然有那行), 而不是转到新/右侧 blob (它删除了那行). 将此设置为 nil, 导致 magit-diff-visit-file 总是转到新/右侧 blob, 即使 point 在删除行上. 强烈不鼓励这样做. 相反, 如果你想访问新的一侧, 请将光标放在 hunk 内除了删除行之外的任何位置. 这样你就不会失去访问旧一侧的能力.

细粒度的 un-/staging 必须在 status 或 diff buffer 中完成, 但也可以直接在当前 buffer 中 un-/stage 对该 buffer 访问文件所做的所有更改.

• M-x magit-stage-file 当在访问文件的 buffer 内调用时, stage 对该文件的所有更改. 在 Magit buffer 中, stage point 处的文件 (如果有). 否则提示要 stage 的文件. 带有前缀参数时, 即使在访问文件的 buffer 中或 point 处有文件 section, 也总是提示用户输入文件.
• M-x magit-unstage-file 当在访问文件的 buffer 内调用时, unstage 对该文件的所有更改. 在 Magit buffer 中, unstage point 处的文件 (如果有). 否则提示要 unstage 的文件. 带有前缀参数时, 即使在访问文件的 buffer 中或 point 处有文件 section, 也总是提示用户输入文件.

另请参阅 git-commit(1) manpage.

• c (magit-commit) 此 transient 前缀命令绑定以下 suffix 命令以及适当的 infix 参数, 并在临时 buffer 中显示它们, 直到调用 suffix.

在如上一节所述发起提交后, 出现两个新 buffers. 一个显示即将提交的更改, 另一个用于编写消息.

提交消息在编辑会话中编辑–在后台 git 等待编辑器 (在我们的例子中是 emacsclient) 将提交消息保存到文件 (在大多数情况下为 .git/COMMIT_EDITMSG) 然后返回. 如果编辑器以非零退出状态返回, 那么 git 不会创建提交. 所以最重要的命令是那些用于完成和中止提交的命令.

• C-c C-c (with-editor-finish) 通过以退出代码 0 返回来完成当前编辑会话. Git 然后使用它在文件中找到的消息创建提交.
• C-c C-k (with-editor-cancel) 通过以退出代码 1 返回来取消当前编辑会话. Git 然后取消提交, 但保持文件不变.

除了被 git commit 使用之外, 消息还可以存储在环中, 该环持续到 Emacs 关闭. 默认情况下, 消息在编辑会话的开始和结束时存储 (无论会话是成功完成还是被取消). 有时从该环中取回消息很有用.

• C-c M-s (git-commit-save-message) 将当前 buffer 内容保存到提交消息环.
• M-p (git-commit-prev-message) 在将当前消息保存到环后, 向后循环提交消息环. 带有数字前缀 ARG, 后退 ARG 条评论.
• M-n (git-commit-next-message) 在将当前消息保存到环后, 向前循环提交消息环. 带有数字前缀 ARG, 后退 ARG 条评论.

默认情况下, 调用提交时会自动显示即将提交的更改的 diff. 要防止这种情况, 从 server-switch-hook 中移除 magit-commit-diff.

(remove-hook 'with-editor-filter-visit-hook 'magit-commit-diff)

然后你可以输入 C-c C-d 来显示 diff, 当你实际上想看到它时, 但仅限于此. 或者你可以保留 hook, 只在生成 diff 需要太长时间的情况下输入 C-g. 如果你这样做, 那么你最终会得到一个损坏的 diff buffer, 但这样做的好处是你通常可以看到 diff, 这很有用, 因为它增加了你发现潜在问题的几率.

当 amend 现有提交时, 显示即将添加到该提交的更改或将这些更改与已经提交的更改一起显示可能会很有用.

• C-c C-d (magit-diff-while-committing) 提交时, 显示即将提交的更改. Amend 时, 再次调用该命令可在仅显示新更改或显示将提交的所有更改之间切换.

某个本地分支的 upstream branch (上游分支) 是该本地分支上的提交最终应合并到的分支, 通常类似于 origin/master. 对于 master 分支本身, upstream 分支和它被 push 到的分支通常是同一个远程分支. 但对于功能分支, upstream 分支和它被 push 到的分支应该不同.

功能分支上的提交最终也应该进入远程分支, 如 origin/master 或 origin/maint. 因此, 此类分支应用作 upstream. 但功能分支不应直接 push 到此类分支. 相反, 功能分支 my-feature 通常被 push 到 my-fork/my-feature 或如果你是贡献者 origin/my-feature. 在新功能经过审查后, 维护者将该功能合并到 master 中. 最后 master (而不是 my-feature 本身) 被 push 到 origin/master.

但新功能很少在第一次尝试时就完美无缺, 因此功能分支通常必须经过多次审查, 改进和重新 push. 因此, Pushing 应该很容易做到, 出于这个原因, 许多 Git 用户得出结论, 最好使用本地功能分支被 push 到的远程分支作为其 upstream.

但幸运的是, Git 早就获得了对 push-remote 的支持, 可以使用变量 branch.<name>.pushRemote 和 remote.pushDefault 与 upstream 分支分开配置. 所以我们不再需要选择两个 remotes 中的哪一个用作 "the remote".

每个 fetching, pulling 和 pushing transient 命令都具有三个 suffix 命令, 它们作用于当前分支和某个其他分支. 其中, p 绑定到作用于 push-remote 的命令, u 绑定到作用于 upstream 的命令, e 绑定到作用于任何其他分支的命令. Status buffer 显示 push-remote 和 upstream 的 unpushed 和 unpulled 提交.

配置这两个 remotes 相当简单. 与 fetching, pulling 和 pushing 相关的所有变量 (以及一些其他分支相关变量) 的值都可以使用命令 magit-branch-configure 进行检查和更改, 该命令可从处理分支的许多 transient 前缀命令获得. 也可以在 pushing 时设置 push-remote 或 upstream (参见第 107 页的 7.4 节 [Pushing]).

Transient 前缀命令 magit-branch 用于创建和检出分支, 以及更改现有分支. 它不用于 fetch, pull, merge, rebase 或 push 分支, 即此命令处理分支本身, 而不是从它们可到达的 commits. 这些功能可从单独的 transient 命令获得.

• b (magit-branch) 此 transient 前缀命令绑定以下 suffix 命令, 并在临时 buffer 中显示它们, 直到调用 suffix. 默认情况下, 它还绑定并显示一些分支相关 Git 变量的值, 并允许更改其值.
• magit-branch-direct-configure [User Option] 此选项控制 transient 命令 magit-branch 是否可用于直接更改 Git 变量的值. 这默认为 t (以避免更改键绑定). 当设置为 nil 时, 该 transient 命令不显示任何变量, 必须改用其 suffix 命令 magit-branch-configure 来查看和更改分支相关变量.
• b C (magit-branch-configure)
• f C
• F C
• P C 此 transient 前缀命令绑定设置分支相关变量值的命令, 并在临时 buffer 中显示它们, 直到退出 transient. 带有前缀参数时, 此命令总是提示输入分支. 不带前缀参数时, 这取决于它是否作为 magit-branch 的 suffix 调用以及 magit-branch-direct-configure 选项. 如果 magit-branch 已经显示当前分支的变量, 那么调用另一个显示同一分支变量的 transient 是没有用的. 在这种情况下, 此命令提示输入分支. 变量在 [Branch Git Variables], 第 86 页中描述.
• b b (magit-checkout) 检出在 minibuffer 中读取的 revision, 默认为 point 处的分支或任意 revision. 如果 revision 是本地分支, 那么它成为当前分支. 如果它是其他东西, 那么 HEAD 变为 detached. 如果 worktree 或 staging area 包含更改, 则检出失败.
• b n (magit-branch-create) 创建一个新分支. 要求用户输入一个分支或任意 revision 用作新分支的起点. 当提供分支名称时, 它成为新分支的 upstream 分支. 新分支的名称也在 minibuffer 中读取. 另请参见选项 magit-branch-prefer-remote-upstream.
• b c (magit-branch-and-checkout) 此命令像 magit-branch-create 一样创建新分支, 但随后也会检出它. 另请参见选项 magit-branch-prefer-remote-upstream.

• b l (magit-branch-checkout) 此命令检出已有的或新的本地分支. 它从用户读取分支名称, 提供所有本地分支和一部分远程分支作为候选项. 存在同名本地分支的远程分支从候选项列表中省略. 用户还可以输入全新的分支名称.

  • 如果用户选择现有的本地分支, 则检出该分支.
  • 如果用户选择远程分支, 则它创建并检出同名的新本地分支, 并将所选远程分支配置为 push target.
  • 如果用户输入新分支名称, 则在从用户读取起点后, 创建并检出该分支.

  在后两种情况下, upstream 也会被设置. 是否将其设置为所选起点或其他内容取决于 magit-branch-adjust-remote-upstream-alist 的值.

• b s (magit-branch-spinoff) 此命令创建并检出一个新分支, 从当前分支开始并跟踪当前分支. 该分支反过来重置为它与其 upstream 共享的最后一次提交. 如果当前分支没有 upstream 或没有 unpushed 提交, 则无论如何都会创建新分支, 并且以前的当前分支不受影响. 这对于在旧分支 (可能但不一定是 "master") 上开始工作后创建功能分支很有用. 如果当前分支是选项 magit-branch-prefer-remote-upstream (见下文) 值的成员, 那么当前分支将照常作为起点, 但起点的 upstream 可能用作新分支的 upstream, 而不是起点本身. 如果可选的 FROM 为非 nil, 那么源分支重置为 FROM~, 而不是它与其 upstream 共享的最后一次提交. 交互式地, 仅当 region 选择了一些 commits 时, FROM 才为非 nil, 并且在这些 commits 中, FROM 是领先源分支最少 commits 的 commit. selection 另一端的 commit 实际上并不重要, FROM 和 HEAD 之间的所有 commits 都移动到新分支. 如果 FROM 不能从 HEAD 到达或可以从源分支的 upstream 到达, 则引发错误.
• b S (magit-branch-spinout) 此命令的行为类似于 magit-branch-spinoff, 除了它不更改当前分支. 如果有任何未提交的更改, 那么它的行为与 magit-branch-spinoff 完全相同.
• b x (magit-branch-reset) 此命令重置分支, 默认为 point 处的分支, 到另一个分支的顶端或任何其他 commit. 当重置的分支是当前分支时, 执行 hard reset. 如果有任何未提交的更改, 那么用户必须确认重置, 因为这些更改将会丢失. 当你开始在一个功能分支上工作但意识到这全是垃圾并想重新开始时, 这很有用. 当重置为另一个分支并使用前缀参数时, 目标分支设置为正在重置的分支的 upstream.
• b k (magit-branch-delete) 删除一个或多个分支. 如果 region 标记了多个分支, 则提议删除这些分支. 否则, 提示删除单个分支, 默认为 point 处的分支. 当以某种方式删除分支很危险时要求确认. 选项 magit-no-confirm 可以自定义为在某些情况下不需要确认. 请参阅其 docstring 以了解为什么默认情况下在某些情况下需要确认或如果提示令人困惑.
• b m (magit-branch-rename) 重命名分支. 分支和新名称在 minibuffer 中读取. 带有前缀参数时, 即使该名称与现有分支冲突, 也重命名分支.
• magit-branch-read-upstream-first [User Option] 创建分支时, 是否在要创建的分支名称之前读取 upstream 分支. 默认为 t, 我建议你保持原样.
• magit-branch-prefer-remote-upstream [User Option] 此选项指定创建新分支时是否优先选择远程 upstreams 而不是本地 upstreams. 当创建新分支时, point 处的分支, 提交或 stash 被建议作为新分支的起点, 或者如果 point 处没有此类 revision, 则建议当前分支. 在任何一种情况下, 用户都可以选择另一个起点. 如果所选起点是分支, 那么也可以根据 Git 变量 branch.autoSetupMerge 的值将其设置为新分支的 upstream. 默认情况下, 对远程分支执行此操作, 但不对本地分支执行. 你可能更喜欢始终使用某个远程分支作为 upstream. 如果所选起点是 (1) 本地分支, (2) 其名称与此选项值的成员匹配, (3) 该本地分支的 upstream 是同名的远程分支, 并且 (4) 该远程分支可以 fast-forwarded 到本地分支, 那么所选分支用作起点, 但其自己的 upstream 用作新分支的 upstream. 此选项值的成员被视为分支名称, 必须完全匹配, 除非它们包含使它们作为分支名称无效的字符. 建议使用触发解释为 regexp 的字符是 * 和 ^. 一些你可能认为无效的其他字符实际上并非如此, 例如 +$ 都是完全有效的. 更确切地说, 如果 git check-ref-format --branch STRING 以非零状态退出, 则将 STRING 视为 regexp. 假设所选分支符合这些条件, 你最终会得到例如: feature --upstream--> origin/master 代替 feature --upstream--> master --upstream--> origin/master 你更喜欢哪种是个人偏好问题. 如果你确实更喜欢前者, 那么你应该将诸如 master, next 和 maint 之类的分支添加到此选项的值中.

• magit-branch-adjust-remote-upstream-alist [User Option] 此选项的值是分支远程分支时用作 upstream 的分支的 alist. 当从位于 remote 上的临时分支 (例如功能或热修复分支) 创建本地分支时, 该远程分支通常不应用作 upstream 分支, 因为 push-remote 已经允许访问它, 并且让 upstream 和 push-remote 都引用同一个相关分支是浪费的. 相反, 应该使用像 "maint" 或 "master" 这样的分支作为 upstream. 此选项允许指定在分支某些远程分支时应用作 upstream 的分支. 值的形式为 ((UPSTREAM . RULE)...). 使用第一个匹配元素, 忽略后续元素. UPSTREAM 是要用作 RULE 指定的分支的 upstream 的分支. 它可以是本地或远程分支. RULE 可以是正则表达式, 匹配其 upstream 应为 UPSTREAM 指定的分支. 或者它可以是 不应 使用 UPSTREAM 的 唯一 分支的列表; 所有其他分支都会使用. 匹配是在剥离被分支的分支名称的 remote 部分后完成的. 如果你在所有仓库中使用一组有限的非临时分支, 那么你可以使用类似: (("origin/master" . ("master" "next" "maint"))) 或者如果所有临时分支的名称都包含斜杠 (至少在某些仓库中), 那么一个好的值可能是: (("origin/master" . "/")) 当然你也可以微调:

  (("origin/maint" . "\\~hotfix/")
   ("origin/master" . "\\~feature/"))
  

  UPSTREAM 可以是本地分支: (("master" . ("master" "next" "maint"))) 因为主分支不再几乎总是命名为 "master", 你也应该考虑其他常用名称:

  (("main" . ("main" "master" "next" "maint"))
   ("master" . ("main" "master" "next" "maint")))
  

• magit-branch-orphan [Command] 此命令创建并检出一个新的孤儿分支, 内容来自给定的 revision.

• magit-branch-or-checkout [Command] 此命令是 magit-checkout 和 magit-branch-and-checkout 之间的混合体, 旨在作为 magit-branch 中前者的替代品. 它首先询问用户现有的分支或 revision. 如果用户输入实际上可以解析为分支或 revision, 那么它检出它, 就像 magit-checkout 一样. 否则它使用输入作为其名称创建并检出一个新分支. 在这样做之前, 它读取新分支的起点. 这类似于 magit-branch-and-checkout 所做的. 要使用此命令代替 magit-checkout, 将此添加到你的 init 文件:

  (transient-replace-suffix 'magit-branch 'magit-checkout
    '("b" "dwim" magit-branch-or-checkout))
  

这些变量可以从 transient 前缀命令 magit-branch-configure 设置. 默认情况下它们也可以从 magit-branch 设置. 参见第 82 页的 [Branch Commands].

• branch.NAME.merge [Variable] 与 branch.NAME.remote 一起, 此变量定义本地分支 NAME 的 upstream 分支. 此变量的值是 upstream 分支的完整引用.
• branch.NAME.remote [Variable] 与 branch.NAME.merge 一起, 此变量定义本地分支 NAME 的 upstream 分支. 此变量的值是 upstream remote 的名称.
• branch.NAME.rebase [Variable] 此变量控制 pull 到分支 NAME 是通过 rebasing 还是通过 merging fetched 分支来完成.
  • 当 true 时, pulling 通过 rebasing 完成.
  • 当 false 时, pulling 通过 merging 完成.
  • 当 undefined 时, 使用 pull.rebase 的值. 该变量的默认值为 false.
• branch.NAME.pushRemote [Variable] 此变量指定名为 NAME 的分支通常被 push 到的 remote. 值必须是现有 remote 的名称. 不可能指定要将本地分支 push 到的分支名称. 远程分支的名称总是与本地分支的名称相同. 如果此变量未定义但定义了 remote.pushDefault, 则使用后者的值. 默认情况下 remote.pushDefault 未定义.
• branch.NAME.description [Variable] 此变量可用于描述名为 NAME 的分支. 该描述用于例如将分支转换为一系列补丁时.

以下变量指定如果未设置上述分支特定变量时使用的默认值.

• pull.rebase [Variable] 此变量指定 pulling 是通过 rebasing 还是通过 merging 完成. 它可以使用 branch.NAME.rebase 覆盖.

  • 当 true 时, pulling 通过 rebasing 完成.
  • 当 false (默认) 时, pulling 通过 merging 完成.

  由于将 upstream 分支合并到功能或热修复分支从来都不是一个好主意, 并且大多数分支都是这样的分支, 你应该考虑将此设置为 true, 并将 branch.master.rebase 设置为 false.

• remote.pushDefault [Variable] 此变量指定本地分支通常被 push 到哪个 remote. 这可以使用 branch.NAME.pushRemote 对每个分支进行覆盖.

以下变量在创建分支期间使用, 并控制是否在此时自动设置各种分支特定变量.

• branch.autoSetupMerge [Variable] 此变量指定在什么情况下创建分支 NAME 应该导致变量 branch.NAME.merge 和 branch.NAME.remote 根据用于创建分支的起点进行设置. 如果起点不是分支, 则从不设置这些变量.
  • 当 always 时, 无论起点是本地还是远程分支, 都设置变量.
  • 当 true (默认) 时, 当起点是远程分支时设置变量, 但当它是本地分支时不设置.
  • 当 false 时, 从不设置变量.
• branch.autoSetupRebase [Variable] 此变量指定创建分支 NAME 是否应导致变量 branch.NAME.rebase 设置为 true.
  • 当 always 时, 无论起点是本地还是远程分支, 都设置变量.
  • 当 local 时, 当起点是本地分支时设置变量, 但当它是远程分支时不设置.
  • 当 remote 时, 当起点是远程分支时设置变量, 但当它是本地分支时不设置.
  • 当 never (默认) 时, 从不设置变量.

注意相应的命令总是更改仓库本地值. 如果你想更改全局值 (当本地值未定义时使用), 那么你必须在命令行上执行此操作, 例如: git config --global remote.autoSetupMerge always

有关这些变量的更多信息, 你还应该参阅 git-config(1) manpage. 另请参阅 git-branch(1) manpage, git-checkout(1) manpage 和第 107 页的 7.4 节 [Pushing].

• magit-prefer-remote-upstream [User Option] 此选项控制读取分支名称并将其设置为 upstream 分支的命令, 在有选择时是否提供本地或远程分支作为默认补全候选项. 这影响所有使用 magit-read-upstream-branch 或 magit-read-starting-point 的命令, 包括所有更改 upstream 的命令和许多创建新分支的命令.

这些命令默认情况下无法从 transient magit-branch 获得.

• magit-branch-shelve [Command] 此命令 shelve (搁置) 分支. 这是通过删除分支, 并创建一个指向分支指向的同一 commit 的新 reference "refs/shelved/BRANCH-NAME" 来完成的. 如果删除的分支有 reflog, 那么它被保留为新 reference 的 reflog. 如果你想将分支移出视线, 但还没准备好完全丢弃它, 这很有用.
• magit-branch-unshelve [Command] 此命令 unshelves 之前使用 magit-branch-shelve shelved 的分支. 这是通过删除 reference "refs/shelved/BRANCH-NAME" 并创建一个指向被删除 reference 指向的同一 commit 的分支 "BRANCH-NAME" 来完成的. 如果删除的 reference 有 reflog, 那么它被恢复为分支的 reflog.

• C-c C-c (with-editor-finish) 通过以退出代码 0 返回来完成当前编辑会话. Git 然后使用它在文件中找到的 rebase 指令.
• C-c C-k (with-editor-cancel) 通过以退出代码 1 返回来取消当前编辑会话. Git 然后放弃启动 rebase 序列.
• RET (git-rebase-show-commit) 在另一个 buffer 中显示当前行上的 commit 并选择该 buffer.
• SPC (git-rebase-show-or-scroll-up) 在另一个 buffer 中显示当前行上的 commit 而不选择该 buffer. 如果 revision buffer 已在当前 frame 的另一个窗口中可见, 则向上滚动该窗口.
• DEL (git-rebase-show-or-scroll-down) 在另一个 buffer 中显示当前行上的 commit 而不选择该 buffer. 如果 revision buffer 已在当前 frame 的另一个窗口中可见, 则向下滚动该窗口.
• p (git-rebase-backward-line) 移动到上一行.
• n (forward-line) 移动到下一行.
• M-p (git-rebase-move-line-up) 向上移动当前 commit (或命令).
• M-n (git-rebase-move-line-down) 向下移动当前 commit (或命令).
• r (git-rebase-reword) 编辑当前行上 commit 的消息.
• e (git-rebase-edit) 在当前行上的 commit 处停止.
• s (git-rebase-squash) 此命令将当前行上的 commit 折叠到上一个 commit 中, 给用户机会手动合并这两条消息.
• S (git-rebase-squish) 此命令将当前行上的 commit 折叠到上一个 commit 中, 丢弃上一个 commit 的消息, 但给用户机会编辑最终消息 (基于当前 commit 的消息). 此动作在 commits 列表中显示的指示器是 fixup -c (带有小写 c).
• f (git-rebase-fixup) 此命令将当前行上的 commit 折叠到上一个 commit 中, 仅按原样使用上一个 commit 的消息并丢弃当前 commit 的消息.
• F (git-rebase-alter) 此命令将当前行上的 commit 折叠到上一个 commit 中, 丢弃上一个 commit 的消息并改用当前 commit 的消息. 这就像 git-rebase-alter, 除了它使用另一个消息. 这也像 git-rebase-squish, 除了它让用户编辑消息. 此动作在 commits 列表中显示的指示器是 fixup -C (带有大写 C).
• k (git-rebase-kill-line) 注释掉当前动作行, 或者如果已经注释, 则取消注释.
• c (git-rebase-pick) 使用当前行上的 commit.
• x (git-rebase-exec) 插入要在处理 commit 后运行的 shell 命令. 如果当前行上已经有这样的命令, 则编辑它. 带有前缀参数时, 即使当前行上已经有一个命令, 也会插入一个新命令. 输入为空时, 删除当前行上的命令 (如果有).
• b (git-rebase-break) 在当前行之前插入一个 break 动作, 指示 Git 将控制权交还给用户.
• y (git-rebase-insert) 读取任意 commit 并将其插入当前行下方.
• C-x u (git-rebase-undo) 撤消一些先前的更改. 像 undo 但在 read-only buffers 中工作.
• git-rebase-auto-advance [User Option] 更改一行后是否移动到下一行.
• git-rebase-show-instructions [User Option] 是否在 rebase buffer 内显示使用说明.
• git-rebase-confirm-cancel [User Option] 取消是否需要确认.

当使用 --rebase-merges 选项执行 rebase 时, 序列将包括几种其他类型的动作, 以下命令变得相关.

• l (git-rebase-label) 此命令插入 label 动作或编辑 point 处的一个.
• t (git-rebase-reset) 此命令插入 reset 动作或编辑 point 处的一个. 提示将提供当前 buffer 中存在的 labels.
• MM (git-rebase-merge) 此命令插入 merge 动作或编辑 point 处的一个. 提示将提供当前 buffer 中存在的 labels. 不支持通过 -c 或 -C 重用消息; merge 总是会调用编辑器.
• Mt (git-rebase-merge-toggle-editmsg) 此命令切换 point 处 merge 动作的 -C 和 -c 选项. 这些选项都指定应重用其消息的 commit. 小写变体指示 Git 在创建 merge 时调用编辑器, 允许用户编辑消息.

当 rebase 序列正在进行时, status buffer 具有一个 section, 列出已经应用的 commits 以及仍需应用的 commits.

Commits 分为两半. 当 rebase 在 commit 处停止时 (因为用户必须处理冲突或者因为他/她明确请求 rebase 在该 commit 处停止), point 位于分隔这两组的 commit 上, 即 HEAD. 它上面的 commits 尚未应用, 而 HEAD 和它下面的 commits 已经应用. 在这两组已应用和尚未应用的 commits 之间, 有时会有一个被丢弃的 commit.

每个 commit 都以一个单词为前缀, 并且这些单词还会以不同的颜色显示, 以指示 commits 的状态.

使用以下颜色:

• 使用与 default face 相同前景色显示的 Commits 尚未应用.
• 黄色 commits 与 rebase 停止处的 commit 有特殊关系. 这用于单词 "join", "goal", "same" 和 "work" (见下文).
• 灰色 commits 已经应用.
• 蓝色 commit 是 HEAD commit.
• 绿色 commit 是 rebase 序列停止处的 commit. 如果这与 HEAD 是同一个 commit (例如, 因为在 rebase 停止在该 commit 后你还没有做任何事情, 那么此 commit 显示为蓝色, 而不是绿色). 只有当你在 rebase 停止在某个 commit 后创建一个或多个新 commits 时, 才能同时存在绿色和蓝色 commit.
• 红色 commits 已被丢弃. 它们仅供参考, 例如以便更容易进行 diff.

当然这些颜色受使用的 color-theme 影响.

使用以下单词:

• 前缀为 pick, reword, edit, squash 和 fixup 的 Commits 尚未应用. 这些单词在这里的含义与在用于编辑 rebase 序列的 buffer 中的含义相同. 参见第 93 页的 [Editing Rebase Sequences]. 当指定了 --rebase-merges 选项时, 可能还会出现 reset, label 和 merge 行.
• 前缀为 done 和 onto 的 Commits 已经应用. 这样的 commit 可能是 HEAD, 在这种情况下它是蓝色的. 否则它是灰色的.
• 前缀为 onto 的 commit 是所有其他 commits 正在被 re-applied 之上的 commit. 此 commit 本身不需要被 re-applied, 它是 rebase 在开始 re-apply 其他 commits 之前回退到的 commit.
• 前缀为 done 的 Commits 已经 re-applied. 这包括已被 re-applied 的 commits, 但也包括你在 rebase 期间创建的新 commits.
• 所有其他 commits, 那些没有前缀以上任何单词的 commits, 以某种方式与 rebase 停止处的 commit 相关.

为了确定 commit 是否与停止处的 commit 相关, 比较它们的 hashes, trees 和 patch-ids¹. 为此目的不使用提交消息.

一般来说, 与停止处 commit 相关的 commits 可以具有任何使用的颜色, 尽管并非所有颜色/单词组合都是可能的.

用于停止处 commits 的单词是:

• 当 commit 前缀为 void 时, 表示 Magit 确信该 commit 中的所有更改均已使用几个新 commits 应用. 此 commit 从 HEAD 不再可达, 并且也不是恢复会话时将被应用的 commits 之一.
• 当 commit 前缀为 join 时, 表示 rebase 序列在该 commit 处停止是因为冲突 - 你现在必须将更改与已经应用的内容 join (merge). 从某种意义上说, 这是 rebase 停止处的 commit, 但虽然其效果已经在 index 和 worktree 中 (带有冲突标记), 但 commit 本身尚未实际应用 (它不是 HEAD). 所以它显示为黄色, 就像其他仍需应用的 commits 一样.
• 当 commit 前缀为 stop 或蓝色或绿色 same 时, 表示 rebase 在此 commit 处停止, 它仍然应用或已被再次应用, 并且至少其 patch-id 未更改.
  • 当 commit 前缀为 stop 时, 表示 rebase 在该 commit 处停止, 因为你之前请求那样做, 并且其 patch-id 未更改. 它甚至可能仍然是完全相同的 commit.
  • 当 commit 前缀为蓝色或绿色 same 时, 表示虽然其 tree 或 hash 发生了变化, 但其 patch-id 没有. 如果是蓝色, 那么它是 HEAD commit (像往常一样蓝色). 当它是绿色时, 那么它不再是 HEAD, 因为已经创建了其他 commit (但在继续 rebase 之前).
• 当 commit 前缀为 goal, 黄色 same 或 work 时, 表示 rebase 应用了该 commit, 但你随后将 HEAD 重置为较早的 commit (可能是为了将其拆分为多个 commits), 并且有一些未提交的更改剩余, 这些更改可能 (但不一定) 源自该 commit.
  • 当 commit 前缀为 goal 时, 表示仍然可以在不手动编辑任何文件的情况下, 通过提交 index 或通过 stage 所有更改然后提交来创建一个具有完全相同 tree ( "goal") 的新 commit. 当原始 tree 仍然以未污染的形式存在于 index 或 worktree 中时, 就是这种情况.
  • 当 commit 前缀为黄色 same 时, 表示不再可能创建一个具有完全相同 tree 的 commit, 但仍然可能创建一个具有相同 patch-id 的 commit. 如果你创建了一个带有其他更改的新 commit, 但原始 commit 的更改仍然以未污染的形式存在于 index 或 worktree 中, 就会出现这种情况.
  • 当 commit 前缀为 work 时, 表示你将 HEAD 重置为较早的 commit, 并且有一些 staged 和/或 unstaged 更改 (可能, 但不一定) 源自该 commit. 但是不再可能创建一个具有相同 tree 或至少相同 patch-id 的新 commit, 因为你已经做了其他更改.
• 当 commit 前缀为 poof 或 gone 时, 表示 rebase 应用了该 commit, 但你随后将 HEAD 重置为较早的 commit (可能是为了将其拆分为多个 commits), 并且没有未提交的更改.
  • 当 commit 前缀为 poof 时, 表示它不再从 HEAD 可达, 但已被一个或多个 commits 替换, 这些 commits 共同具有完全相同的效果.
  • 当 commit 前缀为 gone 时, 表示它不再从 HEAD 可达, 并且我们也无法确定其更改是否仍然在一个或多个新 commits 中生效. 它们可能是, 但如果是这样, 那么肯定还有其他更改, 使得无法确定.

如果你不完全理解上面的内容, 请不要担心. 没关系, 你会通过练习获得足够好的理解.

对于其他序列操作, 如 cherry-picking, 会显示类似的 section, 但由于用于实现它们的 git 命令的限制, 它们缺少上述一些功能. 最重要的是, 这些序列仅支持 "picking" 一个 commit, 而不支持其他动作如 "rewording", 并且它们不跟踪已经应用的 commits.

• V (magit-revert) 此 transient 前缀命令绑定以下 suffix 命令以及适当的 infix 参数, 并在临时 buffer 中显示它们, 直到调用 suffix.

当没有 cherry-pick 或 revert 正在进行时, transient 具有以下 suffix 命令.

• V V (magit-revert-and-commit) 通过创建新 commit 来 revert commit. 提示输入 commit, 默认为 point 处的 commit. 如果 region 选择多个 commits, 则 revert 它们所有, 不提示.
• V v (magit-revert-no-commit) 通过在 worktree 中反向应用它来 revert commit. 提示输入 commit, 默认为 point 处的 commit. 如果 region 选择多个 commits, 则 revert 它们所有, 不提示.

当 cherry-pick 或 revert 正在进行时, transient 改为具有以下 suffix 命令.

• V V (magit-sequence-continue) 恢复当前的 cherry-pick 或 revert 序列.
• V s (magit-sequence-skip) 在 cherry-pick 或 revert 序列期间跳过停止处的 commit.
• V a (magit-sequence-abort) 中止当前的 cherry-pick 或 revert 序列. 这会丢弃自序列开始以来所做的所有更改.

Transient 前缀命令 magit-remote 用于添加 remotes 和更改现有 remotes. 此命令仅处理 remotes 本身, 不处理分支或 commits 的传输. 这些功能可从单独的 transient 命令获得.

另请参阅 git-remote(1) manpage.

• M (magit-remote) 此 transient 前缀命令绑定以下 suffix 命令, 并在临时 buffer 中显示它们, 直到调用 suffix. 默认情况下, 它还绑定并显示一些 remote 相关 Git 变量的值, 并允许更改其值.
• magit-remote-direct-configure [User Option] 此选项控制 remote 相关 Git 变量是否可以直接从 transient magit-remote 访问. 如果为 t (默认) 且检出了本地分支, 则 magit-remote 具有该分支 upstream remote 的变量, 或者如果 HEAD 分离, 则为 origin (如果存在). 如果为 nil, 则必须使用 magit-remote-configure 来执行此操作.
• M C (magit-remote-configure) 此 transient 前缀命令绑定设置 remote 相关变量值的命令, 并在临时 buffer 中显示它们, 直到退出 transient. 带有前缀参数时, 此命令总是提示输入 remote. 不带前缀参数时, 这取决于它是否作为 magit-remote 的 suffix 调用以及 magit-remote-direct-configure 选项. 如果 magit-remote 已经显示 upstream 的变量, 那么调用另一个显示同一 remote 变量的 transient 是没有意义的. 在这种情况下, 此命令提示输入 remote. 变量在 [Remote Git Variables], 第 105 页中描述.
• M a (magit-remote-add) 此命令添加一个 remote 并 fetch 它. Remote 名称和 url 在 minibuffer 中读取.
• M r (magit-remote-rename) 此命令重命名 remote. 旧名称和新名称都在 minibuffer 中读取.
• M u (magit-remote-set-url) 此命令更改 remote 的 url. Remote 和新 url 都在 minibuffer 中读取.
• M k (magit-remote-remove) 此命令删除一个 remote, 在 minibuffer 中读取.
• M p (magit-remote-prune) 此命令为在 minibuffer 中读取的 remote 删除陈旧的远程跟踪分支.
• M P (magit-remote-prune-refspecs) 此命令为在 minibuffer 中读取的 remote 删除陈旧的 refspecs. 如果 remote 上不再存在至少一个将由于该 refspec 而被 fetched 的分支, 则 refspec 是陈旧的. 陈旧的 refspec 是有问题的, 因为它的存在导致 Git 拒绝根据剩余的非陈旧 refspecs 进行 fetch. 如果只剩下陈旧的 refspecs, 那么此命令提议删除 remote 或用默认 refspec ("+refs/heads/*:refs/remotes/REMOTE/*") 替换陈旧的 refspecs. 此命令还删除由于现在陈旧的 refspecs 而创建的远程跟踪分支. 其他陈旧的分支不被移除.
• magit-remote-add-set-remote.pushDefault [User Option] 此选项控制在添加 remote 后是否询问用户是否要设置 remote.pushDefault. 如果为 ask, 则总是询问用户. 如果为 ask-if-unset, 则仅当变量尚未设置时询问用户. 如果为 nil, 则不询问用户且不设置变量. 如果值为字符串, 则在添加的 remote 名称等于该字符串且变量尚未设置时, 无需询问用户即可设置变量.

这些变量可以从 transient 前缀命令 magit-remote-configure 设置. 默认情况下它们也可以从 magit-remote 设置. 参见第 104 页的 [Remote Commands].

• remote.NAME.url [Variable] 此变量指定名为 NAME 的 remote 的 url. 它可以有多个值.
• remote.NAME.fetch [Variable] 从名为 NAME 的 remote fetch 时使用的 refspec. 它可以有多个值.
• remote.NAME.pushurl [Variable] 此变量指定用于 push 到名为 NAME 的 remote 的 url. 如果未指定, 则使用 remote.NAME.url. 它可以有多个值.
• remote.NAME.push [Variable] push 到名为 NAME 的 remote 时使用的 refspec. 它可以有多个值.
• remote.NAME.tagOpts [Variable] 此变量指定默认 fetch 哪些 tags. 如果值为 --no-tags, 则不 fetch tags. 如果值为 --tags, 则 fetch 所有 tags. 如果此变量没有值, 则仅 fetch 可从 fetched 分支到达的 tags.

命令 magit-list-submodules 在单独的 buffer 中显示当前仓库的 submodules 列表. 也可以直接在超级仓库的 status buffer 中显示有关 submodules 的信息, 方法是将 magit-insert-modules 添加到 hook magit-status-sections-hook, 如第 38 页的 [Status Module Sections] 所述.

• magit-list-submodules [Command] 此命令在单独的 buffer 中显示当前仓库的已填充 submodules 列表. 可以通过在标题为 "Modules" 的 section 上按 RET 来调用它.
• magit-submodule-list-columns [User Option] 此选项控制命令 magit-list-submodules 显示哪些列以及如何显示它们. 每个元素的形式为 (HEADER WIDTH FORMAT PROPS). HEADER 是显示在 header 中的字符串. WIDTH 是列的宽度. FORMAT 是一个函数, 使用一个参数 (仓库标识, 通常是其 basename) 调用, 并且 default-directory 绑定到其工作树的顶层. 它必须返回要插入的字符串或 nil. PROPS 是一个支持键 :right-align, :pad-right 和 :sort 的 alist. :sort 函数有一个奇怪的接口, 在 tabulated-list--get-sort 的 docstring 中有描述. 或者可以使用 < 和 magit-repolist-version<, 因为这些函数会自动替换为满足接口的函数. 将 :sort 设置为 nil 以禁止排序; 如果未指定, 则列使用默认排序器排序. 你可能希望使用每列一个字符且列之间没有任何填充来显示一系列数字列, 在这种情况下, 你应该使用适当的 HEADER, 将 WIDTH 设置为 1, 并将 :pad-right 设置为 9. 对于大于 9 的数字, 用 + 替换.

• o (magit-submodule) 此 transient 前缀命令绑定以下 suffix 命令以及适当的 infix 参数, 并在临时 buffer 中显示它们, 直到调用 suffix.

下面的一些命令默认对使用 region 选择的 modules 进行操作. 为简便起见, 它们的描述谈论 "选定的 modules", 但如果未选择 modules, 则它们作用于当前 module, 或者如果 point 不在 module 上, 则读取单个 module 进行操作. 带有前缀参数时, 这些命令忽略 selection 和当前 module, 而是作用于所有合适的 modules.

• o a (magit-submodule-add) 此命令将位于 URL 的仓库添加为 module. 可选的 PATH 是相对于超级项目根目录的 module 路径. 如果为 nil, 则基于 URL 确定路径.
• o r (magit-submodule-register) 此命令通过将选定 modules 的 urls 从 ".gitmodules" 复制到 "$GIT_DIR/config" 来注册它们. 这些值可以在运行 magit-submodule-populate 之前进行编辑. 如果你不需要编辑任何 urls, 则直接使用后者.
• o p (magit-submodule-populate) 此命令创建选定 modules 的工作目录, 检出记录的 commits.
• o u (magit-submodule-update) 此命令更新选定 modules, 检出记录的 commits.
• o s (magit-submodule-synchronize) 此命令同步选定 modules 的 urls, 将值从 ".gitmodules" 复制到超级项目的 ".git/config" 以及 modules 的配置中.
• o d (magit-submodule-unpopulate) 此命令移除选定 modules 的工作目录.
• o l (magit-list-submodules) 此命令显示当前仓库 modules 的列表.
• o f (magit-fetch-modules) 此命令 fetch 所有已填充 modules. 带有前缀参数时, 它充当 transient 前缀命令, 允许调用者设置选项. 也 fetch 超级仓库, 因为 git fetch 不支持不这样做.

• magit-wip-merge-branch [User Option] 此选项控制在分支上创建新 commit 后, 当前分支是否合并到 wip refs 中. 如果为非 nil 且当前分支有新 commits, 则在创建新 wip commit 之前将其合并到 wip ref 中. 这使得更容易检查 wip 历史记录, 并且 wip commits 永远不会被垃圾回收. 如果为 nil 且当前分支有新 commits, 则在创建新 wip commit 之前将 wip ref 重置为分支的顶端. 使用此设置, wip commits 最终会被垃圾回收. 如果为 immediately, 则使用 git-commit-post-finish-hook 创建合并提交. 这不鼓励, 因为它可能导致竞争条件, 例如在 rebases 期间.

当 magit-wip-merge-branch 为 t 时, 历史记录如下所示:

~ ---------- refs/wip/index/refs/heads/master / / / A–—B–—C refs/heads/master ~

当 magit-wip-merge-branch 为 nil 时, 在真实分支上创建 commit 然后进行更改会导致 wip refs 被重新创建以从新 commit 分叉. 但 wip refs 上的旧 commits 不会丢失. 它们仍然可以从 reflog 中获得. 为了更容易看到 wip ref 的分叉点何时更改, 会在其上创建一个带有消息 "restart autosaving" 的附加 commit (下面的 xx0 commits 是此类边界 commits).

从以下开始:

~ BI0—BI1 refs/wip/index/refs/heads/master / A—B refs/heads/master \ BW0—BW1 refs/wip/wtree/refs/heads/master ~

提交 staged 更改并编辑保存文件将导致:

~ BI0—BI1 refs/wip/index/refs/heads/master / A—B—C refs/heads/master \ \ \ CW0—CW1 refs/wip/wtree/refs/heads/master \ BW0—BW1 refs/wip/wtree/refs/heads/master@{2} ~

直到 staged 某些更改之前, index wip ref 的分叉点不会改变. 同样, 仅仅检出分支或创建 commit 不会改变 worktree wip ref 的分叉点. 直到实际上有应该提交到相应 wip ref 的更改时, 分叉点才会被调整.

本节讨论了你可能出于安全原因想要更改 (或不更改) 的各种变量.

Git 将已提交的更改保留足够长的时间, 以便用户恢复意外删除的更改. 它不对 worktree 中的未提交更改, 甚至 index (staging area) 执行此操作. 因为 Magit 使修改未提交的更改变得如此容易, 所以在此过程中也很容易搬起石头砸自己的脚. 出于这个原因, Magit 提供了三个全局模式, 在某些操作之后或之前将 被跟踪 文件保存到 work-in-progress references. 参见第 117 页的 8.9 节 [Wip Modes].

出于性能考虑, 默认情况下不启用这些模式. 相反, 许多潜在的破坏性命令每次使用时都需要确认. 在许多情况下, 可以通过将符号添加到 magit-no-confirm (参见第 26 页的 [Completion and Confirmation]) 来禁用此功能. 如果你启用各种 wip 模式, 那么你应该将 safe-with-wip 添加到此列表中.

同样, 在将文件移动到系统垃圾箱之前不需要确认 - 如果你错误地删除了文件, 你可以从那里恢复它. 选项 magit-delete-by-moving-to-trash 控制是否使用系统垃圾箱, 默认情况下是这样. 尽管如此, trash 不是 magit-no-confirm 的成员 - 你可能想更改它.

默认情况下, 当访问的文件在磁盘上发生更改时, 访问文件的 buffers 会自动 reverted. 这并不像看起来那么危险, 但要做出明智的决定, 你应该参阅第 14 页的 [Risk of Reverting Automatically].

在 Magit 运行 git 产生副作用后, 它还会刷新当前 Magit buffer 和相应的 status buffer. 这是必要的, 因为否则可能会显示过时的信息而用户没有注意到. Magit buffers 通过从头开始重新创建其内容来更新, 这使得更新更简单且不易出错, 但也更昂贵. 保持简单并仅从头开始重新创建所有内容是一个旧的设计决策, 偏离它将需要重大的重构.

同时你可以告诉 Magit 仅自动刷新当前 Magit buffer, 而不刷新 status buffer. 如果你这样做, 那么 status buffer 仅在它是当前 buffer 时才自动刷新.

(setq magit-refresh-status-buffer nil)

你还应该检查是否有任何第三方包向 magit-refresh-buffer-hook, magit-pre-refresh-hook 和 magit-post-refresh-hook 添加了任何内容. 如果有, 则检查这些添加是否显著影响性能.

可以使用 M-x magit-toggle-verbose-refresh 告诉 Magit 详细刷新 buffers. 启用此功能有助于找出哪些 sections 是瓶颈. 打印到 *Messages* buffer 的每一行都包含 section 名称, 显示此 section 所花费的秒数, 以及 0 到 2 个感叹号: 感叹号越多, section 越慢.

当访问的文件在磁盘上更改时, Magit 也会 revert 位于当前仓库内的访问文件的 buffers. 这是在内置库 autorevert 的 auto-revert-mode 之上实现的. 要确定这是否影响性能, 请检查当存在许多 buffers 和/或当某些 buffers 使用 TRAMP 访问文件时, 性能是否明显变差. 如果是这样, 那么这应该会有所帮助.

(setq auto-revert-buffer-list-filter
      'magit-auto-revert-repository-buffer-p)

有关替代方法, 请参阅第 12 页的 [Automatic Reverting of File-Visiting Buffers].

如果你启用了任何默认禁用的功能, 那么你应该检查它们是否显著影响性能. 它们很可能因为已知会降低性能 (至少在大型仓库中) 而未默认启用.

如果性能仅在某些异常大的仓库中较慢, 那么你可能只想在每个仓库或每个仓库类的基础上禁用某些功能. 参见第 125 页的 9.1 节 [Per-Repository Configuration]. 例如, 在具有异常数量 tags 的仓库中确定下一个和当前 tag 需要很长时间. 因此, 最好禁用 magit-insert-tags-headers, 如上述节点中所释.

• magit-define-global-key-bindings [User Option] 此选项控制可以将哪组 Magit 键绑定 (如果有) 添加到全局 keymap, 即使在当前 Emacs 会话中首次使用 Magit 之前.

  • 如果值为 nil, 则不添加绑定.

  • 如果为 default, 可能添加:

    C-x g   magit-status
    C-x M-g magit-dispatch
    C-c M-g magit-file-dispatch
    

  • 如果为 recommended, 可能添加:

    C-x g magit-status
    C-c g magit-dispatch
    C-c f magit-file-dispatch
    

    这些绑定是强烈推荐的, 但我们不能默认使用它们, 因为 C-c <LETTER> 命名空间严格保留给用户添加的绑定 (参见 elisp 中的 "Key Binding Conventions").

  所选集合中的绑定可能会在运行 after-init-hook 时添加. 仅当那时没有其他键绑定到同一命令, 并且没有其他命令绑定到同一键时, 才会添加每个绑定. 换句话说, 我们尽量避免添加不必要的绑定, 以及与其他绑定冲突的绑定. 添加这些绑定延迟到运行 after-init-hook 之后, 允许用户在其 init 文件的任何位置设置变量 (而不必确保在加载或自动加载 magit 之前这样做), 并增加所有潜在冲突的用户绑定已经添加的可能性. 要设置此变量, 请使用 setq 或 Custom 接口. 不要使用函数 customize-set-variable, 因为这样做会导致在评估该形式时立即加载 Magit (这与 custom-set-variables 不同, 后者不加载定义自定义变量的库). 如果 after-init-hook 已经运行, 设置此变量没有效果.

这些函数运行 Git 以获取值, 退出状态或输出. 当然你也可以使用它们来运行具有副作用的 Git 命令, 但应避免这样做.

• magit-git-exit-code &rest args [Function] 使用 ARGS 执行 git 并返回其退出代码.
• magit-git-success &rest args [Function] 使用 ARGS 执行 git, 如果退出代码为 0 则返回 t, 否则返回 nil.
• magit-git-failure &rest args [Function] 使用 ARGS 执行 git, 如果退出代码为 1 则返回 t, 否则返回 nil.
• magit-git-true &rest args [Function] 使用 ARGS 执行 git, 如果 git 打印的第一行是字符串 "true", 则返回 t, 否则返回 nil.
• magit-git-false &rest args [Function] 使用 ARGS 执行 git, 如果 git 打印的第一行是字符串 "false", 则返回 t, 否则返回 nil.
• magit-git-insert &rest args [Function] 使用 ARGS 执行 git 并在 point 处插入其输出.
• magit-git-string &rest args [Function] 使用 ARGS 执行 git 并返回其输出的第一行. 如果没有输出或以换行符开头, 则返回 nil.
• magit-git-lines &rest args [Function] 使用 ARGS 执行 git 并将其输出作为行列表返回. 输出中任何位置的空行都被省略.
• magit-git-items &rest args [Function] 使用 ARGS 执行 git 并将其 null 分隔的输出作为列表返回. 输出中任何位置的空项都被省略.

如果选项 magit-git-debug 的值为非 nil 并且 git 以非零退出状态退出, 那么在 echo area 中警告并在当前仓库的 process buffer 中添加包含 git 标准错误的 section.

• magit-process-git destination &rest args [Function] 在单独的进程中同步调用 Git, 返回其退出代码. DESTINATION 指定如何处理输出, 类似于 call-process, 除了支持文件处理程序. 在调用期间启用 Cygwin 的 "noglob" 选项并确保 unix eol 转换.
• magit-process-file process &optional infile buffer display &rest args [Function] 在单独的进程中同步处理文件. 与 process-file 相同, 但在调用期间临时启用 Cygwin 的 "noglob" 选项并确保 unix eol 转换.

如果在使用上述函数之一时发生错误, 那么通常是因为 bug, 即使用了实际上不支持的参数. 此类错误通常不报告, 但当它们发生时我们需要能够调试它们.

• magit-git-debug [User Option] 是否报告在使用 magit-git-insert, magit-git-string, magit-git-lines 或 magit-git-items 时发生的错误. 这实际上并不引发错误. 相反, 在 echo area 中显示一条消息, 并将 git 的标准错误插入当前仓库 process buffer 的新 section 中.
• magit-git-str &rest args [Function] 这是 magit-git-string 的一个变体, 它忽略选项 magit-git-debug. 它主要旨在用于处理确实尊重该选项的函数中的错误时. 在处理错误时使用此类函数可能会导致另一个错误, 从而导致无限递归. 你可能永远不需要使用此函数.

这些函数用于运行 git 以产生某种效果. 大多数实际运行 git 的 Magit 命令都是通过使用此类函数来完成的.

因为我们在使用这些函数时不需要消耗 git 的输出, 所以它们的输出被记录到每个仓库的 buffer 中, 可以使用 Magit buffer 中的 $ 或其他地方的 M-x magit-process 显示.

这些函数可以通过两种不同的方式产生效果. 首先, 运行 git 可能会更改某些内容, 即创建或 push 新 commit. 其次, 该更改可能需要刷新 Magit buffers 以反映仓库的更改状态. 但刷新并不总是可取的, 因此只有其中一些函数在 git 返回后执行此类刷新.

有时异步运行 git 很有用. 例如, 当用户刚刚发起 push 时, 没有理由让她等待直到完成. 在其他情况下, 等待 git 完成后再让用户做其他事情是有意义的. 例如, 在 stage 更改后, 等待刷新完成很有用, 因为这也自动移动到下一个更改.

同步函数返回退出代码, 而异步函数返回进程对象.

• magit-call-git &rest args [Function] 使用 ARGS 同步调用 git.
• magit-call-process program &rest args [Function] 使用 ARGS 同步调用 PROGRAM.
• magit-run-git &rest args [Function] 使用 ARGS 同步调用 git 然后刷新.
• magit-run-git-with-input &rest args [Function] 使用 ARGS 同步调用 git 并将当前 buffer 的内容作为标准输入发送给它. 如果当前 buffer 的 default-directory 在远程文件系统上, 此函数实际上异步运行 git. 但随后它等待进程返回, 因此函数本身是同步的.
• magit-git &rest args [Function] 使用 ARGS 同步调用 git, 仅用于副作用. 此函数不刷新 buffer.
• magit-git-wash washer &rest args [Function] 使用 ARGS 执行 Git, 在 point 处插入 washed 输出. 实际上首先在 point 处插入原始输出. 如果没有输出调用 magit-cancel-section. 否则暂时将 buffer 缩小到插入的文本, 移动到其开头, 然后调用函数 WASHER 并将 ARGS 作为其唯一参数.

现在是异步变体.

• magit-run-git-async &rest args [Function] 启动 Git, 准备刷新, 并返回进程对象. ARGS 被扁平化然后用作 Git 的参数. 在 echo area 中显示命令行参数. Git 返回后, 一些 buffers 被刷新: 调用此函数时当前的 buffer (如果是 Magit buffer 且仍然存在), 以及相应的 Magit status buffer. 如果 magit-revert-buffers 为非 nil, 则访问当前仓库中被跟踪文件的未修改 buffers 被 reverted.
• magit-run-git-with-editor &rest args [Function] 导出 GIT_EDITOR 并启动 Git. 同时也准备刷新并返回进程对象. ARGS 被扁平化然后用作 Git 的参数. 在 echo area 中显示命令行参数. Git 返回后, 一些 buffers 被刷新: 调用此函数时当前的 buffer (如果是 Magit buffer 且仍然存在), 以及相应的 Magit status buffer.
• magit-start-git input &rest args [Function] 启动 Git, 准备刷新, 并返回进程对象. 如果 INPUT 为非 nil, 它必须是 buffer 或现有 buffer 的名称. buffer 内容成为进程的标准输入. 选项 magit-git-executable 指定 Git 可执行文件, 选项 magit-git-global-arguments 指定常量参数. 其余参数 ARGS 指定 Git 的参数. 它们在使用前被扁平化. Git 返回后, 一些 buffers 被刷新: 调用此函数时当前的 buffer (如果是 Magit buffer 且仍然存在), 以及相应的 Magit status buffer. 如果 magit-revert-buffers 为非 nil, 则访问当前仓库中被跟踪文件的未修改 buffers 被 reverted.
• magit-start-process &rest args [Function] 启动 PROGRAM, 准备刷新, 并返回进程对象. 如果可选参数 INPUT 为非 nil, 它必须是 buffer 或现有 buffer 的名称. buffer 内容成为进程的标准输入. 使用 start-file-process 启动进程, 然后设置使用 sentinel magit-process-sentinel 和过滤器 magit-process-filter. 这些函数所需的信息存储在进程对象中. 当此函数返回时, 进程尚未开始运行, 因此可以覆盖 sentinel 和过滤器. 进程返回后, magit-process-sentinel 刷新在调用 magit-start-process 时当前的 buffer (如果是 Magit buffer 且仍然存在), 以及相应的 Magit status buffer. 如果 magit-revert-buffers 为非 nil, 则访问当前仓库中被跟踪文件的未修改 buffers 被 reverted.
• magit-this-process [Variable] 即将启动的子进程. 这可以用来改变过滤器和 sentinel.
• magit-process-raise-error [Variable] 当此值为非 nil 时, 如果 git 以非零退出状态退出, magit-process-sentinel 将引发错误. 用于调试目的.

• magit-insert-section &rest args [Macro] 在 point 处插入一个 section. TYPE 是 section 类型, 一个符号. 许多作用于当前 section 的命令根据该类型表现不同. 此外, 如果存在变量 magit-TYPE-section-map, 则使用该 map 作为属于 section 的所有文本的文本属性 keymap (但这可能会在子 sections 中被覆盖). TYPE 也可以具有形式 (eval FORM), 在这种情况下 FORM 在运行时求值. 可选的 VALUE 是 section 的值, 通常是作用于 section 时所需的字符串. 当可选的 HIDE 为非 nil 时, 默认折叠 section 主体, 即首次创建 section 时, 但不是在刷新 buffer 时. 否则, 默认展开它. 这可以使用 magit-section-set-visibility-hook 覆盖. 当在刷新期间重新创建 section 时, 继承前任的可见性并忽略 HIDE (但仍然尊重 hook). BODY 是任意数量的实际插入 section 标题和主体的形式. 可选的 NAME, 如果指定, 必须是符号, 然后绑定到正在插入的 section 的结构体. 在评估 BODY 之前, section 对象的开始设置为 point 的值, 在评估 BODY 之后, 其结束设置为 point 的新值; BODY 负责向前移动 point. 如果在 BODY 内部发现 section 为空, 那么可以使用 magit-cancel-section 中止并删除部分插入的 section 的所有痕迹. 这可能发生在通过 washing Git 的输出创建 section 时, 而 Git 这次实际上没有输出任何内容.
• magit-insert-heading &rest args [Function] 插入当前正在插入的 section 的标题. 此函数只能在 magit-insert-section 内部使用. 当不带任何参数调用时, 仅将表示正在插入的 section 的对象的 content 槽设置为 point 处的标记. 像这样使用此函数时, section 应仅包含一行. 当带有参数 ARGS (必须是字符串) 调用时, 在 point 处插入这些字符串. 在这发生之前 section 不应包含任何文本, 之后它也应只包含一行. 如果这些字符串中的任何一个内部设置了 face 属性, 则按原样插入所有字符串. 否则对所有插入的文本使用 magit-section-heading face. section 结构的 content 属性是标题的结尾 (从 start 到 content) 和主体的开头 (从 content 到 end). 如果 content 的值为 nil, 则 section 没有标题并且其主体不能折叠. 如果 section 确实有标题, 那么其高度必须恰好是一行, 包括尾随换行符. 这不是强制执行的; 你负责正确处理. 唯一的例外是此函数会在必要时插入换行符.
• magit-cancel-section [Function] 取消当前正在插入的 section. 这将退出 magit-insert-section 的最内层调用, 并删除该调用内部已发生的所有痕迹.
• magit-define-section-jumper sym title &optional value [Function] 定义一个交互式函数以转到 section SYM. TITLE 是 section 的显示标题.

• magit-current-section [Function] 返回 point 处的 section.
• magit-region-sections &optional condition multiple [Function] 返回选定 sections 的列表. 当 region 处于活动状态并构成有效的 section selection 时, 返回所有选定 sections 的列表. 当 region 从一个 section 的标题开始并在同一 section 的标题或同级 section 的标题结束时, 就是这种情况. 如果可选的 MULTIPLE 为非 nil, 那么 region 不能在同一 section 中开始和结束. 当 selection 无效时, 返回 nil. 在这种情况下, 大多数可以作用于选定 sections 的命令将改为作用于 point 处的 section. 当 region 看起来像在任何其他 buffer 中那样时, selection 无效. 当 selection 有效时, region 使用 magit-section-highlight face. 这不适用于 diffs, 那里的情况稍微复杂一些, 但即使在这里, 如果 region 看起来像通常那样, 那么就此函数而言, 这不是一个有效的 selection. 如果可选的 CONDITION 为非 nil, 那么 selection 不仅必须有效; 所有选定的 sections 还必须匹配 CONDITION, 否则返回 nil. 参见 magit-section-match 了解 CONDITION 可以采取的形式.
• magit-region-values &optional condition multiple [Function] 返回选定 sections 的值的列表. 返回 magit-region-sections (见该条目) 本身会返回的值.

• M-x magit-describe-section-briefly 显示有关 point 处 section 的信息. 此命令用于调试目的.
• magit-section-ident section [Function] 返回 SECTION 的唯一标识符. 返回值的形式为 ((TYPE . VALUE)...).
• magit-get-section ident &optional root [Function] 返回由 IDENT 标识的 section. IDENT 必须是 magit-section-ident 返回的列表.

• magit-section-match condition &optional section [Function] 如果 SECTION 匹配 CONDITION, 则返回 t. SECTION 默认为 point 处的 section. 如果未指定 SECTION 且 point 处也没有 section, 则返回 nil. CONDITION 可以采取以下形式:

  • (CONDITION...): 如果任何 CONDITION 匹配, 则匹配.
  • [CLASS...]: 如果 section 的类与第一个 CLASS 相同或者是其子类; section 的父类匹配第二个 CLASS; 依此类推, 则匹配.
  • [* CLASS...]: 匹配匹配 [CLASS...] 的 sections 以及递归匹配其所有子 sections.
  • CLASS: 如果 section 的类与 CLASS 相同或者是其子类, 则匹配; 无论父 sections 的类如何.

  每个 CLASS 应该是一个类符号, 标识派生自 magit-section 的类. 为了向后兼容, CLASS 也可以是一个 "类型符号". 如果其 type 槽的值是 eq, 则 section 匹配这样的符号. 如果类型符号在 magit--section-type-alist 中有条目, 那么如果其类是对应于该类型 (根据该 alist) 的类的子类, 则 section 也匹配该类型. 注意不需要指定 magit-describe-section-briefly 打印的完整 section 谱系, 除非你当然想要那么精确.

• magit-section-value-if condition &optional section [Function] 如果 point 处的 section 匹配 CONDITION, 则返回其值. 如果可选的 SECTION 为非 nil, 则测试它是否匹配. 如果 point 处没有 section 且 SECTION 为 nil, 则返回 nil. 如果 section 不匹配, 则返回 nil. 参见 magit-section-match 了解 CONDITION 可以采取的形式.
• magit-section-case &rest clauses [Function] 在 point 处 section 的类型上选择子句. 每个子句看起来像 (CONDITION BODY...). 将 section 的类型与每个 CONDITION 进行比较; 顺序评估第一个匹配项的 BODY 形式, 并返回最后一个形式的值. 在 BODY 内部, 符号 it 绑定到 point 处的 section. 如果没有子句成功或 point 处没有 section, 返回 nil. 参见 magit-section-match 了解 CONDITION 可以采取的形式. 此外, 允许在最后一个子句中使用 CONDITION t, 如果没有其他 CONDITION 匹配, 则匹配, 即使 point 处没有 section.
• magit-root-section [Variable] 当前 buffer 中的根 section. 所有其他 sections 都是此 section 的后代. 此变量的值由 magit-insert-section 设置, 你永远不应该修改它.

对于 diff 相关 sections, 存在一些额外的工具.

• magit-diff-type &optional section [Function] 返回 SECTION 的 diff 类型. 返回的类型是符号 staged, unstaged, committed 或 undefined 之一. 此类型与所有 sections 通用的通用类型 (存储在相应 magit-section 结构体的 type 槽中) 具有类似的目的, 但考虑了额外的信息. 当 SECTION 与 diffs 无关且包含它的 buffer 也不是仅 diff buffer 时, 返回 nil. 目前类型也可以是 tracked 和 untracked 之一, 但这些值并未在每个应该处理的地方显式处理. 可能的修复方法是在这里直接返回 nil. Section 必须是 diff 或 hunk section, 或子项为 diff 类型的 section. 如果可选的 SECTION 为 nil, 返回当前 section 的 diff 类型. 在其主模式为 magit-diff-mode 的 buffers 中, SECTION 被忽略, 类型使用其他方式确定. 在 magit-revision-mode buffers 中, 类型始终为 committed.
• magit-diff-scope &optional section strict [Function] 返回 SECTION 或选定 section(s) 的 diff 范围. Diff 的 "scope" 描述选择了 diff 的哪一部分, 它是一个符号, region, hunk, hunks, file, files 或 list 之一. 不要将其与 magit-diff-type 返回的 diff "type" 混淆. 如果可选的 SECTION 为非 nil, 则返回它的范围, 忽略 region 选择的 sections. 否则返回当前 section 的范围, 或者如果 region 处于活动状态并选择了一组有效的 diff 相关 sections, 则返回这些 sections 的类型, 即 hunks 或 files. 如果 SECTION (或如果 nil 为当前 section) 是 hunk section 并且 region 在该 section 的主体内开始和结束, 则类型为 region. 如果可选的 STRICT 为非 nil, 那么如果 point 处的 section 的 diff 类型为 untracked 或 point 处的 section 实际上不是 diff 而是 diffstat section, 则返回 nil.

默认主题使用蓝色表示本地分支, 绿色表示远程分支, 金麒麟色 (棕黄色) 表示 tags. 创建新主题时, 你可能应该遵循该示例. 如果你的主题已经使用其他颜色, 则坚持使用这些颜色.

在旧版本中, 这些 reference faces 曾经有背景颜色和周围的框. 基本默认 faces 不再这样做, 以使 Magit buffers 不那么嘈杂, 你应该至少在框方面遵循该示例. (过去使用框是为了解决高亮覆盖层和文本属性背景之间的冲突. 这不再是必要的, 因为高亮不再导致其他背景颜色消失.) 或者你可以保留背景颜色和/或框, 但随后必须特别注意相应地调整 magit-branch-current. 默认情况下, 它看起来主要像 magit-branch-local, 但带有一个框 (默认情况下, 前者是唯一使用框的 face, 正是为了让它突出). 如果前者也使用框, 那么你必须确保它在其他方面与后者不同.

最难主题化的 faces 是那些与 diffs, 标题, 高亮和 region 相关的 faces. 有些 faces 属于所有这四组 - 预计要花一些时间才能弄好.

默认主题中的 region face, 无论是浅色还是深色变体, 以及随 Emacs 分发或由第三方分发的许多其他主题中, 都非常丑陋. 通常使用非常突出的背景颜色, 这很丑陋, 但如果这是唯一的问题, 那是可以接受的. 不幸的是, 许多主题还设置了前景色, 这确保了 region 内的所有文本都是可读的. 如果不这样做, 可能会出现某些前景色太接近 region 背景色而无法阅读的情况. 但这也意味着 region 内的文本会丢失所有语法高亮.

我认为在使 region face 正确方面所做的工作是衡量主题一般质量的一个很好的指标. 我对 region face 的建议是: 使用与 default face 的背景颜色略有不同的背景颜色, 并且根本不设置前景色. 因此, 对于浅色主题, 你可以使用浅灰色 (可能有色调) 作为 default 的背景颜色, 并使用稍深的灰色作为 region 的背景. 这通常应该足以不与任何其他 face 的前景色冲突. 但是, 如果其他一些 faces 也设置了浅灰色作为背景颜色, 那么你也应该确保它不与那些冲突 (尽管在某些情况下可能是可以接受的).

Magit 仅在 region 根据其自身定义 "无效" 时才使用 region face. 在 Magit buffer 中, region 用于选择多个同级 sections, 以便支持它的命令作用于所有这些 sections 而不仅仅是当前 section, 或者用于在单个 hunk section 内选择行. 在所有其他情况下, section 被认为是无效的, Magit 不会对其采取行动. 但这种无效 sections 会发生, 要么是因为用户尚未将 point 移动到足够远以使其有效, 要么是因为她想使用非 magit 命令来作用于 region, 例如 kill-region.

因此, 对无效 sections 使用常规 region face 是一个特性. 它告诉用户 Magit 将无法对其采取行动. 如果那个 face 看起来有点奇怪, 甚至 (如果不那么严重) 如果它与 section 标题和其他具有背景颜色的东西的背景颜色冲突, 也是可以接受的.

Magit 高亮显示当前 section. 如果一个 section 有子 sections, 那么所有子 sections 都会被高亮显示. 这是使用名称中带有 "highlight" 的 faces 完成的. 对于大多数 sections, magit-section-highlight 用于主体和标题. 像 region face 一样, 它应该只将背景颜色设置为类似于 default 的颜色. highlight 背景颜色必须与 region 背景颜色和 default 背景颜色都不同.

对于 diff 相关 sections, Magit 使用各种 faces 来高亮显示所选 section(s) 的不同部分. 请注意, 与所有其他 section 标题不同, hunk 标题默认具有背景颜色, 因为拥有非常明显的 hunks 分隔符很有用. face magit-diff-hunk-heading 应该不同于 magit-diff-hunk-heading-highlight 和 magit-section-highlight, 以及 magit-diff-context 和 magit-diff-context-highlight. 默认情况下, 我们通过更改前景色来做到这一点. 更改背景颜色会导致并发症, 并且我们已经有足够多无法绕过的问题了. (还要注意, 让 section 标题始终为粗体通常是个好主意, 但仅限于有子 sections 的 sections).

当存在有效的 region 选择 diff 相关同级 sections (即多个文件或 hunks) 时, 所有这些 sections 的主体都使用相应的 highlight faces, 但除此之外, 标题改用 magit-diff-file-heading-selection 或 magit-diff-hunk-heading-selection faces 之一. 这些 faces 必须与常规 highlight 变体不同, 以提供 region 处于活动状态的明确视觉指示.

在主题化 diff 相关 faces 时, 首先将选项 magit-diff-refine-hunk 设置为 all. 你个人可能更喜欢只 refine 当前 hunk 或根本不使用 hunk refinement, 但你的主题的一些用户希望所有 hunks 都被 refined, 所以你必须迎合这一点.

(还要打开 magit-diff-highlight-indentation, magit-diff-highlight-trailing, 和 magit-diff-paint-whitespace; 并在你用于测试的代码中插入一些空白错误.)

对于添加的行, 你必须调整三个 faces: magit-diff-added, magit-diff-added-highlight, 和 diff-refined-added. 确保后者与前两者以及 smerge-other 和 diff-added 配合良好. 然后对删除的行, 上下文行, 我们添加的行和他们添加的行做同样的事情. 还要确保相应的 added, removed 和 context faces 对于 highlighted 和 unhighlighted 变体使用大致相同的饱和度. 还要确保文件和 diff 标题与 context lines 配合良好 (例如, 使它们看起来不同). Line faces 应该同时设置前景和背景颜色. 例如, 对于添加的行, 使用两种不同的绿色.

如果 highlighted 和 unhighlighted 变体的前景色相同是最好的, 所以你需要找到一种在 highlight 和 unhighlighted 背景, refine 背景以及 highlight context 背景上都表现良好的颜色. 当存在 hunk 内部 region 时, added- 和 removed-lines 背景颜色仅在该 region 内使用. region 外部使用 highlighted context 背景颜色. 这使得更容易看到什么正在被 staged. 带有 hunk 内部 region 时, hunk 标题使用 magit-diff-hunk-heading-selection 显示, 并且在落在 region 内的行周围添加细线. 它的背景颜色必须与涉及的各种其他背景颜色有明显的区别.

没人说这会很容易. 如果你的主题限制自己使用一组特定的颜色, 那么你应该在这里破例. 否则不可能让 diffs 在每一个变体中都看起来很好. 实际上你可能只想坚持这些 faces 的默认定义. 你已经被警告过了. 另外请注意, 如果你没弄好, 在某些情况下这看起来就像 Magit 中的 bug - 所以请做好它, 或者根本别做.

mu[m's] git 或 magi{c => t} 都可以.

口号是 "It's Magit! The magical Git client" (是 Magit! 神奇的 Git 客户端), 所以像 magic 一样发音 Magit 是有道理的, 同时考虑到 C 和 T 的发音不同.

德语 "Magie" 的发音与英语 "magic" 不同, 所以如果你说德语, 那么你可以使用上述理由来证明使用前一种发音是正当的; Mag{ie => it}.

你也可以仅仅因为你更喜欢它而选择前一种发音.

另请参见 https://magit.vc/assets/videos/magic.mp4. 另请参见 https://emacs.stackexchange.com/questions/13696.

要显示最近运行的 git 命令的输出, 按 $ (或者, 如果不可用, 使用 M-x magit-process-buffer). 这显示一个包含每个 git 调用 section 的 buffer; 像往常一样按 TAB 展开或折叠它们.

默认情况下, 只有当 git 为副作用运行时, 其输出才会插入 process buffer. 当输出以某种方式被消耗时, 将其也插入 process buffer 会太昂贵. 出于调试目的, 可以使用 M-x magit-toggle-git-debug 强制这样做.

Git 的 manpages 可以导出为名为 gitman 的 info 手册. Magit 自己的 info 手册链接到该手册中的节点而不是实际的 manpages, 仅仅因为 Info 不支持链接到 manpages.

不幸的是, 一些发行版默认不安装 gitman 手册, 你必须安装单独的文档包才能获得它.

Magit 修补了 info, 增加了访问指向 gitman info 手册链接的能力, 改为查看相应的 manpage. 如果你更喜欢那种方法, 那么将 magit-view-git-manual-method 的值设置为受支持的 Emacs 包 man 或 woman 之一, 例如:

(setq magit-view-git-manual-method 'man)

Git 支持显示加密文件的 diffs, 但必须被告知这样做. 由于 Magit 只是使用 Git 来获取 diffs, 配置 Git 也会影响 Magit 内部显示的 diffs.

git config --global diff.gpg.textconv "gpg --no-tty --decrypt"
echo "*.gpg filter=gpg diff=gpg" > .gitattributes

请参阅第 81 页的 6.6 节 [Branching], 以及 https://emacsair.me/2016/01/18/magit-2.4

如果你不使用 VC (内置版本控制接口), 那么你可能会想禁用它, 尤其是因为我们曾经建议你这样做.

我们不再建议你禁用 VC. 这样做会破坏依赖于 VC 启用的有用的第三方包 (如 diff-hl).

如果你无论如何都选择禁用 VC, 那么你可以通过更改 vc-handled-backends 的值来做到这一点.

参见第 126 页的 [Performance], 以及第 144 页的 [I changed several thousand files at once and now Magit is unusable].

Magit 目前不期望在这种条件下工作良好. 如果能这就太好了. 在这种条件下达到令人满意的性能将需要进行大量的重构. 这不是一个小任务, 但我希望能最终找到时间来实现它.

但目前我们建议你使用命令行来完成这一个提交.

另请参见第 126 页的 [Performance].

这很可能意味着 Magit 在寻找合适的 emacsclient 可执行文件时遇到问题. 参见 with-editor 中的 "Configuring With-Editor" 一节和 with-editor 中的 "Debugging" 一节.

几乎可以肯定 Magit 只是这个问题附带的. 这更有可能是一个配置问题, 即使你可以在命令行上推送.

详细的设置说明可以在 https://github.com/magit/magit/wiki/Pushing-with-Magit-from-Windows 找到.

这通常发生是因为 Emacs 没有与你的 shell 相同的环境变量. 尝试安装并配置 https://github.com/purcell/exec-path-from-shell. 默认情况下它同步 $PATH, 这有助于 Magit 找到你在 shell 上使用的同一个 git.

如果 SOMETHING 是 "使用 gpg-agent 进行提交和/或 tag 签名的密码缓存", 那么你还需要同步 $GPG_AGENT_INFO.

这可能是由 diff.* Git 变量的自定义引起的. 你可能出于某种原因设置了该变量, 因此应该只通过自定义 magit-git-global-arguments 在 Magit 中撤消该设置.

Magit 和 git-commit.el 都没有在用于编写提交消息的 buffer 中摆弄 point, 所以一定是其他东西在做这件事.

你可能全局启用了一种模式, 该模式在文件访问 buffers 中恢复 point. 这可能有点令人惊讶, 但是当你编写提交消息时, 你实际上是在编辑文件.

所以你必须找出哪个包在做这件事. saveplace, pointback, 和 session 是可能的候选者. 这些代码片段可能会有所帮助:

(setq session-name-disable-regexp "\\(?:\\~'\\.git/[A-Z_]+\\'\\)")

(with-eval-after-load 'pointback
  (lambda ()
    (when (or git-commit-mode git-rebase-mode)
      (pointback-mode -1))))

Magit 不负责在 mode-line 中显示的看起来像 Git-master 的版本控制信息. 内置的 "Version Control" 包, 也称为 "VC", 更新该信息, 并且可以被告知更频繁地这样做:

(setq auto-revert-check-vc-info t)

但这样做对性能不利. 有关更多 (过于乐观的) 信息, 请参阅 emacs 中的 "VC Mode Line" 一节.

如果你真的不关心在 mode-line 中看到此信息, 而只是不想看到不正确的信息, 那么考虑干脆不在 mode-line 中显示它:

(setq-default mode-line-format
              (delete '(vc-mode vc-mode) mode-line-format))

或者更一般地说, 模棱两可的 refnames 破坏了某些东西.

Magit 假设 refs 在 "refs/heads/", "refs/tags/", 和 "refs/remotes/" 命名空间中非模棱两可地命名 (即, 当剥离这些前缀时, 所有名称保持唯一). 我们认为不支持模棱两可的 refnames, 并建议你使用非模棱两可的命名方案. 但是, 如果你确实在处理具有模棱两可 refnames 的仓库, 请报告你遇到的任何问题, 以便我们可以调查是否有简单的修复方法.

当 Magit 调用 git 时, 它会添加一些全局参数, 包括 --literal-pathspecs, 并且由 Magit 启动的 git 进程随后将该设置传递给它自己启动的其他 git 进程. 它通过设置环境变量 GIT_LITERAL_PATHSPECS 来做到这一点, 而不是通过使用 --literal-pathspecs 参数调用子进程. 因此你可以在 hook 脚本中使用 unset GIT_LITERAL_PATHSPECS 覆盖此设置.

原因是 git-commit.el 尚未加载和/或服务器尚未启动. 当你从 Magit 提交时, 这些事情总是已经处理好了, 因为为了这样做, 必须加载 Magit, 而这样做涉及加载 git-commit 并启动服务器.

如果你想从命令行提交, 那么你必须自己处理这些事情. 你的 init.el 文件应包含:

(require 'git-commit)
(server-mode)

你可以使用 (load "/path/to/magit-autoloads.el") 代替 (require 'git-commit). 你可能想这样做, 因为加载 git-commit 会导致 Magit 的大部分内容被加载.

还有一些 (server-mode) 的变体你可能想尝试. 我个人使用:

(use-package server
  :config (or (server-running-p) (server-mode)))

现在你可以使用:

$ emacs&
$ EDITOR=emacsclient git commit

但是你不能使用:

$ killall emacs
$ EDITOR="emacsclient --alternate-editor emacs" git commit

这实际上最终会使用 emacs, 而不是 emacsclient. 如果你这样做, 那么你仍然可以编辑提交消息, 但不会使用 git-commit-mode, 并且你必须退出 emacs 才能完成该过程.

前方同义反复. 如果你想能够使用 emacsclient 连接到正在运行的 emacs 实例, 即使没有 emacs 实例在运行, 那么你不能直接使用 emacsclient.

相反, 你必须创建一个脚本来执行类似以下操作: 尝试使用 emacsclient (不使用 --alternate-editor). 如果成功, 什么也不做. 否则启动 emacs & (并且 init.el 必须调用 server-start) 并再次尝试使用 emacsclient.

当你对 hunk 键入 RET 以访问相应文件中的相应位置时, 可能会发生这种情况. 这个问题的一个解决方案是使用 global-reveal-mode. 它确保 point 周围的文本总是可见的. 如果这对你的口味来说太激烈了, 那么你可以改用 magit-diff-visit-file-hook 来显示文本, 可能使用 reveal-post-command 或对于 Org buffers 使用 org-reveal.

Magit 过去使用 Magit-Popup 来实现 transient 弹出菜单. 现在它改用 Transient, 它是 Magit-Popup 的继承者.

在旧的 Magit-Popup 菜单中, 可以通过在弹出 buffer 中使用 C-c C-c 来保存用户设置 (例如, 设置 commits 的 gpg 签名密钥). 这将关闭弹出窗口, 但保存设置作为未来弹出窗口的默认值.

当切换到 Transient 菜单时, 此功能现在改为通过 C-x C-s 提供; 当使用 Transient 时, C-x 前缀还有其他选项, 键入时会显示. 有关更多详细信息, 请参阅 https://magit.vc/manual/transient/Saving-Values.html#Saving-Values.