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

名称

gitcli - Git 命令行接口和约定

概要

gitcli

描述

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

许多命令以修订（最常见的是“提交”，但有时根据上下文和命令是“tree-ish”）和路径作为参数。以下是规则

  • 选项在前，参数在后。子命令可以带破折号选项（它们可以有自己的参数，例如“--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

魔法文件名选项

接受文件名的选项允许前缀 :(optional)。例如

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] 套件的一部分