undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Teng Long 2022-01-17 16:21:01 +08:00 committed by Junio C Hamano
parent e9d7761bb9
commit c11f95010c
1 changed files with 14 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
Documentation/gitcli.txt
View File

@ -19,6 +19,15 @@ Many commands take revisions (most often "commits", but sometimes
"tree-ish", depending on the context and command) and paths as their "tree-ish", depending on the context and command) and paths as their
arguments. Here are the rules: arguments. Here are the rules:
* Options come first and then args.
A subcommand may take dashed options (which may take their own
arguments, e.g. "--max-parents 2") and arguments. You SHOULD
give dashed options first and then arguments. Some commands may
accept dashed options after you have already gave non-option
arguments (which may make the command ambiguous), but you should
not rely on it (because eventually we may find a way to fix
these ambiguity by enforcing the "options then args" rule).
* Revisions come first and then paths. * Revisions come first and then paths.
E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`, E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,
`v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86` `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`
@ -72,24 +81,24 @@ you will.
Here are the rules regarding the "flags" that you should follow when you are Here are the rules regarding the "flags" that you should follow when you are
scripting Git: scripting Git:
* it's preferred to use the non-dashed form of Git commands, which means that * It's preferred to use the non-dashed form of Git commands, which means that
you should prefer `git foo` to `git-foo`. you should prefer `git foo` to `git-foo`.
* splitting short options to separate words (prefer `git foo -a -b` * Splitting short options to separate words (prefer `git foo -a -b`
to `git foo -ab`, the latter may not even work). to `git foo -ab`, the latter may not even work).
* when a command-line option takes an argument, use the 'stuck' form. In * When a command-line option takes an argument, use the 'stuck' form. In
other words, write `git foo -oArg` instead of `git foo -o Arg` for short other words, write `git foo -oArg` instead of `git foo -o Arg` for short
options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg`
for long options. An option that takes optional option-argument must be for long options. An option that takes optional option-argument must be
written in the 'stuck' form. written in the 'stuck' form.
* when you give a revision parameter to a command, make sure the parameter is * When you give a revision parameter to a command, make sure the parameter is
not ambiguous with a name of a file in the work tree. E.g. do not write not ambiguous with a name of a file in the work tree. E.g. do not write
`git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work
if you happen to have a file called `HEAD` in the work tree. if you happen to have a file called `HEAD` in the work tree.
* many commands allow a long option `--option` to be abbreviated * Many commands allow a long option `--option` to be abbreviated
only to their unique prefix (e.g. if there is no other option only to their unique prefix (e.g. if there is no other option
whose name begins with `opt`, you may be able to spell `--opt` to whose name begins with `opt`, you may be able to spell `--opt` to
invoke the `--option` flag), but you should fully spell them out invoke the `--option` flag), but you should fully spell them out