{"thread":{"id":"62558","subject":"gitrevisions: be more chatty about shell metacharacter gotchas?","startedAt":"2024-11-28T19:30:57Z","lastAt":"2024-12-02T16:18:03Z","messageCount":3,"participants":["Kristoffer Haugsbakk","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"508306","messageId":"702d88e9-c62d-482c-a457-6d6642e8488e@app.fastmail.com","threadId":"62558","inReplyTo":null,"subject":"gitrevisions: be more chatty about shell metacharacter gotchas?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-11-28T19:30:17Z","receivedAt":"2024-11-28T19:30:57Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"See this question from today (+CC):\n\nhttps://stackoverflow.com/q/79232719/1725151\n\nThe problem turned out to be:\n\n> You are using the Windows command line CMD. This beast treats ^\n> specially (it > is some sort of escape character). You have to type it\n> twice for every occurrence where you need one of them: [...]\n\nNow gitrevisions(7) already has this:\n\n    Note\n    This document shows the \"raw\" syntax as seen by git. The shell and\n    other UIs might require additional quoting to protect special characters\n    and to avoid word splitting.\n\nAll bases covered.\n\nBut, and I don’t know why I didn’t realize this sooner than I did, but\nthis part:\n\n    :/<text>, e.g. :/fix nasty bug\n    [...]\n    Depending on the given text, the shell’s word splitting rules might require\n    additional quoting.\n\nI don’t recall reading this part (only glazing over it).  I did eventually\nguess that I needed to\n\n    :/'fix nasty bug'\n\nbecause that part needs to be “one word”.  Or something.  It can’t be split.\n\nI think I’m a low-intermediate shell user.  I get by.  In a wider\nperspective, git(1) (i.e. in a terminal context, mostly) is used by people\nfrom a wide range of skill levels.  Many seem to (based on the question I\nstumble over) mostly be using a terminal because they need to use git(1) and\nthat’s about it.\n\nSo would it make sense to be a bit more chatty about these metacharacter\ngotchas on this page?  Maybe add a “Note” on e.g. `^` that these here (?)\npopular shells use `^` as a metacharacter?\n\nThat would for sure be redundant.  But IMO good documentation finds a\nbalance between redundancy and other concerns.  Like in the form\nof reminders and localized hints.\n\nAlso back to this paragraph:\n\n    Depending on the given text, the shell’s word splitting rules might require\n    additional quoting.\n\nPart of why my eyes might have glazed over (I think) is that this is very\ntechnical phrasing.  Yes, technical phrasing in a technical manual.  To be\nexpected.  But the topic is the revision syntax; all of us Git users of\nvarying levels might be primed for less terse but more evident paragraphs\nlike\n\n    Keep in mind that you probably should quote the search string.  A search\n    string like `:/fix nasty bug` could be interpreted as just `:/fix`\n    depending on how your shell splits words.  Try to stick to\n    `:/'fix nasty bug'` or `:/\"fix nasty bug\"` (whichever is better in your\n    shell) for that reason.\n\nBecause this leads with what the gotcha and remedy is about.\n\nThoughts?\n"},{"id":"508406","messageId":"xmqqttbmkh8h.fsf@gitster.g","threadId":"62558","inReplyTo":"702d88e9-c62d-482c-a457-6d6642e8488e@app.fastmail.com","subject":"Re: gitrevisions: be more chatty about shell metacharacter gotchas?","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-12-02T01:26:22Z","receivedAt":"2024-12-02T01:26:25Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n\n> Part of why my eyes might have glazed over (I think) is that this is very\n> technical phrasing.  Yes, technical phrasing in a technical manual.  To be\n> expected.  But the topic is the revision syntax; all of us Git users of\n> varying levels might be primed for less terse but more evident paragraphs\n> like\n>\n>     Keep in mind that you probably should quote the search string.  A search\n>     string like `:/fix nasty bug` could be interpreted as just `:/fix`\n>     depending on how your shell splits words.  Try to stick to\n>     `:/'fix nasty bug'` or `:/\"fix nasty bug\"` (whichever is better in your\n>     shell) for that reason.\n>\n> Because this leads with what the gotcha and remedy is about.\n\nI am very much sympathetic to the cause to help people avoid making\nmistakes, and reminding of the basic rules of command line syntax\n\"as needed\" may be a good idea.\n\nAny arguments and options you give from the command line are subject\nto the same shell quoting rules, and we at least need one single\nplace to say exactly that to help beginners.\n\nOn top of that, there are probably arguments and options that more\noften contain shell metacharacters (like '*' and ' ') than other\narguments and options, and it may be helpful to beginners to remind\nthe need for quoting.  But \"as needed\" is relative to the level of\nreader, and if we overdo it, it would make it less readable for\nother readers.\n\nThere already is a note about '*'; we can add another note about\nwhitespace next to it, perhaps here.\n\n Documentation/gitcli.txt | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\nindex 7c709324ba..0a67005fc6 100644\n--- c/Documentation/gitcli.txt\n+++ w/Documentation/gitcli.txt\n@@ -57,6 +57,16 @@ When writing a script that is expected to handle random user-input, it is\n a good practice to make it explicit which arguments are which by placing\n disambiguating `--` at appropriate places.\n \n+ * Arguments, options, and option values given on the shell command\n+   line follow the usual shell syntax rules.  You'd need to quote\n+   your string with whitespace in it appropriately if you do not\n+   want it to be split by the shell, for example.\n++\n+--------------------------------\n+$ git commit -m \"my message with whitespace\"\n+$ git show \"HEAD^{/^my message with whitespace}\"\n+--------------------------------\n+\n  * Many commands allow wildcards in paths, but you need to protect\n    them from getting globbed by the shell.  These two mean different\n    things:\n\n\n\n"},{"id":"508454","messageId":"8752f4b3-db2e-4db5-bb1d-8b87cb6fadbd@app.fastmail.com","threadId":"62558","inReplyTo":"xmqqttbmkh8h.fsf@gitster.g","subject":"Re: gitrevisions: be more chatty about shell metacharacter gotchas?","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2024-12-02T16:17:41Z","receivedAt":"2024-12-02T16:18:03Z","isPatch":false,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Mon, Dec 2, 2024, at 02:26, Junio C Hamano wrote:\n> There already is a note about '*'; we can add another note about\n> whitespace next to it, perhaps here.\n>\n>  Documentation/gitcli.txt | 10 ++++++++++\n>  1 file changed, 10 insertions(+)\n>\n> diff --git c/Documentation/gitcli.txt w/Documentation/gitcli.txt\n> index 7c709324ba..0a67005fc6 100644\n> --- c/Documentation/gitcli.txt\n> +++ w/Documentation/gitcli.txt\n> @@ -57,6 +57,16 @@ When writing a script that is expected to handle\n> random user-input, it is\n>  a good practice to make it explicit which arguments are which by\n> placing\n>  disambiguating `--` at appropriate places.\n>\n> + * Arguments, options, and option values given on the shell command\n> +   line follow the usual shell syntax rules.  You'd need to quote\n> +   your string with whitespace in it appropriately if you do not\n> +   want it to be split by the shell, for example.\n> ++\n> +--------------------------------\n> +$ git commit -m \"my message with whitespace\"\n> +$ git show \"HEAD^{/^my message with whitespace}\"\n> +--------------------------------\n> +\n>   * Many commands allow wildcards in paths, but you need to protect\n>     them from getting globbed by the shell.  These two mean different\n>     things:\n\nThis is a good addition. Including a couple of good examples.\n\n-- \nKristoffer Haugsbakk\n"}]}