如何阅读 git 概要文档？
How do I read git synopsis documentation?
作为一名 iOS 工程师，我很难理解 git 文档。我查看了 glossary 并进行了在线搜索，但找不到我的问题的答案。
git checkout的例子：它的文档是这样的：
1 git checkout [-q] [-f] [-m] [<branch>]
2 git checkout [-q] [-f] [-m] --detach [<branch>]
3 git checkout [-q] [-f] [-m] [--detach] <commit>
4 git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
5 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>…
6 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
7 git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…]
☝️我自己加了行号
- 我数了7行。每行都是 options 的组合，可以与该行中的任意数量的选项一起使用吗？即 第一行：
git checkout [-q] [-f] [-m] [<branch>] 可以与 -q、-f、-m 单独或 -q -f 结合使用？但是 git checkout -q -b 分支不起作用，因为 -b 不在该行中？我的意思是前三行看起来非常相似。
- 第一行和第二行：为什么不能用这一行替换前两行：
git checkout [-q] [-f] [-m] [--detach] <branch>
- 此外，我认为顺序并不重要，第一行的顺序并不重要，
git checkout -q -f 与 git checkout -f -q 没有什么不同。我试过了，结果是一样的，但我还是不确定
- 第二行：为什么有些选项在
[]中，而--detach中没有？它与 --detach 在 [] 内的第 3 行有何不同
- 第 4 行：
[[-b|-B|--orphan] <new_branch>] 我该如何阅读？我不知道
- 第 5 行：
| 是什么意思？
- 第7行：
()用的是什么？
- 第 7 行：
[--] 是什么？
我明白这个问题可能看起来很宽泛，但是不同的语法命令需要一起看。
特别感谢 Charles Duffy 处理了我的评论并帮助我整理了这些内容。
I counted 7 lines. Is every line a combination of options that can
work with any number of the options in that line?
没错。然而 git checkout -q -b new_branch_name 有效。它仅适用于#4 定义，而不适用于#1 定义
1st and 2nd lines: Why couldn't the first 2 lines be replaced with
this one line: git checkout [-q] [-f] [-m] [--detach]
你是对的，它们可以被替换并且仍然具有相同的摘要含义。行的分隔是因为行为差异足以在以后有单独的长格式解释。
Also I suppose order isn't important that is for the first line, git
checkout -q -f is not different than git checkout -f -q. I tried and
the results were the same, but I'm just still not sure
除非在“选项”部分中另有说明，否则基于选项出现顺序的选项之间没有隐含关系。
☝️ 来自POSIX Conventions:
其余问题的答案可以在Git CodingGuidlines
中找到
占位符以小写形式拼写并括在尖括号中：
<file>
--sort=<key>
--abbrev[=<n>]
如果一个占位符有多个单词，它们之间用破折号分隔：
<new-branch-name>
--template=<template-directory>
多次出现的可能性由三个点表示：
<file>...
(One or more of <file>.)
可选部分用方括号括起来：
[<extra>]
(Zero or one <extra>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
brackets.)
[<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
多个选项用竖线表示：
[-q | --quiet]
[--utf8 | --no-utf8]
需要说明的是，备选方案不能组合，您可以通过 -q 或 --quiet
括号用于分组：
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
[(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.)
git remote set-head <name> (-a | -d | <branch>)
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.)
[(<rev> | <range>)...] 的含义 ... 应用于 | 的两个参数，想像一下 5 如何应用于 3 2 来自 (3 + 2) * 5。结果：
rev1 rev2 rev9可以接受range1 range3 range4可以接受rev1 range1 不 可以接受！
还有一个更人为的例子：
--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is
also provided.
另请注意，如果您向下滚动 git checkout page 本身（其他页面在“选项”部分末尾有类似的词汇表），您会看到一些有助于您更好地理解的元数据：
<branch>
Branch to checkout; if it refers to a branch (i.e., a name that, when
prepended with "refs/heads/", is a valid ref), then that branch is
checked out. Otherwise, if it refers to a valid commit, your HEAD
becomes "detached" and you are no longer on any branch (see below for
details).
You can use the @{-N} syntax to refer to the N-th last branch/commit
checked out using "git checkout" operation. You may also specify -
which is synonymous to @{-1}.
As a special case, you may use A...B as a shortcut for the merge base
of A and B if there is exactly one merge base. You can leave out at
most one of A and B, in which case it defaults to HEAD.
<new_branch>
Name for the new branch.
<start_point>
The name of a commit at which to start the new branch; see
git-branch[1] for details. Defaults to HEAD.
As a special case, you may use "A...B" as a shortcut for the merge
base of A and B if there is exactly one merge base. You can leave out
at most one of A and B, in which case it defaults to HEAD.
<tree-ish>
Tree to checkout from (when paths are given). If not specified, the
index will be used.
--
Do not interpret any more arguments as options.
<pathspec>…
Limits the paths affected by the operation.
For more details, see the pathspec entry in gitglossary[7].
另请参阅指定含义的标准文档，另请参阅 POSIX Utility Conventions
[1]: https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean
作为一名 iOS 工程师，我很难理解 git 文档。我查看了 glossary 并进行了在线搜索，但找不到我的问题的答案。
git checkout的例子：它的文档是这样的：
1 git checkout [-q] [-f] [-m] [<branch>]
2 git checkout [-q] [-f] [-m] --detach [<branch>]
3 git checkout [-q] [-f] [-m] [--detach] <commit>
4 git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
5 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>…
6 git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]
7 git checkout (-p|--patch) [<tree-ish>] [--] [<pathspec>…]
☝️我自己加了行号
- 我数了7行。每行都是 options 的组合，可以与该行中的任意数量的选项一起使用吗？即 第一行：
git checkout [-q] [-f] [-m] [<branch>]可以与-q、-f、-m单独或-q -f结合使用？但是git checkout -q -b分支不起作用，因为-b不在该行中？我的意思是前三行看起来非常相似。 - 第一行和第二行：为什么不能用这一行替换前两行：
git checkout [-q] [-f] [-m] [--detach] <branch> - 此外，我认为顺序并不重要，第一行的顺序并不重要，
git checkout -q -f与git checkout -f -q没有什么不同。我试过了，结果是一样的，但我还是不确定 - 第二行：为什么有些选项在
[]中，而--detach中没有？它与--detach在[] 内的第 3 行有何不同
- 第 4 行：
[[-b|-B|--orphan] <new_branch>]我该如何阅读？我不知道 - 第 5 行：
|是什么意思？ - 第7行：
()用的是什么？ - 第 7 行：
[--]是什么？
我明白这个问题可能看起来很宽泛，但是不同的语法命令需要一起看。
特别感谢 Charles Duffy 处理了我的评论并帮助我整理了这些内容。
I counted 7 lines. Is every line a combination of options that can work with any number of the options in that line?
没错。然而 git checkout -q -b new_branch_name 有效。它仅适用于#4 定义，而不适用于#1 定义
1st and 2nd lines: Why couldn't the first 2 lines be replaced with this one line:
git checkout [-q] [-f] [-m] [--detach]
你是对的，它们可以被替换并且仍然具有相同的摘要含义。行的分隔是因为行为差异足以在以后有单独的长格式解释。
Also I suppose order isn't important that is for the first line, git checkout -q -f is not different than git checkout -f -q. I tried and the results were the same, but I'm just still not sure
除非在“选项”部分中另有说明，否则基于选项出现顺序的选项之间没有隐含关系。
☝️ 来自POSIX Conventions:
其余问题的答案可以在Git CodingGuidlines
中找到占位符以小写形式拼写并括在尖括号中：
<file>
--sort=<key>
--abbrev[=<n>]
如果一个占位符有多个单词，它们之间用破折号分隔：
<new-branch-name>
--template=<template-directory>
多次出现的可能性由三个点表示：
<file>...
(One or more of <file>.)
可选部分用方括号括起来：
[<extra>]
(Zero or one <extra>.)
--exec-path[=<path>]
(Option with an optional argument. Note that the "=" is inside the
brackets.)
[<patch>...]
(Zero or more of <patch>. Note that the dots are inside, not
outside the brackets.)
多个选项用竖线表示：
[-q | --quiet]
[--utf8 | --no-utf8]
需要说明的是，备选方案不能组合，您可以通过 -q 或 --quiet
括号用于分组：
[(<rev> | <range>)...]
(Any number of either <rev> or <range>. Parens are needed to make
it clear that "..." pertains to both <rev> and <range>.)
[(-p <parent>)...]
(Any number of option -p, each with one <parent> argument.)
git remote set-head <name> (-a | -d | <branch>)
(One and only one of "-a", "-d" or "<branch>" _must_ (no square
brackets) be provided.)
[(<rev> | <range>)...] 的含义 ... 应用于 | 的两个参数，想像一下 5 如何应用于 3 2 来自 (3 + 2) * 5。结果：
rev1 rev2 rev9可以接受range1 range3 range4可以接受rev1 range1不 可以接受！
还有一个更人为的例子：
--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
Here "=" is outside the brackets, because "--diff-filter=" is a
valid usage. "*" has its own pair of brackets, because it can
(optionally) be specified only when one or more of the letters is
also provided.
另请注意，如果您向下滚动 git checkout page 本身（其他页面在“选项”部分末尾有类似的词汇表），您会看到一些有助于您更好地理解的元数据：
<branch>
Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that branch is checked out. Otherwise, if it refers to a valid commit, your HEAD becomes "detached" and you are no longer on any branch (see below for details).
You can use the @{-N} syntax to refer to the N-th last branch/commit checked out using "git checkout" operation. You may also specify - which is synonymous to @{-1}.
As a special case, you may use A...B as a shortcut for the merge base of A and B if there is exactly one merge base. You can leave out at most one of A and B, in which case it defaults to HEAD.
<new_branch>
Name for the new branch.
<start_point>
The name of a commit at which to start the new branch; see git-branch[1] for details. Defaults to HEAD.
As a special case, you may use "A...B" as a shortcut for the merge base of A and B if there is exactly one merge base. You can leave out at most one of A and B, in which case it defaults to HEAD.
<tree-ish>
Tree to checkout from (when paths are given). If not specified, the index will be used.
--
Do not interpret any more arguments as options.
<pathspec>…
Limits the paths affected by the operation.
For more details, see the pathspec entry in gitglossary[7].
另请参阅指定含义的标准文档，另请参阅 POSIX Utility Conventions [1]: https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean