{"thread":{"id":"60729","subject":"would these doc and completion patches like this welcome?","startedAt":"2024-01-11T21:42:29Z","lastAt":"2024-01-11T21:42:29Z","messageCount":1,"participants":["Britton Kerin"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"486663","messageId":"CAC4O8c-tdkhhDYa9GaHZwhaC_0VG8x-v7eVULY7PiF1Z8ZgFXg@mail.gmail.com","threadId":"60729","inReplyTo":null,"subject":"would these doc and completion patches like this welcome?","fromName":"Britton Kerin","fromEmail":"britton.kerin@gmail.com","sentAt":"2024-01-11T21:42:15Z","receivedAt":"2024-01-11T21:42:29Z","isPatch":false,"sender":{"key":"britton.kerin@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7434164?v=4"},"body":"Someone mentioned that there were other places where should be\n and I looked through the docs a bit to see, and also noted\nsimple completion fixes.\n\nThere were a number of small issues I saw that I'll fix if there's\ninterest but I want to ask before spending time (I have a few patches\nsubmitted at the moment and can't tell if they are unwelcome or what).\n\nTo give an idea what I have in mind the rough notes I made on a first\npass through are below. Note that I haven't got as far as verifying\nfor sure e.g. what actually takes a pathspec so there may be mistakes\nin here.\n\nThe question now is is there enough interest that I should proceed or not?\n\n\nHere's the list:\n\n\n\ngit-am:\n\n doc: --exclude and --include probably take , but currently refer\n to . Note: Underlying git-apply currently says in\n detailed description, in synopsis\n\n doc: --directory= in synopsis and detailed description but should\n probably be since the detailed description in git-am just says\n that \"These flags are passed to the git apply\"\n\n comp: --directory= takes and should complete a dir\n\ngit-archive:\n\n doc: is argument really a or should it be ?\n\ngit-bisect:\n\n doc: mentions of path in main text should be (assuming\n guy on mailing list who said it actually takes a was right,\n check)\n\ngit-clone:\n\n doc: or ? who cares I think but elsewhere some use \n \n\n comp: should be completed\n\n comp: should be completed\n\ngit-describe:\n\n doc: synopsis mentions but later text just mentions blob, I think this\n is not how other tools mention such things\n\ngit-diff:\n\n doc: are all the mentions of really or should they be\n ?\n\n doc: is optional arg to --relative really a , or is it a ?\n\n comp: there are lots of options that aren't completed that should be\n\n comp: NOTE: should not get completed as dir even if they aren't\n since they might be files\n\n comp: NOTE: the optional arg to --relative should not be completed as an\n actual dir\n\ngit-format-patch:\n\n doc: is optional arg to --relative really a , or is it a ?\n\n doc: what is ?\n\n doc: --from in main text but not synopsis\n\n comp: --to --cc --from don't have optarg completion help for format-patch\n as they do for send-email. I notice that according to it's\n --git-completion-helper output format-patch doesn't implement --bcc\n hmnm is that really true so weird\n\n comp: NOTE: the optional arg to --relative should not be completed as an\n actual dir\n\ngit-init:\n\n doc: has both [--template=] and\n [--separate-git-dir ], I see no reason one of these should get\n an = and the other not, seems like both should get = and that's how this\n command does it though other git commands seem to doc differently\n\n doc: is mentioned in synopsis but only underlined directory in\n body. elsewhere in same file words like this do get their <> and are\n underlined also. what is the\n actual git way for this? Just underline? Underline and <> (seems\n right to me?) Underline seems to be the common utility way (for ls, cp,\n ln at least which I checked, but those don't use <> everywhere. I\n guess I sort of think it should be one or the other not both and git\n uses <> everywhere for args and optargs. FIXME: sheesh I can't quit\n tell when bold is even getting used in my terminal font it's similar\n enough but actuall bold and <> seems pretty common as well\n\n comp: arg to --template should be completed as a dir\n\n comp: arg to --separate-git-dir should be completed as a dir\n\n comp: the optional [] arg appears to be the only possible\n non-option argument and so should be easy to complete as a dir\n\ngit-log:\n\n doc: synopsis says ... probably it means ... check\n\n doc: full text also mentions in a number of places, it should\n probably by ... but at least ... (or sometimes just\n or )\n\n doc: is optional arg to --relative really a , or is it a ?\n\n comp: NOTE: the optional arg to --relative should not be completed as an\n actual dir\n\ngit-pull:\n\n doc: one option description reads '--squash, --no-squash' while another reads\n '--[no-]verify'. I think I like the first way better for easy search\n but I think the second might be more common. Find out the preferred\n way and make consistent.\n\ngit-range-diff:\n\n doc: refers to where it likely means pathspec. highlights \n but doesn't underline\n\ngit-reset:\n\n doc: says 'can copy the contents of a path out of a commit' I believe it\n really means 'contents of a pathspec' but that's so clunky to read\n and understand and so much less likely to be what someone is attempting\n if they're doing the already somewhat exatic thing described that it's\n probably better to just keep on being wrong here.\n\ngit-shortlog:\n\n doc: refers to but should probably be \n\n doc: is optional arg to --relative really a , or is it a ?\n\n comp: NOTE: the optional arg to --relative should not be completed as an\n actual dir\n\n doc: mentions in one place ('as the ' should be 'as a ')\n refers to but should probably be \n\ngit-submodule:\n\n doc: all over the place but then the text mentions in one\n place that looks representative so probably they should all be\n \n\n doc: describes (an optional argument) under options\n\ngit-worktree:\n\n doc: NOTE: I don't think these should be doced as regardless of\n what the actual code takes. Out of curiosity what does actual code\n take?\n\n comp: repair subcommand: should be completed to a real dir in this\n case\n\ngitk:\n\n doc: says probably means \n\ngit-config:\n\n doc: appears in synopsis but isn't mentioned in text\n\ngit-reflog:\n\n doc: takes , argubly should be ...\n\ngit-repack:\n\n comp: --expire-to= should complete dirs\n\n comp: --filter-to= should complete dirs\n\ngit-bugreport:\n\n doc: in general (not just for this command) should opts that need a path\n that's a dir always call it rather than ?\n\n comp: completion needs implemented\n\n comp: -o/--ouput-directory should complete dirs\n\ngit-diagnose:\n\n comp: completion needs implemented\n\n comp: -o/--ouput-directory should complete dirs\n\ngit-difftool:\n\n comp: there are lots of options that need completion added for underlying\n git-diff. For some reason git difftool --git-completion-help doesn't\n pull in the git-diff options (unlike send-email does format-patch\n options) perhaps this could be fixed?. Or the git-diff options could\n be factored into a function so they can be used for both _git_diff\n and _git_difftool\n\ngit-merge-tree:\n\n doc: --stdin appears pretty significant, but doesn't have an entry of it's\n own in the OPTIONS section\n\n comp: not implemented at all yet\n\ngit-archimport:\n\n comp: not implemented, probably not worth it\n\ngit-cvsexportcommit:\n\n comp: not implemented, probably not worth it\n\ngit-cvsserver:\n\n comp: not implemented, probably not worth it\n\ngit-quiltimport:\n\n doc: --patches= might be better than --patches , how to handle this\n in general?\n\n comp: not implemented yet\n\n comp: --patches should complete dirs\n\ngit-send-email:\n\n doc: send-email docs --to --from --cc with different docs than the\n corresponding format-patch options. Are they not just passed through in\n the case where format-patch is being done implicitly? Do they override\n for an already-prepared patch series? Hmm\n\n comp: all long opts of send-email and format-patch are accepted via\n the --git-completion-helper mechanism. Unfortunately this means all\n git-format-patch opts are accepted even when --no-format-patch has been\n given. Both commands support --git-completion-helper so in theory\n the wrong option set could be filtered back out. It's not possible\n to do this from the arg since it probably isn't there yet and might\n be ambiguous anyway\n\n * there are at least some opts for which optargs aren't completed:\n\n comp: should --reply-to be completed like --to=*|--cc=*|--bcc=*|--from=* are?\n\n comp: should --envelope-sender be completed like\n --to=*|--cc=*|--bcc=*|--from=* are?\n\n comp: optarg to --smtp-encryption could be completed\n\n comp: optarg to --transfer-encoding could be be completed\n\n comp: optarg to --smtp-debug could be be completed\n"}]}