8

As an iOS engineer I struggle to understand the git documentation. I looked into the glossary and searched online but couldn’t find an answer to my question.

Example for git checkout: The documentation on it are as such:

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>…​]

☝️ I added line number myself

  • I counted 7 lines. Is every line a combination of options that can work with any number of the options in that line? ie First line: the git checkout [-q] [-f] [-m] [<branch>] can work with either -q, -f, -m individually or -q -f combined? yet git checkout -q -b branch won’t work because -b isn’t in that line? I mean The first three lines look very similar.
  • 1st and 2nd lines: Why couldn't the first 2 lines be replaced with this one line: git checkout [-q] [-f] [-m] [--detach] <branch>
  • 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
  • 2nd line: why are some options in [] but the --detach isn’t in a bracket? How is it different from 3rd line where --detach is inside []
  • 4th line: [[-b|-B|--orphan] <new_branch>] how should I read that? I have no clue
  • 5th line: what does | mean?
  • 7th line: what is () used?
  • 7th line: what’s with [--]?

I understand the question may seem broad, but the different syntax commands need to be seen together.

14
  • 2
    -- has a standard meaning (as "end-of-options"); it's not git-specific at all. ("Anything after this will not be parsed as an option, but as a positional argument"). In this case, everything after -- is guaranteed to be parsed as a pathspec, even if it might otherwise be ambiguous. Mar 28, 2020 at 20:48
  • 2
    ...for the standards document specifying that meaning, see pubs.opengroup.org/onlinepubs/9699919799/basedefs/… Mar 28, 2020 at 20:50
  • 1
    BTW, git checkout -q -b new_branch_name works -- it just works under the #4 definition, not under the #1 definition. Mar 28, 2020 at 20:52
  • 2
    Correct; at least, those usages would not be documented to work; their behavior would be implementation-defined and subject-to-change, as opposed to documentation-defined and guaranteed to be stable. Mar 28, 2020 at 22:02
  • 2
    Which is to say, it's not guaranteed that undocumented things won't work, but is (only) guaranteed that documented things will work. Mar 28, 2020 at 22:04

1 Answer 1

7

Special thanks Charles Duffy who addressed my comments and helped me put this together.

I counted 7 lines. Is every line a combination of options that can work with any number of the options in that line?

That's correct. Yet git checkout -q -b new_branch_name works. It just works under the #4 definition, not under the #1 definition

1st and 2nd lines: Why couldn't the first 2 lines be replaced with this one line: git checkout [-q] [-f] [-m] [--detach]

You're right that they could be replaced and still have the same summary meaning. The separation of lines is because the behaviors differ enough to have separate long-form explanations later.

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

There are no implied relationships between the options based upon the order in which they appear, unless otherwise stated in the OPTIONS section.

☝️ From POSIX Conventions:


The answer to the remainder of the questions can be found from Git CodingGuidlines

Placeholders are spelled in lowercase and enclosed in angle brackets:

<file>
--sort=<key>
--abbrev[=<n>]

If a placeholder has multiple words, they are separated by dashes:

<new-branch-name>
--template=<template-directory>

Possibility of multiple occurrences is indicated by three dots:

<file>...
(One or more of <file>.)

Optional parts are enclosed in square brackets:

[<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.)

Multiple alternatives are indicated with vertical bars:

[-q | --quiet]
[--utf8 | --no-utf8]

To be clear, alternatives can't be combined you can either pass -q or --quiet

Parentheses are used for grouping:

[(<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.)

Meaning for [(<rev> | <range>)...] the ... is applied to both arguments of |, think of just as if how 5 is applied to both 3 and 2 from (3 + 2) * 5. As a result:

  • rev1 rev2 rev9 is acceptable
  • range1 range3 range4 is acceptable
  • rev1 range1 isn not acceptable!

And a somewhat more contrived example:

--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.

Also note that from the git checkout page itself, if you scroll down (other pages had similar glossary put towards the end of the OPTIONS section), you'll see some meta data that helps you better understand:

<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].


Also for the standards document specifying meaning, also see POSIX Utility Conventions [1]: https://unix.stackexchange.com/questions/11376/what-does-double-dash-mean

3
  • 3
    👏 This 👏 is 👏 so 👏 useful 👏 Dec 7, 2020 at 20:47
  • @mfaani please enlighten me why it's always a problem with open source documentation, this so useful what you provide us with, Always asking myself why we cannot find this in git documentation, unless I really missed a page . :/ Feb 2, 2022 at 16:25
  • I also wrote a more structured blog post: mfaani.com/posts/how-to-read-git-documentation
    – mfaani
    Apr 18, 2022 at 14:35

Not the answer you're looking for? Browse other questions tagged or ask your own question.