如何阅读Git概要文档?

8
作为一名iOS工程师,我很难理解git文档。我查阅了术语表并在网上搜索,但没有找到我的问题的答案。
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行,每一行都是由选项组成的组合吗?例如第一行:使用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 -fgit checkout -f -q没有区别。我尝试过,结果是一样的,但我还是不确定
  • 第二行:为什么有些选项用[]括起来,而--detach不在括号中?它与第三行的区别在哪里,因为--detach[]内部?
  • 第四行:[[-b|-B|--orphan] <new_branch>]我该如何理解它?我不知道
  • 第五行:什么意思是|
  • 第七行:()有什么用?
  • 第七行:[--]是什么意思?

我了解问题可能看起来很广泛,但需要查看不同语法命令之间的关系


2
"--" 有一个标准含义(作为“选项结束”);它与 Git 没有任何特定关系。(“此后的任何内容都不会被解析为选项,而是作为位置参数处理”)。在这种情况下,“--”之后的所有内容都将被保证解析为路径规范,即使它可能是模棱两可的。 - Charles Duffy
2
有关规定该含义的标准文档,请参阅https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html - Charles Duffy
1
顺便提一下,git checkout -q -b new_branch_name 是可行的——它只适用于第四个定义,而不是第一个定义。 - Charles Duffy
2
正确;至少,这些用法不会被记录为有效;它们的行为将是实现定义的,并且可能会发生变化,而不是文档定义的并保证稳定。 - Charles Duffy
2
也就是说,未记录的事情不能保证不起作用,但记录的事情可以保证起作用。 - Charles Duffy
显示剩余9条评论
1个回答

7

特别感谢Charles Duffy,他解决了我的问题并帮助我完成了这个项目。

我数了7行。每一行都是可以与该行中的任意选项组合使用的选项吗?

没错。但是git checkout -q -b 新分支名可以工作。它只适用于第4种定义,而不是第1种定义。

第1行和第2行:为什么不能用这一行代替前两行:git checkout [-q] [-f] [-m] [--detach]

你说得对,它们可以被替换并且仍然具有相同的概要含义。将它们分开是因为行为差异足以在后面有单独的长格式说明。

此外,我想第一行的顺序并不重要,即git checkout -q -f和git checkout -f -q没有区别。我尝试了一下,结果是一样的,但我还是不确定

除非在OPTIONS部分另有说明,否则选项之间的顺序没有暗示的关系。

☝️ 来自 POSIX 公约


答案可以从Git编码指南中找到。 占位符应该用小写字母拼写,并用尖括号括起来:
<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>)...]的含义是对|两侧的参数应用...,就像在(3 + 2) * 5中将5应用于32一样。因此:

  • 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页面本身开始,如果你向下滚动(其他页面在OPTIONS部分末尾也有类似的词汇表),你会看到一些元数据,这些元数据可以帮助你更好地理解:

要检出的分支;如果它是指一个分支(即,一个名称,当以“refs/heads/”为前缀时是有效的引用),则该分支被检出。否则,如果它是指一个有效的提交,则你的HEAD将变为“分离状态”,你将不再位于任何分支上(详情见下文)。

你可以使用@{-N}语法来引用使用“git checkout”操作检出的第N个最后一个分支/提交。你也可以指定-,它等同于@{-1}。

作为一个特殊情况,如果恰好有一个合并基础,你可以使用A...B作为A和B的快捷方式。你最多可以省略A和B中的一个,此时默认为HEAD。

新分支的名称。如果提供了此参数,则将创建一个新分支,并将其设置为当前分支。

新分支的名称。

<start_point>

开始新分支的提交名称;有关详细信息,请参见 git-branch[1]。默认为 HEAD。

作为特殊情况,如果 A 和 B 有一个并且仅有一个合并基,则可以使用 "A...B" 作为快捷方式。您最多可以省略 A 和 B 中的一个,默认为 HEAD。

<tree-ish>

要检出的树(当给出路径时)。如果未指定,则使用索引。

--

不要将任何其他参数解释为选项。

<pathspec>…

限制操作影响的路径。

有关更多详细信息,请参见gitglossary[7]中的pathspec条目。


此外,关于规范文件的含义,请参见POSIX实用程序约定。[1]: https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean

3
这非常有用。 - Martin Jaskulla
@mfaani,请给我解释一下为什么开源文档总是有问题,你提供的内容非常有用。我一直在想为什么我们在git文档中找不到这些内容,除非我真的错过了某一页。:/ - projektorius96
我还写了一篇更有结构的博客文章:https://mfaani.com/posts/how-to-read-git-documentation/ - mfaani

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接