Adds shell completions for lychee #1972

mre · 2025-12-28T15:30:23Z

This follows ripgrep's lead and uses the same naming conventions for the CLI args. clap_complete does all the heavy-lifting, so there's no need to write our own generator. Completions get added to the binary releases.

@thomas-zahner, I tried to integrate the feature similar to your man page support (thanks for that!).

~~⚠️ TODO: Remove test-completions script before merging.~~

Also, we should probably update the homebrew recipe after the next release. Example from ripgrep: https://github.com/BurntSushi/ripgrep/blob/0a88cccd5188074de96f54a4b6b44a63971ac157/pkg/brew/ripgrep-bin.rb#L20

This follows ripgrep's lead and uses the same naming conventions for the CLI args. `clap_complete` does all of the heavy-lifting, so there's no need to write our own generator. Completions get added to the binary releases.

Adds PowerShell, GitHub, IPv4, and IPv6 to the list of valid identifiers to prevent warnings about missing backticks in documentation comments. - Rustdoc configuration in Cargo.toml under [package.metadata.rustdoc] - Clippy configuration in clippy.toml at workspace root

mre · 2025-12-28T16:15:27Z

.github/workflows/test-completions.yml

Just a test file to see if the workflow passes and generates those completion files.

So we remove this workflow before merging, right?

lychee-bin/src/commands/generate.rs

thomas-zahner

Thank you very much, cool addition 🚀
I haven't tested it yet. Before merging I would like to do so and update the nix-package accordingly

lychee-bin/complete/README.md

thomas-zahner · 2025-12-28T17:36:01Z

lychee-bin/complete/_lychee

@@ -0,0 +1,117 @@
+#compdef lychee


I think we shouldn't track any of these files (lychee-bin/complete/* expect readme), as they are generated either manually as described in the docs or via release workflow. Do you agree? We could then also consider moving lychee-bin/complete/README.md to docs/AUTOCOMPLETE.md

Ripgrep tracks them.. In my opinion, it's great to see the diff for future troubleshooting between versions of clap_complete.

Huh that surprises me..
Wouldn't we then also need a workflow, a test or some sort of automation to keep these generated files up to date? Otherwise, we constantly forget about keeping these files up-to-date.

Technically yes. That would be a nice addition, but it would also mean some additional work. These things tend to get tricky, especially with committing those files, which might trigger other workflows etc. But it's not strictly necessary in the beginning, in my opinion.

To expand on that a bit, I believe most people wouldn't care and for the few people who do, they get it out of the box as part of their release builds. We always bundle the latest versions. And the files in the repo are for troubleshooting, for the most part. I could add a make target to update them manually for now.

Yes that's why personally I would not track those generated files at all. They should always be fully reproducible and as you say they are generated and included with every release. It would be less code, less files and we wouldn't have this problem of outdated files at all.

But if you really prefer to include them for debugging/troubleshooting we can do so.

Also if most people don't care, why should we care to add these files to the repository in the first place? 😅

I think it would be interesting to know why ripgrep tracks them and if they have a mechanism to keep the files up-to-date.

Did some research.

They don't update the completions through CI, but they added a test to check that the completions are up-to-date, which is quite clever, because it would fail if contributors forget to update the file when new options get added: https://github.com/BurntSushi/ripgrep/blob/master/ci/test-complete

One reason (perhaps the only one?) why they track the completion files is that the ZSH completions are handwritten. https://github.com/BurntSushi/ripgrep/blob/0a88cccd5188074de96f54a4b6b44a63971ac157/crates/core/flags/complete/zsh.rs#L4-L5

This way, they get a lot of confidence in their completions with little maintenance overhead. We could do the same.

Added the check

One reason (perhaps the only one?) why they track the completion files is that the ZSH completions are handwritten.

Ah that would make sense. Then one could argue that we don't need to track them, as we have no customisation or handwritten scripts. Also we could do the new CI shell completion tests by using the output of --generate and not track the generated files. I personally would prefer that. I think tracking the generated files only has any benefit, if we make manual adjustments to those files or if we intend to do so in the future.

