Getting ZSH Tab-Completion Into apk-tools

Issue

I had been using Chimera Linux and discovered that apk did not have tab-completion under Zsh, and this bothered me. I expect my tools to help me, and when they don’t, I will look to either fix them or replace them. Shell tab-completion is not a necessary feature for terminal programs, but it can help learning unfamiliar tools, and speed things up for familiar ones. Here is a list of contributing reasons as to why this issue bothered me:

• I use the terminal a lot, generally as much as possible
• I care about efficiency
• I was new to both apk and Chimera

Research

I hadn’t previously done development work on shell completions, but figured since even some of the most basic, under-supported programs came packaged with it, it must not be that difficult to implement; so, why was such a widely used and versatile program lacking support for a de facto feature, for one of the most widely used shells? It had support for Bash completions, maybe it was more difficult to support for other shells?

I researched how shell completions are implemented. The answer (short): typically, a local file. I explored multiple completion files, noting the program they belonged to, reading their code, and extracting the concepts and behavior from the code I read. I cross-referenced my findings with apks Bash completion file. I was also able to locate apks Zsh completion file, in Alpine Linux’s aports repository.

I copied apk-tools’ _apk completion file for Zsh to my local machine’s appropriate shell completion directory for Zsh. I ran tests to ensure completions for apk were now properly working — they weren’t, the completions were for a different version of apk than Chimera was using at the time. But, this was progress, completions were now happening!

Momentum

I ended up manually manipulating the completions file to get the correct completions, leading to me understanding that the issue was due to the aforementioned mismatch in apk versioning. I think I ended up finding a version of the completions that matched the version of apk Chimera used at the time, but I can’t recall.

After having successfully added Zsh completions for apk on my local machine, and gaining better understanding of what was going on, I reached out to Chimera via their IRC channel. The creator of Chimera, q66 (Daniel Kolesa) and a community member (“pj”) pointed me to what work needed to be done for Chimera users to have Zsh completions for apk — the apk-tools maintainer, Timo Teräs (@fabled), desired for the completions to be auto-generated at build time.

Hiatus

It would take 10 months before I started development on the issue, as changes in my personal life created time and energy issues for this matter. I never forgot about the issue, I thought it would be cool to contribute to the progress of a project (Chimera Linux) I felt was doing something I thought was cool, something I could get behind.

I eventually began looking for software work again, so that meant making myself stand out, adding experience under my belt. I had heard that open-source contributions look good, especially for self-taught developers, so I thought this might be a good opportunity for me to add to my experience.

Implementation

I started out by reviewing previous apk-tools issues and merge requests surrounding shell completions, collecting information on what exactly the maintainer would accept into the project. Honestly, now that I somewhat understood the logic behind shell completion files, I was disappointed and bothered that a solution had not yet been implemented (especially since this issue has been open since at least 2020).

I pooled all of my knowledge and understanding on the matter and prompted Claude AI (Sonnet 5) to check the plausibility of using the Bash completions’ genhelp script as a quick-start for implementing Zsh’s. Claude explained that much of the script would not be usable, but it could be used as a loose basis for the implementation, which is really what I was getting at.

Guided by Claude, I extended apk-tools’ genhelp pipeline by adding a Zsh completion generator. Once all the changes were made and all manual tests passed, I created a merge request on the apk-tools repository (!415).

Unexpected Issues

I ran into two issues during development, both in the build system:

1. A Meson build-target collision, with _apk as the target
2. A hardcoded format check, which only validated the existence of Bash’s genhelp script

Success!

My merge request was accepted and merged into the project. I don’t expect any further development on my end.

I published a project details page here.