## 命名

gitcli - Git 命令行界面和约定

## 概要

gitcli

## 描述

本手册介绍了在整个 Git CLI 中使用的约定。

许多命令都采用修订（通常是 “commits” ，但有时是 “ tree-ish ” ，取决于上下文和命令）和路径作为它们的参数。这是规则：

- 修订首先是路径。例如在`git diff v1.0 v2.0 arch/x86 include/asm-x86`，`v1.0`并且`v2.0`是修改，`arch/x86`并且`include/asm-x86`是路径。

- 当一个论证可能会被误解为一个修订或一条路径时，他们可以通过放在`--`它们之间来消除歧义。例如`git diff -- HEAD`，“我的工作树中有一个名为 HEAD 的文件，请在索引中的版本I和我在该文件的工作树中显示的内容之间显示更改”，而不是“显示 HEAD 提交与工作之间的差异树整体“。你可以说`git diff HEAD --`要问后者。

- 在没有歧义的情况下`--`，Git 会做出合理的猜测，但会出错并要求您在模棱两可时消除歧义。例如，如果你有一个在你的工作树叫 HEAD 的文件，`git diff HEAD`是模糊的，而你不得不说要么`git diff HEAD --`或`git diff -- HEAD`消除歧义。在编写预期处理随机用户输入的脚本时，最好明确哪些参数是通过`--`在适当的位置进行消除歧义来明确的。

- 许多命令允许在路径中使用通配符，但是您需要保护它们免受 shell 的影响。这两个意思是不同的东西：

$ git checkout -- *.c $ git checkout -- \*.c

前者允许 shell 扩展 fileglob ，并且要求工作树中的 dot-C 文件被索引中的版本覆盖。后者传递`*.c`给 Git，并且您要求索引中匹配模式的路径被检出到您的工作树上。跑步后`git add hello.c; rm hello.c`，你会`not`看到`hello.c`你的工作树与前者，但后者，你会。

- 就像文件系统`.`（句点）引用当前目录一样，在Git 中使用`.`作为存储库名称（一个点存储库）是一个相对路径，并且表示您当前的存储库。这里是关于您应该遵循的“标志”的规则当你在编写 Git 时：

- 它的最好使用的 Git 的非虚线形式的命令，这意味着你应该更喜欢`git foo`到`git-foo`。

- 拆分短选项分隔单词（喜欢`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`长期期权。采用可选选项参数的选项必须写入`stuck`表单中。

- 当您为某个命令提供修订参数时，请确保该参数与工作树中文件的名称不混淆。例如，不要写，`git log -1 HEAD`而要写`git log -1 HEAD --`; 如果您碰巧`HEAD`在工作树中调用了一个文件，则前者不起作用。

- 许多命令允许将一个长选项`--option`仅缩写为其唯一的前缀（例如，如果没有其他选项的名称以该名称开头`opt`，则可以拼写`--opt`来调用该`--option`标志），但是在编写脚本时应该将其完全拼出; 后来的 Git 版本可能会引入一个新的选项，其名称共享相同的前缀，例如`--optimize`，用于创建一个过去不再唯一的简短前缀。

## 增强的选项解析器

从 Git 1.5.4 系列和更进一步，许多 Git 命令（不是所有的这些在编写时）都带有一个增强的选项解析器。

这里是这个选项解析器提供的工具列表。

### Magic 选项

具有增强的选项分析器的命令都可以理解一些神奇的命令行选项：

-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

--help-all

有些 Git 命令会使用仅用于管道的选项或已弃用的选项，并且这些选项对于默认用法是隐藏的。该选项提供了完整的选项列表。

### 否定选项

具有较长选项名称的选项可以通过前缀来取消`--no-`。例如，`git branch`有选项`--track`是`on`默认。您可以使用`--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

然而，这是不允许与可选的值，其中，所述开关`stuck`，必须使用形式：

    $ 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`，它仅修改索引条目。