lychee-bin/src/commands/generate.rs

thomas-zahner · 2025-12-28T17:39:52Z

.github/workflows/test-completions.yml

So we remove this workflow before merging, right?

mre · 2025-12-29T10:54:51Z

@thomas-zahner fyi, I tested it on bash, zsh and fish on macOS.

Todo before merging:

Test locally (@thomas-zahner)
update nix package (@thomas-zahner)
remove test-completions workflow (@mre)

mre · 2025-12-29T17:05:12Z

The completion check makes the build slower (by ~30 seconds) because we have to build the binary first to run lychee --help. Maybe that's acceptable, but I'm open for suggestions. I would assume that it gets faster with subsequent runs because of the build cache.

thomas-zahner · 2025-12-30T15:26:16Z

The completion check makes the build slower

Thanks for adding the test.

You do build specifically for the test script.

      - name: Build binary
        run: cargo build

I don't think this should be necessary.
See Test the "zsh shell completions (Unix, sans cross)" step which is part of the normal ci workflow, where the binary was built in a previous step already. This would probably save those 30 additional seconds?

mre · 2025-12-31T16:54:04Z

Good idea. Let's try!

thomas-zahner · 2026-01-01T18:04:35Z

Cool. I've tested it with ZSH and it works perfectly fine. So it's fine to merge from my side. Only my comment about not tracking the generated files which I personally prefer. But I'm also fine with tracking them if you prefer it, or if you think we will soon do some manual adjustments to the scripts.

mre · 2026-01-02T01:14:02Z

Yup! That did the trick. Checking completion takes all of 1 second now. Thanks for the tip!

Adds shell completions for lychee

556593b

This follows ripgrep's lead and uses the same naming conventions for the CLI args. `clap_complete` does all of the heavy-lifting, so there's no need to write our own generator. Completions get added to the binary releases.

mre requested a review from thomas-zahner December 28, 2025 15:30

mre added 3 commits December 28, 2025 16:33

add temporary test completions workflow

c0a608f

cleanup

e64b09c

mre force-pushed the add-shell-completions branch from 39ff1d8 to e64b09c Compare December 28, 2025 16:07

cleanup

5f7bb2a

mre commented Dec 28, 2025

View reviewed changes

lychee-bin/src/commands/generate.rs Show resolved Hide resolved

fix doc test

c765094

mre force-pushed the add-shell-completions branch from 4a0217a to c765094 Compare December 28, 2025 16:20

thomas-zahner reviewed Dec 28, 2025

View reviewed changes

mre force-pushed the add-shell-completions branch 2 times, most recently from cf110f9 to ebd3f2b Compare December 29, 2025 16:51

Add make completions

d120d40

mre force-pushed the add-shell-completions branch from ebd3f2b to d120d40 Compare December 29, 2025 16:55

Avoid rebuilding binary for testing shell completions

78eb112

mre requested a review from thomas-zahner January 2, 2026 01:14

thomas-zahner approved these changes Jan 2, 2026

View reviewed changes

Clean up autogenerated shell-completions

4a88fa9

Uh oh!

Adds shell completions for lychee #1972

Are you sure you want to change the base?

Adds shell completions for lychee #1972

Conversation

mre commented Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

thomas-zahner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thomas-zahner Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thomas-zahner Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mre commented Dec 29, 2025 • edited by thomas-zahner Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mre commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thomas-zahner commented Dec 30, 2025

Uh oh!

mre commented Dec 31, 2025

Uh oh!

thomas-zahner commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mre commented Jan 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mre commented Dec 28, 2025 •

edited

Loading

thomas-zahner Dec 29, 2025 •

edited

Loading

thomas-zahner Jan 1, 2026 •

edited

Loading

mre commented Dec 29, 2025 •

edited by thomas-zahner

Loading

mre commented Dec 29, 2025 •

edited

Loading

thomas-zahner commented Jan 1, 2026 •

edited

Loading