Here is the description of one of the Git commands taken from here: https://git-scm.com/docs/git-branch. To my understanding this site can be treated as official documentation. It that right?

I took git branch command as a sample. I hope all other commands follow the same rules. So, here is the sample:

(1) git branch
           [--color[=<when>] | --no-color] [--show-current]
           [-v [--abbrev=<n> | --no-abbrev]]
           [--column[=<options>] | --no-column] [--sort=<key>]
           [--merged [<commit>]] [--no-merged [<commit>]]
           [--contains [<commit>]] [--no-contains [<commit>]]
           [--points-at <object>] [--format=<format>]
           [(-r | --remotes) | (-a | --all)]
           [--list] [<pattern>…​]
(2) git branch
           [--track[=(direct|inherit)] | --no-track] [-f]
           [--recurse-submodules] <branchname> [<start-point>]
(3) git branch
           (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
(4) git branch
           --unset-upstream [<branchname>]
(5) git branch
           (-m | -M) [<oldbranch>] <newbranch>
(6) git branch
           (-c | -C) [<oldbranch>] <newbranch>
(7) git branch
           (-d | -D) [-r] <branchname>…​
(8) git branch
           --edit-description [<branchname>]

So, I understand this description that:

1. The git branch command has 8 non-intersecting patterns. Exactly 8 patterns. Not 6 or 7.
2. Each pattern explicitly lists all keys and parameters that are applicable to this pattern.
3. Git makes decision on what pattern to apply based on the key(s) in the command line. I see that in the sample above all keys are present only in one pattern. There is no intersections.

Everything would be great, but all keys in the pattern 1 and pattern 2 are optional. This means that they can be all missing. How will Git make its decision in this case?

The command git branch abcd1234-whatever, is ambiguous between pattern 1 and pattern 2.

Am I missing something else here?

CodePudding user response：

Not all keys are optional for the second pattern. Notice that <branchname> is in angle brackets, not square brackets.

As a rule of thumb, the following lists branches:

git branch

The following creates a new branch:

git branch some_new_branch

The manual explicitly addresses the possible misinterpretation of some_new_branch as a search pattern for existing branches:

Note that when providing a <pattern>, you must use --list; otherwise the command may be interpreted as branch creation.

So yes, there is an ambiguity to the general rule, but the authors chose to embrace it and provide an unambiguous workaround. Specifically, you have to explicitly use --list to indicate the optional positional argument to pattern 1 versus the mandatory unmarked one for pattern 2.

That being said, I wouldn't start with that part of the manual. While it's complete and accurate, it does not attempt to show you actual usage. The same official docs have an excellent tutorial section that will show you how to use git as a tool. The command manual is a great place to search for extended capabilities once you've learned the basics.

Check out the Guides section on https://git-scm.com/docs, e.g. https://git-scm.com/docs/gittutorial. As with many introductory materials written by the authors and maintainers of a project, these are excellent.