英语 ▾ 主题 ▾ 最新版本 ▾ gitcli 上次更新于 2.49.0

名称

gitcli - Git 命令行界面和约定

概要

gitcli

描述

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

许多命令接受修订（通常是 "commits"，但有时是 "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 commit 和整个工作树之间的差异"。你可以说 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 展开 fileglob，你要求工作树中的 dot-C 文件被索引中的版本覆盖。后者将 *.c 传递给 Git，你要求索引中与模式匹配的路径被检出到你的工作树中。在运行 git add hello.c; rm hello.c 之后，你将不会在前者的工作树中看到 hello.c，但在后者中你会看到。

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

以下是你在编写 Git 脚本时应该遵循的关于 "flags" 的规则

  • 将短选项拆分成单独的单词（首选 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

请注意，当命令行上除了 -h 之外还有其他内容时，一些子命令（例如 git grep）的行为可能不同，但是没有任何其他内容的 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

关于容易混淆的选项的说明

许多可以处理工作区和/或索引中的文件的命令可以使用 --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