简体中文 ▾ 主题 ▾ 最新版本 ▾ gitcli 最后更新于 2.52.0

名称

gitcli - Git 命令行接口和约定

概要

gitcli

描述

本手册描述了 Git CLI 中使用的约定。

许多命令将其参数接受为修订版本（最常是“提交”，但有时是“树形对象”，具体取决于上下文和命令）和路径。以下是规则

  • 选项在前，参数在后。子命令可以接受带连字符的选项（这些选项可能带有自己的参数，例如 `--max-parents 2`）和参数。您应先给出带连字符的选项，然后给出参数。一些命令可能会在您已经给出非选项参数后接受带连字符的选项（这可能会使命令变得含糊不清），但您不应依赖它（因为我们最终可能会找到一种方法来强制执行“选项在前，参数在后”的规则来解决这些歧义）。

  • 修订版本在前，路径在后。例如，在 `git diff v1.0 v2.0 arch/x86 include/asm-x86` 中，`v1.0` 和 `v2.0` 是修订版本，`arch/x86` 和 `include/asm-x86` 是路径。

  • 当一个参数可能被误解为修订版本或路径时，可以通过在它们之间放置 `--` 来消歧。例如，`git diff -- HEAD` 的意思是“我在工作目录中有一个名为 HEAD 的文件。请显示暂存区版本和工作目录版本之间的更改”，而不是“显示 HEAD 提交和整个工作目录之间的差异”。您可以说 `git diff HEAD --` 来请求后者。

  • 如果不使用消歧 `--`，Git 会做出合理的猜测，但当出现歧义时，它会报错并要求您进行消歧。例如，如果您的工作目录中有一个名为 HEAD 的文件，`git diff HEAD` 就是模糊的，您必须说 `git diff HEAD --` 或 `git diff -- HEAD` 来消歧。

  • 由于 `--` 在某些命令中用于消歧修订版本和路径，因此不能用于将选项和修订版本分开。您可以使用 `--end-of-options` 来实现此目的（对于不区分修订版本和路径的命令，它也有效，在这种情况下，它只是 `--` 的别名）。

    在编写预期要处理随机用户输入的脚本时，最好通过在适当的位置放置消歧 `--` 来明确哪些参数是哪些。

  • 许多命令允许在路径中使用通配符，但您需要保护它们不被 shell 扩展。以下两个命令的意思不同

    $ git restore *.c
$ git restore \*.c

    前者允许您的 shell 扩展文件通配符，并要求您工作目录中的 .C 文件被索引版本覆盖。后者将 `*.c` 传递给 Git，并要求索引中与模式匹配的路径被检出到您的工作目录。在运行 `git add hello.c; rm hello.c` 之后，您将 *不会* 在工作目录中看到 `hello.c`，但使用后者时会。

  • 正如文件系统中的 `*.*`（点）指代当前目录一样，在 Git 中使用 `.` 作为仓库名（点仓库）是一个相对路径，表示您当前的仓库。

以下是您在编写 Git 脚本时应遵循的关于“标志”的规则

  • 将短选项拆分成单独的单词（优先使用 `git foo -a -b` 而不是 `git foo -ab`，后者甚至可能不起作用）。

  • 当命令行选项接受参数时，请使用 *粘合* 形式。也就是说，对于短选项，写成 `git foo -oArg` 而不是 `git foo -o Arg`；对于长选项，写成 `git foo --long-opt=Arg` 而不是 `git foo --long-opt Arg`。接受可选选项参数的选项必须写成 *粘合* 形式。

  • 尽管有上述建议，但当 Arg 是相对于用户主目录的路径时，例如 `~/directory/file` 或 `~u/d/f`，您可能希望使用分开的形式，例如 `git foo --file ~/mine`，而不是 `git foo --file=~/mine`。在这种情况下，shell 会将 `~/` 扩展到您的主目录，但大多数 shell 会在后一种情况中保留波浪号。我们的一些命令知道如何对选项值进行波浪号扩展，即使是粘合形式，但并非所有命令都这样做。

  • 当您向命令提供修订版本参数时，请确保该参数与工作目录中的文件名不混淆。例如，不要写 `git log -1 HEAD`，而应写 `git log -1 HEAD --`；如果您恰好在工作目录中有一个名为 `HEAD` 的文件，前者将不起作用。

  • 许多命令允许长选项 `--option` 被缩短为其唯一前缀（例如，如果不存在以 `opt` 开头的其他选项名称，您可以通过键入 `--opt` 来调用 `--option` 标志），但在编写脚本时，您应该完整地拼写它们；Git 的后续版本可能会引入一个名称共享相同前缀的新选项，例如 `--optimize`，从而使以前唯一的前缀不再唯一。

增强的选项解析器

从 Git 1.5.4 系列及之后，许多 Git 命令（撰写本文时并非全部）都配备了增强的选项解析器。

以下是此选项解析器提供的功能列表。

特殊选项

