{"thread":{"id":"62531","subject":"[PATCH] doc: option value may be separate for valid reasons","startedAt":"2024-11-24T09:43:58Z","lastAt":"2024-11-25T04:49:19Z","messageCount":6,"participants":["Junio C Hamano","Eric Sunshine"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"507977","messageId":"xmqqjzct9db8.fsf@gitster.g","threadId":"62531","inReplyTo":null,"subject":"[PATCH] doc: option value may be separate for valid reasons","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-24T09:43:55Z","receivedAt":"2024-11-24T09:43:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Even though `git help cli` recommends users to prefer using\n\"--option=value\" over \"--option value\", there can be reasons why\ngiving them separately is a good idea. One reason is that shells do\nnot perform tilde expansion for `--option=~/path/name` but they\nexpand `--options ~/path/name` just fine.\n\nThis is not a problem for many options whose option parsing is\nproperly written using OPT_FILENAME(), because the value given to\nOPT_FILENAME() is tilde-expanded internally by us, but some commands\ntake a pathname as a mere string, which needs this trick to have the\nshell help us.\n\nI think the reason we originally decided to recommend the stuck form\nwas because an option that takes an optional value requires you to\nuse it in the stuck form, and it is one less thing for users to\nworry about if they get into the habit to always use the stuck form.\nBut we should be discouraging ourselves from adding an option with\nan optional value in the first place, and we might want to weaken\nthe current recommendation.\n\nIn any case, let's describe this one case where it is necessary to\nuse the separate form, with an example.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 10 ++++++++++\n Documentation/gitcredentials.txt | 5 +++++\n 2 files changed, 15 insertions(+)\n\ndiff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\nindex 7c709324ba..e484be9a36 100644\n--- c/Documentation/gitcli.txt\n+++ w/Documentation/gitcli.txt\n@@ -88,10 +88,20 @@ scripting Git:\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+ * Despite the above suggestion, when Arg is a path relative to the\n+ home directory of a user, e.g. ~/directory/file or ~u/d/f, you\n+ may want to use the separate form, e.g. `git credential-store\n+ --file ~/sec/rit`, not `git credential-store --file=~/sec/rit`.\n+ The shell will expand `~/` in the former to your home directory,\n+ but most shells keep the tilde in the latter. Some of our\n+ commands know how to tilde-expand the option value internally,\n+ but not all. The `--file` option of `credential-store` is an\n+ example that it needs shell's help to tilde-expand its value.\n+\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 \ndiff --git c/Documentation/gitcredentials.txt w/Documentation/gitcredentials.txt\nindex 71dd19731a..f6ce923f25 100644\n--- c/Documentation/gitcredentials.txt\n+++ w/Documentation/gitcredentials.txt\n@@ -240,10 +240,15 @@ Here are some example specifications:\n # the arguments are parsed by the shell, so use shell\n # quoting if necessary\n [credential]\n \thelper = \"foo --bar='whitespace arg'\"\n \n+# store helper (discouraged) with custom location for the db file;\n+# tilde expansion often requires the filename as a separate argument.\n+[credential]\n+\thelper = \"store --file ~/.git-secret.txt\"\n+\n # you can also use an absolute path, which will not use the git wrapper\n [credential]\n \thelper = \"/path/to/my/helper --with-arguments\"\n \n # or you can specify your own shell snippet\n"},{"id":"507996","messageId":"CAPig+cT_uB-mBwRh_A-HvpO8QCjv_Rw3-6s4gV=BCwYmSGcctg@mail.gmail.com","threadId":"62531","inReplyTo":"xmqqjzct9db8.fsf@gitster.g","subject":"Re: [PATCH] doc: option value may be separate for valid reasons","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-11-24T23:54:34Z","receivedAt":"2024-11-24T23:54:46Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Nov 24, 2024 at 4:44 AM Junio C Hamano wrote:\n> Even though `git help cli` recommends users to prefer using\n> \"--option=value\" over \"--option value\", there can be reasons why\n> giving them separately is a good idea. One reason is that shells do\n> not perform tilde expansion for `--option=~/path/name` but they\n> expand `--options ~/path/name` just fine.\n>\n> This is not a problem for many options whose option parsing is\n> properly written using OPT_FILENAME(), because the value given to\n> OPT_FILENAME() is tilde-expanded internally by us, but some commands\n> take a pathname as a mere string, which needs this trick to have the\n> shell help us.\n>\n> I think the reason we originally decided to recommend the stuck form\n> was because an option that takes an optional value requires you to\n> use it in the stuck form, and it is one less thing for users to\n> worry about if they get into the habit to always use the stuck form.\n> But we should be discouraging ourselves from adding an option with\n> an optional value in the first place, and we might want to weaken\n> the current recommendation.\n>\n> In any case, let's describe this one case where it is necessary to\n> use the separate form, with an example.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> @@ -88,10 +88,20 @@ scripting Git:\n> + * Despite the above suggestion, when Arg is a path relative to the\n> + home directory of a user, e.g. ~/directory/file or ~u/d/f, you\n> + may want to use the separate form, e.g. `git credential-store\n> + --file ~/sec/rit`, not `git credential-store --file=~/sec/rit`.\n> + The shell will expand `~/` in the former to your home directory,\n> + but most shells keep the tilde in the latter. Some of our\n> + commands know how to tilde-expand the option value internally,\n> + but not all. The `--file` option of `credential-store` is an\n> + example that it needs shell's help to tilde-expand its value.\n\nI'm not sure the final sentence adds any value considering that\ncredential-store was already mentioned in the example earlier in the\nparagraph, though I suppose it doesn't hurt to keep the sentence.\n\n> diff --git c/Documentation/gitcredentials.txt w/Documentation/gitcredentials.txt\n> @@ -240,10 +240,15 @@ Here are some example specifications:\n> # the arguments are parsed by the shell, so use shell\n> # quoting if necessary\n> [credential]\n> helper = \"foo --bar='whitespace arg'\"\n>\n> +# store helper (discouraged) with custom location for the db file;\n> +# tilde expansion often requires the filename as a separate argument.\n> +[credential]\n> + helper = \"store --file ~/.git-secret.txt\"\n\nIn the context of the commit message, I understand why you added the\ncomment above this example, but as a mere user without having that\ncontext, I think the part starting \"tilde expansion...\" would confuse\nme more than help. Perhaps being a bit more explicit might help:\n\n # use `--file ~/path` rather than `--file=~/path` to allow the\n # shell to expand tilde to the home directory\n"},{"id":"508007","messageId":"xmqqo7246mjy.fsf@gitster.g","threadId":"62531","inReplyTo":"CAPig+cT_uB-mBwRh_A-HvpO8QCjv_Rw3-6s4gV=BCwYmSGcctg@mail.gmail.com","subject":"Re: [PATCH] doc: option value may be separate for valid reasons","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-25T03:04:49Z","receivedAt":"2024-11-25T03:04:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n>> + may want to use the separate form, e.g. `git credential-store\n>> + --file ~/sec/rit`, not `git credential-store --file=~/sec/rit`.\n>> + The shell will expand `~/` in the former to your home directory,\n>> + but most shells keep the tilde in the latter. Some of our\n>> + commands know how to tilde-expand the option value internally,\n>> + but not all. The `--file` option of `credential-store` is an\n>> + example that it needs shell's help to tilde-expand its value.\n>\n> I'm not sure the final sentence adds any value considering that\n> credential-store was already mentioned in the example earlier in the\n> paragraph, though I suppose it doesn't hurt to keep the sentence.\n\nProbably.\n\n>> diff --git c/Documentation/gitcredentials.txt w/Documentation/gitcredentials.txt\n>> @@ -240,10 +240,15 @@ Here are some example specifications:\n>> # the arguments are parsed by the shell, so use shell\n>> # quoting if necessary\n>> [credential]\n>> helper = \"foo --bar='whitespace arg'\"\n>>\n>> +# store helper (discouraged) with custom location for the db file;\n>> +# tilde expansion often requires the filename as a separate argument.\n>> +[credential]\n>> + helper = \"store --file ~/.git-secret.txt\"\n>\n> In the context of the commit message, I understand why you added the\n> comment above this example, but as a mere user without having that\n> context, I think the part starting \"tilde expansion...\" would confuse\n> me more than help. Perhaps being a bit more explicit might help:\n>\n> # use `--file ~/path` rather than `--file=~/path` to allow the\n> # shell to expand tilde to the home directory\n\nYou're right. That reads much better.\n\nThanks.\n"},{"id":"508008","messageId":"xmqqh67w6m4m.fsf@gitster.g","threadId":"62531","inReplyTo":"xmqqjzct9db8.fsf@gitster.g","subject":"[PATCH v2] doc: option value may be separate for valid reasons","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-25T03:14:01Z","receivedAt":"2024-11-25T03:14:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Even though `git help cli` recommends users to prefer using\n\"--option=value\" over \"--option value\", there can be reasons why\ngiving them separately is a good idea. One reason is that shells do\nnot perform tilde expansion for `--option=~/path/name` but they\nexpand `--options ~/path/name` just fine.\n\nThis is not a problem for many options whose option parsing is\nproperly written using OPT_FILENAME(), because the value given to\nOPT_FILENAME() is tilde-expanded internally by us, but some commands\ntake a pathname as a mere string, which needs this trick to have the\nshell help us.\n\nI think the reason we originally decided to recommend the stuck form\nwas because an option that takes an optional value requires you to\nuse it in the stuck form, and it is one less thing for users to\nworry about if they get into the habit to always use the stuck form.\nBut we should be discouraging ourselves from adding an option with\nan optional value in the first place, and we might want to weaken\nthe current recommendation.\n\nIn any case, let's describe this one case where it is necessary to\nuse the separate form, with an example.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/gitcli.txt | 9 +++++++++\n Documentation/gitcredentials.txt | 6 ++++++\n 2 files changed, 15 insertions(+)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex 7c709324ba..bd62cbd043 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -90,6 +90,15 @@ scripting Git:\n for long options. An option that takes optional option-argument must be\n written in the 'stuck' form.\n \n+ * Despite the above suggestion, when Arg is a path relative to the\n+ home directory of a user, e.g. ~/directory/file or ~u/d/f, you\n+ may want to use the separate form, e.g. `git foo --file ~/mine`,\n+ not `git foo --file=~/mine`. The shell will expand `~/` in the\n+ former to your home directory, but most shells keep the tilde in\n+ the latter. Some of our commands know how to tilde-expand the\n+ option value even when given in the stuck form, but not all of\n+ them do.\n+\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\ndiff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt\nindex 71dd19731a..35a7452c8f 100644\n--- a/Documentation/gitcredentials.txt\n+++ b/Documentation/gitcredentials.txt\n@@ -242,6 +242,12 @@ Here are some example specifications:\n [credential]\n \thelper = \"foo --bar='whitespace arg'\"\n \n+# store helper (discouraged) with custom location for the db file;\n+# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,\n+# to allow the shell to expand tilde to the home directory.\n+[credential]\n+\thelper = \"store --file ~/.git-secret.txt\"\n+\n # you can also use an absolute path, which will not use the git wrapper\n [credential]\n \thelper = \"/path/to/my/helper --with-arguments\"\n\nInterdiff:\n diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\n index e484be9a36..bd62cbd043 100644\n --- a/Documentation/gitcli.txt\n +++ b/Documentation/gitcli.txt\n @@ -92,13 +92,12 @@ scripting Git:\n \n * Despite the above suggestion, when Arg is a path relative to the\n home directory of a user, e.g. ~/directory/file or ~u/d/f, you\n - may want to use the separate form, e.g. `git credential-store\n - --file ~/sec/rit`, not `git credential-store --file=~/sec/rit`.\n - The shell will expand `~/` in the former to your home directory,\n - but most shells keep the tilde in the latter. Some of our\n - commands know how to tilde-expand the option value internally,\n - but not all. The `--file` option of `credential-store` is an\n - example that it needs shell's help to tilde-expand its value.\n + may want to use the separate form, e.g. `git foo --file ~/mine`,\n + not `git foo --file=~/mine`. The shell will expand `~/` in the\n + former to your home directory, but most shells keep the tilde in\n + the latter. Some of our commands know how to tilde-expand the\n + option value even when given in the stuck form, but not all of\n + them do.\n \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 diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt\n index f6ce923f25..35a7452c8f 100644\n --- a/Documentation/gitcredentials.txt\n +++ b/Documentation/gitcredentials.txt\n @@ -243,7 +243,8 @@ Here are some example specifications:\n \thelper = \"foo --bar='whitespace arg'\"\n \n # store helper (discouraged) with custom location for the db file;\n -# tilde expansion often requires the filename as a separate argument.\n +# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,\n +# to allow the shell to expand tilde to the home directory.\n [credential]\n \thelper = \"store --file ~/.git-secret.txt\"\n \n-- \n2.47.0-496-g788c9fe963\n\n\n"},{"id":"508010","messageId":"CAPig+cTCiyc-8GnEEKZvDTAvmrXNrfJ-Uq4=7TCv21UgoiKAZw@mail.gmail.com","threadId":"62531","inReplyTo":"xmqqh67w6m4m.fsf@gitster.g","subject":"Re: [PATCH v2] doc: option value may be separate for valid reasons","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-11-25T03:35:59Z","receivedAt":"2024-11-25T03:36:11Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Nov 24, 2024 at 10:14 PM Junio C Hamano wrote:\n> Even though `git help cli` recommends users to prefer using\n> \"--option=value\" over \"--option value\", there can be reasons why\n> giving them separately is a good idea. One reason is that shells do\n> not perform tilde expansion for `--option=~/path/name` but they\n> expand `--options ~/path/name` just fine.\n>\n> This is not a problem for many options whose option parsing is\n> properly written using OPT_FILENAME(), because the value given to\n> OPT_FILENAME() is tilde-expanded internally by us, but some commands\n> take a pathname as a mere string, which needs this trick to have the\n> shell help us.\n>\n> I think the reason we originally decided to recommend the stuck form\n> was because an option that takes an optional value requires you to\n> use it in the stuck form, and it is one less thing for users to\n> worry about if they get into the habit to always use the stuck form.\n> But we should be discouraging ourselves from adding an option with\n> an optional value in the first place, and we might want to weaken\n> the current recommendation.\n>\n> In any case, let's describe this one case where it is necessary to\n> use the separate form, with an example.\n>\n> Signed-off-by: Junio C Hamano \n\nv2 looks good to me.\n"},{"id":"508011","messageId":"xmqq7c8r7wab.fsf@gitster.g","threadId":"62531","inReplyTo":"CAPig+cTCiyc-8GnEEKZvDTAvmrXNrfJ-Uq4=7TCv21UgoiKAZw@mail.gmail.com","subject":"Re: [PATCH v2] doc: option value may be separate for valid reasons","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-11-25T04:49:16Z","receivedAt":"2024-11-25T04:49:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> On Sun, Nov 24, 2024 at 10:14 PM Junio C Hamano wrote:\n>> Even though `git help cli` recommends users to prefer using\n>> \"--option=value\" over \"--option value\", there can be reasons why\n>> giving them separately is a good idea. One reason is that shells do\n>> not perform tilde expansion for `--option=~/path/name` but they\n>> expand `--options ~/path/name` just fine.\n>>\n>> This is not a problem for many options whose option parsing is\n>> properly written using OPT_FILENAME(), because the value given to\n>> OPT_FILENAME() is tilde-expanded internally by us, but some commands\n>> take a pathname as a mere string, which needs this trick to have the\n>> shell help us.\n>>\n>> I think the reason we originally decided to recommend the stuck form\n>> was because an option that takes an optional value requires you to\n>> use it in the stuck form, and it is one less thing for users to\n>> worry about if they get into the habit to always use the stuck form.\n>> But we should be discouraging ourselves from adding an option with\n>> an optional value in the first place, and we might want to weaken\n>> the current recommendation.\n>>\n>> In any case, let's describe this one case where it is necessary to\n>> use the separate form, with an example.\n>>\n>> Signed-off-by: Junio C Hamano \n>\n> v2 looks good to me.\n\nThanks.\n"}]}