Repository navigation
Match glob characters literally in completion and quote them for the shell - #1812
Merged
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1812 +/- ##
=======================================
Coverage 99.75% 99.75%
=======================================
Files 23 23
Lines 6632 6647 +15
=======================================
+ Hits 6616 6631 +15
Misses 16 16
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. |
tleonhardt
reviewed
Nov 14, 2026
# Conflicts: # CHANGELOG.md
…TH entries Removed the guard which made path_complete() and get_exes_in_path() return nothing when the search text contained '*' or '?'. Since the search text now goes through glob.escape(), those characters are matched literally like any other, so names containing them can be completed. get_exes_in_path() and find_editor() no longer skip PATH entries which are symbolic links to directories. get_exes_in_path() resolves each entry so a directory reachable through more than one entry is only searched once. Documented that completion results are literal names which are not escaped for a shell, and added tests for shell_cmd_complete() with bracketed names and for PATH directories containing glob characters.
Tab completion now adds quotes to a match containing '*', '?', or '[', as it already did for a match containing a space. With the wildcard guard gone, completing '!rm my*' to an unquoted 'my*file.txt' would have let the shell expand it to every matching file. get_exes_in_path() no longer raises when PATH has an empty or relative entry and the current working directory has been removed. Only absolute entries are resolved with realpath(). find_editor() now uses shutil.which() instead of walking PATH by hand. As a side effect it can find 'edit' on Windows, which the old search never could because it did not try any file extensions. Documented that a leading '~' is the exception to literal matching, promoted the 'Special Characters in Paths' docs section to H2, and moved the test helper which creates fake executables into conftest.py.
The glob-character quoting added in the previous commit applied to every completer. That broke commands which preserve quotes when one of their choices had a glob character, left a stray quote when completing an alias with a glob character in its name, and quoted every shell command when an executable named '[' was among the matches. path_complete() and shell_cmd_complete() now mark their results, and only marked results are quoted for a shell. The check covers the characters which are special to the platform's shell rather than only glob characters, a '[' only counts when a ']' follows it, and single quotes are used on POSIX when a name has a character which a shell still expands within double quotes. All other completions are quoted only for a space, as before. find_editor() goes back to searching the PATH directories itself. shutil.which() also searched the current directory on Windows and fell back to a default path when PATH was not set. The Windows editor list now names edit.exe so it can still be found. find_editor() and get_exes_in_path() share one helper for reading PATH.
Quoting every path_complete() result for shell-special characters reached commands which never involve a shell. A command taking its raw argument, with path_complete as its completer, received the quotes literally for a name like notes[2026].txt and could no longer open the file. The quoting is now decided where cmd2 knows a shell is the consumer: the arguments of the shell command and everything after a pipe. Everywhere else only a match with a space is quoted, as before. Within that scope a '[' is special even with no ']' after it, since zsh rejects it as a bad pattern, a leading '=' is special on POSIX, and the Windows list follows the characters cmd.exe documents as requiring quotes. The private Completions._quote_for_shell field no longer takes part in comparisons.
os.path.realpath() can raise for a PATH entry which can't be reached, such as one on an unavailable network share on Windows. Since find_editor() runs when cmd2 is imported, that could keep cmd2 from being imported. The PATH entries are now used as written. Executable names were already de-duplicated, so the only cost is searching a directory twice when it is listed under two names. The places which mark completions as being passed to a shell now share one helper, Cmd._for_shell(). Corrected the docs for how the quote character is chosen when several matches are offered, and documented that a macro which runs a shell command is not quoted for the shell.
tleonhardt
approved these changes
Nov 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This continues the work of #1811 by adding the fix to
get_exes_in_path().It started as that one fix and grew during review. It now makes file path and shell command completion treat every glob character literally, quotes completions which a shell would otherwise expand, and fixes how
PATHis searched.Changes
Literal matching of glob characters
get_exes_in_path()passes its search path throughglob.escape(), so executable names andPATHdirectories containing square brackets are matched literally. This is the same fix fix: complete literal bracketed file paths #1811 made topath_complete().path_complete()andget_exes_in_path()return nothing when the search text contained*or?. Now that the search text is escaped, the guard no longer protected anything. It only made those two characters behave differently from every other special character. A file namedmy*file.txtcan now be completed.~is still special inpath_complete(). The docstring and docs say so.Quoting of completions which are passed to a shell
!ls my*gives!ls "my*file.txt".!rm my*+ Tab used to complete nothing. It would have completed to an unquotedmy*file.txt, which the shell expands to every matching file.cmd2knows a shell is the consumer: the arguments of theshellcommand (including!) and everything after a pipe. Everywhere else, only a match with a space is quoted, exactly as before. A command which takes its raw argument and usespath_complete()therefore does not start receiving quotes for a name likenotes[2026].txt.Cmd._for_shell(), which sets a privateCompletions._quote_for_shellfield thatCmd._perform_completion()checks. The field is excluded from comparisons.*,?,[,{,},(,),<,>,|,&,;,$, a backtick, a backslash, and a leading#or=.cmd.exedocuments as requiring quotes, other than~.$, a backtick, a backslash, or a double quote in it. Those get single quotes, since a POSIX shell still interprets them inside double quotes. Windows always gets double quotes.[is common, so completing a shell command which could match it quotes every match. A bare[has to count because zsh rejects it as a bad pattern.PATHhandlingget_exes_in_path()andfind_editor()no longer skipPATHentries which are symbolic links to directories. Both now readPATHthrough one private helper,_get_path_dirs().os.path.realpath()can raise for an entry which can't be reached, andfind_editor()runs whencmd2is imported. Executable names are de-duplicated, so the only cost is searching a directory twice when it is listed under two names (e.g./bin->/usr/bin).edit.exeinstead ofedit. The other entries already had their extensions, and a file literally namededitcould never be found.Documentation and tests
get_exes_in_path(),shell_cmd_complete(), andpath_complete()with names and directories containing[,*, and?edit,run_script, file redirection, raw-argument commands, choices, and alias names are left alonePATHentries forget_exes_in_path()andfind_editor()PATHentries which can't be resolvedfind_editor(): the order of preference, an unsetPATH, and that the current directory is not searched*or?in a file name, a symbolic link, or a removed working directory are skipped on Windows.tests/conftest.pyasmake_exes().Behavior changes worth a look
shellarguments and piped commands are now quoted when they have a shell-special character. Completions everywhere else are unchanged.edit, which is what 91e5bc2 intended. This has not been confirmed on a Windows machine which has Edit installed.Follow-up
shell_cmd_complete()only checksos.path.sep, so on Windows text using forward slashes is treated as a bare command name. This predates the PR and is not fixed here.Testing
make check,make test(3064 passed, 3 skipped on macOS), andmake docs-testpass locally.!ls my*andhelp | grep -c . fiinserts the quoted name and that the shell then sees only that file, and thatedit fiandhelp > ficompletefile(1).txtwithout quotes.