@matheusbsbs / matheus-bagliano / commits / c11f95010c

git-cli.txt: clarify "options first and then args"

There are some commands permit the user whether to provide options first before args, or the reverse order. For example: git push --dry-run <remote> <ref> And: git push <remote> <ref> --dry-run Both of them is supported, but some commands do not, for instance: git ls-remote --heads <remote> And: git ls-remote <remote> --heads If <remote> only has one ref and it's name is "refs/heads/--heads", you will get the same result, otherwise will not.This is because the former in the second example will parse "--heads" as an "option" which means to limit to only "refs/heads" when listing the remote references, the latter treat "--heads" as an argument which means to filter the result list with the given pattern. Therefore, we want to specify a bit more in "gitcli.txt" about the way we recommend and help to resolve the ambiguity around some git command usage. The related disscussions locate at [1]. By the way, there are some issues with lowercase letters in the document, which have been modified together. [1] https://public-inbox.org/git/cover.1642129840.git.dyroneteng@gmail.com/ Signed-off-by: Teng Long <dyroneteng@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Teng Long committed Jan 17, 2022 at 16:21 UTC c11f95010cc9f09ea3e5d401bc14c9b6663d2893
1 file changed +14 -5
Documentation/gitcli.txt
+14 -5
@@ -19,6 +19,15 @@ Many commands take revisions (most often "commits", but sometimes
19 "tree-ish", depending on the context and command) and paths as their
20 arguments. Here are the rules:
21
22 + * Options come first and then args.
23 + A subcommand may take dashed options (which may take their own
24 + arguments, e.g. "--max-parents 2") and arguments. You SHOULD
25 + give dashed options first and then arguments. Some commands may
26 + accept dashed options after you have already gave non-option
27 + arguments (which may make the command ambiguous), but you should
28 + not rely on it (because eventually we may find a way to fix
29 + these ambiguity by enforcing the "options then args" rule).
30 +
31 * Revisions come first and then paths.
32 E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
33 `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`
@@ -72,24 +81,24 @@ you will.
81 Here are the rules regarding the "flags" that you should follow when you are
82 scripting Git:
83
75 - * it's preferred to use the non-dashed form of Git commands, which means that
84 + * It's preferred to use the non-dashed form of Git commands, which means that
85 you should prefer `git foo` to `git-foo`.
86
78 - * splitting short options to separate words (prefer `git foo -a -b`
87 + * Splitting short options to separate words (prefer `git foo -a -b`
88 to `git foo -ab`, the latter may not even work).
89
81 - * when a command-line option takes an argument, use the 'stuck' form. In
90 + * When a command-line option takes an argument, use the 'stuck' form. In
91 other words, write `git foo -oArg` instead of `git foo -o Arg` for short
92 options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg`
93 for long options. An option that takes optional option-argument must be
94 written in the 'stuck' form.
95
87 - * when you give a revision parameter to a command, make sure the parameter is
96 + * When you give a revision parameter to a command, make sure the parameter is
97 not ambiguous with a name of a file in the work tree. E.g. do not write
98 `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work
99 if you happen to have a file called `HEAD` in the work tree.
100
92 - * many commands allow a long option `--option` to be abbreviated
101 + * Many commands allow a long option `--option` to be abbreviated
102 only to their unique prefix (e.g. if there is no other option
103 whose name begins with `opt`, you may be able to spell `--opt` to
104 invoke the `--option` flag), but you should fully spell them out