已激活增强选项解析器的命令都支持几个特殊的命令行选项

-h

提供命令的格式化用法。

$ git describe -h
usage: git describe [<options>] <commit-ish>*
   or: git describe [<options>] --dirty

    --contains            find the tag that comes after the commit
    --debug               debug search strategy on stderr
    --all                 use any ref
    --tags                use any tag, even unannotated
    --long                always use long format
    --abbrev[=<n>]        use <n> digits to display SHA-1s

请注意，某些子命令（例如 `git grep`）在命令行上除了 `-h` 之外还有其他内容时，行为可能不同，但 `git subcmd -h` 在命令行上没有其他内容时，始终会显示用法。

--help-all

一些 Git 命令接受仅用于内部或已弃用的选项，这些选项在默认用法中被隐藏。此选项提供完整的选项列表。

否定选项

长选项名称的选项可以通过添加前缀 `--no-` 来否定。例如，`git branch` 有一个默认值为 *开启* 的 `--track` 选项。您可以使用 `--no-track` 来覆盖该行为。对于 `--color` 和 `--no-color` 也是如此。

选项优先于配置和环境变量

当存在一个用于调整 Git 命令某个方面行为的配置变量或环境变量，并且还有一个用于调整同一方面的命令行选项时，命令行选项会覆盖配置和/或环境变量的设置。

例如，`user.name` 配置变量用于指定 `git commit` 命令在创建新提交时记录作者和提交者名称所使用的人类可读名称。如果设置了 `GIT_AUTHOR_NAME` 环境变量，它在决定记录哪个作者姓名时具有优先权。如果提供了 `git commit` 命令的 `--author=<author>` 命令行选项，它将优先于这两种信息来源。

聚合短选项

支持增强选项解析器的命令允许您聚合短选项。这意味着您可以使用例如 `git rm -rf` 或 `git clean -fdx`。

缩写长选项

支持增强选项解析器的命令接受长选项的唯一前缀，就如同完全拼写出来一样，但请谨慎使用。例如，`git commit --amen` 的行为就如同您输入了 `git commit --amend`，但这只在 Git 的后续版本引入共享相同前缀的另一个选项（例如 `git commit --amenity` 选项）之前是正确的。

将参数与选项分开

您可以将选项的强制参数写成命令行上的一个单独的单词。这意味着以下所有用法都有效

$ git foo --long-opt=Arg
$ git foo --long-opt Arg
$ git foo -oArg
$ git foo -o Arg

但是，对于具有可选值的开关，这是 **不允许** 的，在这种情况下必须使用 *粘合* 形式

$ git describe --abbrev HEAD     # correct
$ git describe --abbrev=10 HEAD  # correct
$ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT

特殊文件名选项

接受文件名的选项允许使用前缀 `:（可选）`。例如

git commit -F :(optional)COMMIT_EDITMSG
# if COMMIT_EDITMSG does not exist, the above is equivalent to
git commit

与配置值一样，如果指定的文件不存在，Git 的行为就如同该选项未被给出。请参阅 `git-config[1]` 中的“值”。

关于易混淆选项的说明

许多可以在工作目录文件和/或暂存区文件上操作的命令可以接受 `--cached` 和/或 `--index` 选项。有时人们错误地认为，由于暂存区最初被称为缓存，所以这两个选项是同义词。它们 **不是** 同义词 — 这两个选项的意思大相径庭。

  • `--cached` 选项用于要求一个通常作用于工作目录文件的命令 **仅** 作用于暂存区。例如，`git grep` 在没有指定要从中查找字符串的提交时，通常作用于工作目录文件，但使用 `--cached` 选项时，它会在暂存区中查找字符串。

  • `--index` 选项用于要求一个通常作用于工作目录文件的命令 **也** 影响暂存区。例如，`git stash apply` 通常将暂存条目中记录的更改合并到工作目录，但使用 `--index` 选项时，它也会将更改合并到暂存区。

`git apply` 命令可以与 `--cached` 和 `--index` 一起使用（但不能同时使用）。通常该命令只影响工作目录中的文件，但使用 `--index` 时，它会同时修补文件及其暂存区条目，使用 `--cached` 时，它只修改暂存区条目。

有关更多信息，请参阅 https://lore.kernel.org/git/7v64clg5u9.fsf@assigned-by-dhcp.cox.net/ 和 https://lore.kernel.org/git/7vy7ej9g38.fsf@gitster.siamese.dyndns.org/。

其他一些同样可以在工作目录文件和/或暂存区文件上操作的命令可以接受 `--staged` 和/或 `--worktree`。

  • `--staged` 与 `--cached` 完全相同，用于要求命令仅作用于暂存区，而不作用于工作目录。

  • `--worktree` 则相反，用于要求命令仅作用于工作目录，而不作用于暂存区。

  • 这两个选项可以一起指定，以要求命令同时作用于暂存区和工作目录。

GIT

Git[1] 套件的一部分