简体中文 ▾ 主题 ▾ 最新版本 ▾ gitcli 最后更新于 2.50.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 命令接受仅用于底层（plumbing）或已弃用的选项，这些选项在默认用法中是隐藏的。此选项提供完整的选项列表。

否定选项

带有长选项名的选项可以通过添加前缀 --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

关于常见混淆选项的注意事项

许多可以在工作区和/或索引中对文件进行操作的命令可以接受 --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] 套件的一部分

scroll-to-top