简体中文 ▾ 主题 ▾ 最新版本 ▾ 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 进行文件名扩展（globbing）。以下两种用法含义不同：

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

    前者让 shell 展开文件通配符，你是在要求将工作区中所有的 .c 文件用暂存区中的版本覆盖。后者将 *.c 传给 Git，你是在要求将暂存区中匹配该模式的路径检出到工作区。运行 git add hello.c; rm hello.c 后，对于前者，你将不会在工作区中看到 hello.c，但对于后者，你会看到。

  • 就像文件系统中的 . (点) 指代当前目录一样，在 Git 中使用 . 作为仓库名（点仓库）是一个相对路径，指代当前的仓库。

以下是你编写 Git 脚本时应遵循的有关“标志（flags）”的规则：

  • 拆分短选项为单独的词（建议使用 git foo -a -b 而非 git foo -ab，后者甚至可能无法工作）。

  • 当命令行选项带有参数时，请使用粘连（stuck）形式。换句话说，对于短选项，写成 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

但是，对于带有可选值的开关，这是不允许的，必须使用粘连（stuck）形式。

$ 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] 中的“值（Values）”。

关于易混淆选项的说明

许多既可以操作工作区文件也可以操作暂存区文件的命令，可以接受 --cached 和/或 --index 选项。有时人们错误地认为，由于暂存区最初被称为“缓存（cache）”，这两个是同义词。它们不是 —— 这两个选项含义截然不同。

  • --cached 选项用于要求一个通常操作工作区文件的命令仅对暂存区进行操作。例如，git grep 在没有使用提交指定搜索范围时，通常在工作区文件中操作；但配合 --cached 选项，它将在暂存区中查找字符串。

  • --index 选项用于要求一个通常操作工作区文件的命令同时影响暂存区。例如，git stash apply 通常将存储条目（stash entry）中记录的更改合并到工作区，但使用 --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] 套件的一部分