Adds shell completions for lychee by mre · Pull Request #1972 · lycheeverse/lychee

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

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

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

@@ -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.

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!

katrinafyi

Looks really good and will be a great feature!

Personally, I also prefer not checking in the completions, as long as they're included in the release binaries (which it looks like they are :D)

Edit: Just tested with fish and it's really great. This will help usability a lot.

katrinafyi · 2026-02-22T05:53:20Z

+
+### Bash
+
+**User installation:**


Maybe just a sentence here that if a user has installed lychee through a package manager, then hopefully completions should work out of the box. Otherwise, they can try the manual steps and/or ping the package maintained.

Also, maybe add a gitignore in this folder for the generated files.

katrinafyi · 2026-02-22T05:54:42Z

+          ./lychee --generate complete-bash > complete/lychee.bash
+          ./lychee --generate complete-elvish > complete/lychee.elv
+          ./lychee --generate complete-fish > complete/lychee.fish
+          ./lychee --generate complete-powershell > complete/_lychee.ps1


This block is repeated 3 times amongst the workflows. Can we use the makefile task instead? I'm just worried about subtle typos in the workflows that run less often, like release.

katrinafyi · 2026-02-22T05:56:03Z

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash


The script is lovely and colourful, but is it needed if completions aren't checked in anymore? If make completions succeeds then it should all be up to date.

katrinafyi · 2026-02-22T05:56:30Z

        run: make test
+      # Shell completions are generated from CLI help and should be platform-independent
+      - name: Check completions are up to date
+        run: ./scripts/check-completions.sh


Remove this to fix CI?

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

still needed

mre · 2026-03-13T23:29:30Z

This is ready for another review. I think I addressed all comments now.

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

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

mre commented Dec 28, 2025

View reviewed changes

Comment thread .github/workflows/test-completions.yml Outdated

mre commented Dec 28, 2025

View reviewed changes

Comment thread lychee-bin/src/commands/generate.rs

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 3 times, most recently from ebd3f2b to d120d40 Compare December 29, 2025 16:55

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

thomas-zahner approved these changes Jan 2, 2026

View reviewed changes

katrinafyi approved these changes Feb 22, 2026

View reviewed changes

mre added 10 commits March 14, 2026 00:06

Adds shell completions for lychee

7cd3318

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.

add temporary test completions workflow

bd4e2d5

cleanup

67a111f

cleanup

e27a32e

fix doc test

4d0d43f

Add make completions

73518fe

Avoid rebuilding binary for testing shell completions

5804f86

Clean up autogenerated shell-completions

93584e3

Simplify CI completion check and update docs and .gitignore

04d44e7

mre force-pushed the add-shell-completions branch from 4a88fa9 to 04d44e7 Compare March 13, 2026 23:06

Merge branch 'master' into add-shell-completions

dda70df

mre added 2 commits March 14, 2026 00:10

Add back clap_complete

e4f60ad

still needed

remove outdated ci check for feature flags

fa9b829

katrinafyi approved these changes Mar 14, 2026

View reviewed changes

mre merged commit 35a607d into master Mar 14, 2026
8 checks passed

mre deleted the add-shell-completions branch March 14, 2026 10:00

mre mentioned this pull request Mar 14, 2026

chore: release v0.24.0 #2048

Merged

mre mentioned this pull request Mar 25, 2026

Add shell completions #1564

Closed


		### Bash

		User installation:

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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!

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!

katrinafyi left a comment • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mre commented Mar 13, 2026

Uh oh!

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

katrinafyi left a comment •

edited

Loading