{"thread":{"id":"57260","subject":"[PATCH v1 0/1] gitcli: clarify \"options first and then args\"","startedAt":"2022-01-17T07:56:31Z","lastAt":"2022-01-17T08:21:10Z","messageCount":2,"participants":["Teng Long"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"446343","messageId":"cover.1642405806.git.dyroneteng@gmail.com","threadId":"57260","inReplyTo":null,"subject":"[PATCH v1 0/1] gitcli: clarify \"options first and then args\"","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2022-01-17T07:56:22Z","receivedAt":"2022-01-17T07:56:31Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"The patch adds some clarification about \"options first and then args\"\nin \"gitcli.txt\" which was discussed in :\n\n https://public-inbox.org/git/cover.1642129840.git.dyroneteng@gmail.com/ \n\nThanks.\n\nTeng Long (1):\n git-cli.txt: clarify \"options first and then args\"\n\n Documentation/gitcli.txt | 19 ++++++++++++++-----\n 1 file changed, 14 insertions(+), 5 deletions(-)\n\nRange-diff against v0:\n-: ---------- > 1: fe748304d9 git-cli.txt: clarify \"options first and then args\"\n-- \n2.34.1.391.g9ef3d6f133\n\n"},{"id":"446353","messageId":"fe748304d94e0ae25fd3549aadc49cf951ff2d64.1642405806.git.dyroneteng@gmail.com","threadId":"57260","inReplyTo":"cover.1642405806.git.dyroneteng@gmail.com","subject":"[PATCH v1 1/1] git-cli.txt: clarify \"options first and then args\"","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2022-01-17T08:21:01Z","receivedAt":"2022-01-17T08:21:10Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"There are some commands permit the user whether to provide options\nfirst before args, or the reverse order. For example:\n\n git push --dry-run \n\nAnd:\n\n git push --dry-run\n\nBoth of them is supported, but some commands do not, for instance:\n\n git ls-remote --heads \n\nAnd:\n\n git ls-remote --heads\n\nIf only has one ref and it's name is \"refs/heads/--heads\", you\nwill get the same result, otherwise will not.This is because the former\nin the second example will parse \"--heads\" as an \"option\" which means\nto limit to only \"refs/heads\" when listing the remote references, the\nlatter treat \"--heads\" as an argument which means to filter the result\nlist with the given pattern.\n\nTherefore, we want to specify a bit more in \"gitcli.txt\" about the way\nwe recommend and help to resolve the ambiguity around some git command\nusage. The related disscussions locate at [1].\n\nBy the way, there are some issues with lowercase letters in the document,\nwhich have been modified together.\n\n[1] https://public-inbox.org/git/cover.1642129840.git.dyroneteng@gmail.com/\n\nSigned-off-by: Teng Long \n---\n Documentation/gitcli.txt | 19 ++++++++++++++-----\n 1 file changed, 14 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 92e4ba6a2f..1819a5a185 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -19,6 +19,15 @@ Many commands take revisions (most often \"commits\", but sometimes\n \"tree-ish\", depending on the context and command) and paths as their\n arguments. Here are the rules:\n \n+ * Options come first and then args.\n+ A subcommand may take dashed options (which may take their own\n+ arguments, e.g. \"--max-parents 2\") and arguments. You SHOULD\n+ give dashed options first and then arguments. Some commands may\n+ accept dashed options after you have already gave non-option\n+ arguments (which may make the command ambiguous), but you should\n+ not rely on it (because eventually we may find a way to fix\n+ these ambiguity by enforcing the \"options then args\" rule).\n+\n * Revisions come first and then paths.\n E.g. in `git diff v1.0 v2.0 arch/x86 include/asm-x86`,\n `v1.0` and `v2.0` are revisions and `arch/x86` and `include/asm-x86`\n@@ -72,24 +81,24 @@ you will.\n Here are the rules regarding the \"flags\" that you should follow when you are\n scripting Git:\n \n- * it's preferred to use the non-dashed form of Git commands, which means that\n+ * It's preferred to use the non-dashed form of Git commands, which means that\n you should prefer `git foo` to `git-foo`.\n \n- * splitting short options to separate words (prefer `git foo -a -b`\n+ * Splitting short options to separate words (prefer `git foo -a -b`\n to `git foo -ab`, the latter may not even work).\n \n- * when a command-line option takes an argument, use the 'stuck' form. In\n+ * When a command-line option takes an argument, use the 'stuck' form. In\n other words, write `git foo -oArg` instead of `git foo -o Arg` for short\n options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg`\n for long options. An option that takes optional option-argument must be\n written in the 'stuck' form.\n \n- * when you give a revision parameter to a command, make sure the parameter is\n+ * When you give a revision parameter to a command, make sure the parameter is\n not ambiguous with a name of a file in the work tree. E.g. do not write\n `git log -1 HEAD` but write `git log -1 HEAD --`; the former will not work\n if you happen to have a file called `HEAD` in the work tree.\n \n- * many commands allow a long option `--option` to be abbreviated\n+ * Many commands allow a long option `--option` to be abbreviated\n only to their unique prefix (e.g. if there is no other option\n whose name begins with `opt`, you may be able to spell `--opt` to\n invoke the `--option` flag), but you should fully spell them out\n-- \n2.34.1.391.g9ef3d6f133\n\n"}]}