Git
英语 ▾ 主题 ▾ 最新版本 ▾ gitcli 最后更新于 2.45.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。需要可选选项参数的选项必须以粘连形式编写。

  • 当你向命令提供修订版参数时，确保参数与工作树中文件的名称没有歧义。例如，不要写 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 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

关于经常混淆的选项的说明

许多可以在工作树和/或索引中的文件上工作的命令都可以接受 --cached 和/或 --index 选项。有时人们错误地认为，因为索引最初称为缓存，所以这两个选项是同义词。它们不是——这两个选项的含义大不相同。

  • --cached 选项用于要求通常在工作树中的文件上工作的命令仅使用索引。例如，git grep 在不使用提交来指定要从中查找字符串的提交时，通常在工作树中的文件上工作，但使用 --cached 选项时，它会在索引中查找字符串。

  • --index 选项用于要求通常在工作树中的文件上工作的命令也影响索引。例如，git stash apply 通常将存储在存储条目中的更改合并到工作树中，但使用 --index 选项时，它也会将更改合并到索引中。

git apply 命令可以与 --cached 和 --index 选项一起使用（但不能同时使用）。通常情况下，该命令只影响工作树中的文件，但使用 --index 时，它会同时修补文件及其索引条目，而使用 --cached 时，它只会修改索引条目。

有关更多信息，请参阅 https://lore.kernel.org/git/[email protected]/ 和 https://lore.kernel.org/git/[email protected]/。

其他一些也作用于工作树和/或索引中文件的命令可以接受 --staged 和/或 --worktree 选项。

  • --staged 与 --cached 完全相同，用于指示命令仅作用于索引，而不是工作树。

  • --worktree 则相反，用于指示命令仅作用于工作树，而不是索引。

  • 这两个选项可以一起指定，指示命令同时作用于索引和工作树。

GIT

git[1] 套件的一部分

scroll-to-top