fd: Add missing Powershell completions to install path #224200
Conversation
This adds `fd.ps1` to `#{prefix}/share/pwsh/completions`, as it was not added to the formula initially, and was first added to the package in sharkdp/fd@4e7b403
For an example of a build output that proves `fd.ps1` is included in the macOS aarch64 release builds, see https://github.com/sharkdp/fd/actions/runs/15128752111/job/42525598460
This has the caveat of installing `fd.ps1` instead of `_fd.ps1`, I have been requested to make this change by @daeho-ro, and while I would prefer to avoid breaking the standard completion filename format I will revert the usage of `Utils.safe_popen_read` if it is necessary to get this merged.
Table of contentsCurrent behavior of
|
| Linked files |
|---|
 |
 |
Generally-accepted filename convention
The general convention is to prefix the file with _, and most completion loading plugins for Powershell only support this filename formatting.
As another example, please see the following documentation for clap_complete, which shows that the filenames that clap generates for Powershell completion files are also prefixed with _ by default.
Examples of convention usage
If you use the following commands, you can get a list of files (on GitHub) that are definitively Powershell autocomplete definitions:
# Note: ZSH-specific syntax was used to make this easier
# You need an authenticated Github account to use the gh search command
local lines=("${(f)$(gh search code --language powershell '[CompletionResult]::new' --json path --limit 1000 | jq '.[] | .path')}")
# Note: if you do not have the following commands available:
## Substitute gsed with sed
## Substitute rg with grep
for f in $lines; do
basename "$(printf '%s' "$f" | gsed -E 's/^"([^"]+)"$/\1/g')"
done | rg '^_' | wc -l
# Output: 185
# Total results: 570
While I would say that not all Powershell autocomplete files are actually suffixed with _, the results do contain a lot of personal dotfiles where the user has likely hardcoded sourcing them.
Usage in fd
Just as a quick note, fd (the formula this pull request is concerning), does actually use clap to generate it's completions, the only reason it's not using the _ filename is because it does not use clap_complete::generate_to, and is instead using clap_complete::generate in order to print the completions to stdout, and [as a result] we are forced to use generate_completions_from_executable.
https://github.com/sharkdp/fd/blob/dbea8a68a8b2cba8282d76e766c143948384d583/src/main.rs#L112
https://github.com/sharkdp/fd/blob/dbea8a68a8b2cba8282d76e766c143948384d583/src/main.rs#L123
https://github.com/sharkdp/fd/blob/dbea8a68a8b2cba8282d76e766c143948384d583/src/cli.rs#L747-L757
Usage in Homebrew Formulas
As far as Homebrew Formulas go, I can point out at least one other example where the private API generate_completions_from_executable is already used for the same reason: https://github.com/Homebrew/homebrew-core/blob/e1992a944aaa9d1450be3184d8e7e20e080bc75b/Formula/r/rip2.rb
If I run the following commands inside Homebrew/homebrew-core/Formulas/ as of commit d4298e3:
alias rgm='rg -j 16 -. -SNIo --no-heading'
rgm generate_completions_from_executable | wc -l
# Output: 641
rgm safe_popen_read | wc -l
# Output: 141
rgm "write Utils\.safe_popen_read" | wc -l
# Output: 17
This shows that 18% of calls to executables are using the private api, at least 17 of them are doing so because the wrapper commands have no ability to rename the destination file, I'd say it's likely that number is higher [but I'm only filtering for ones that write directly in the same line, which doesn't account for usages where the file contents is saved to a variable first].
Conclusion
I would strongly recommend against breaking a widely-accepted naming convention, especially in a case where standard libraries such as clap [and others] do use this convention, and in many cases not following this convention will break user's shell plugins which are designed to automatically load completion files with this naming convention.
The ideal solution here would be to add an optional argument to generate_completions_from_executable, which would dictate an output filename.
Proposed API change
I would suggest that the optional argument function something like the following example, so that you can avoid repeated calls to generate_completions_from_executable, and instead only have to specify a name for the given shells.
I considered using
shell_output_nameinstead ofoutput_name, but ultimately feel like the shorter name is better.
# Generic example
generate_completions_from_executable(bin/"foo", "completions", shells: [:bash, :zsh], base_name: "bar", output_name: { "pwsh" => "_bar.ps1" })
# Example specific to my use case
generate_completions_from_executable(bin/"fd", "--gen-completions", shells: [:bash, :fish, :pwsh], output_name: { "pwsh" => "_fd.ps1" })
Examples of proposed API change
As for the rip2 Formula example I gave earlier, where it is using this private API for the same reason, please take a look at how it could be improved:
--- rip2.rb 2025-05-22 16:58:37
+++ rip2-proposal.rb 2025-05-24 02:43:36
@@ -23,9 +23,8 @@
def install
system "cargo", "install", *std_cargo_args
- generate_completions_from_executable(bin/"rip", "completions")
+ generate_completions_from_executable(bin/"rip", "completions", shells: [:bash, :pwsh, :fish, :pwsh], output_name: { "pwsh" => "_rip.ps1" })
(share/"elvish/lib/rip.elv").write Utils.safe_popen_read(bin/"rip", "completions", "elvish")
- (share/"powershell/completions/_rip.ps1").write Utils.safe_popen_read(bin/"rip", "completions", "powershell")
(share/"nu/completions/rip.nu").write Utils.safe_popen_read(bin/"rip", "completions", "nushell")
end
Alternatively:
--- rip2.rb 2025-05-22 16:58:37
+++ rip2-proposal.rb 2025-05-24 02:45:41
@@ -23,9 +23,12 @@
def install
system "cargo", "install", *std_cargo_args
- generate_completions_from_executable(bin/"rip", "completions")
+ generate_completions_from_executable(
+ bin/"rip", "completions",
+ shells: [:bash, :pwsh, :fish, :pwsh],
+ output_name: { "pwsh" => "_rip.ps1" }
+ )
(share/"elvish/lib/rip.elv").write Utils.safe_popen_read(bin/"rip", "completions", "elvish")
- (share/"powershell/completions/_rip.ps1").write Utils.safe_popen_read(bin/"rip", "completions", "powershell")
(share/"nu/completions/rip.nu").write Utils.safe_popen_read(bin/"rip", "completions", "nushell")
end
Footnotes
Please let me know if I should convert this into an issue, or if there is a proper place to discuss the Formula API spec, as I'm not sure if this repository is the appropriate place to submit such a proposal.
I will also likely reach out to the fd team in order to ask them to change their filename format to the widely-accepted convention, when I have more time to do so.
|
⛔ It looks like @BrewTestBot cannot push to your PR branch. Please open future pull requests from a non-organization fork to simplify the merge process. |
|
🤖 An automated task has requested creation of a replacement PR. |
Replacement PR dispatched
|
✅ Replacement PR created at #224674. |
d71c8ea
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>, where<formula>is the name of the formula you're submitting?brew test <formula>, where<formula>is the name of the formula you're submitting?brew audit --strict <formula>(after doingHOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>)? If this is a new formula, does it passbrew audit --new <formula>?This adds
fd.ps1to#{prefix}/share/pwsh/completions, as it was not added to the formula initially, and was first added to the package in sharkdp/fd@4e7b403For an example of a build output that proves
fd.ps1is included in the macOS aarch64 release builds, see https://github.com/sharkdp/fd/actions/runs/15128752111/job/42525598460Unfortunately, I am not too sure how one is supposed to rename
fd.ps1to_fd.ps1when usinggenerate_completions_from_executable, if someone else is able to fix that I would greatly appreciate it.Please see the following for an example of where this private API is already used for the same reason: https://github.com/Homebrew/homebrew-core/blob/e1992a944aaa9d1450be3184d8e7e20e080bc75b/Formula/r/rip2.rb