patchmeson: install shell completion scripts

While Meson has support for _building_ our completion scripts, it does not yet know to also _install_ them. This omission is intentional as it matches the status quo of our Makefile, which doesn't know to install these scripts, either. In fact, our Makefile does not know about these scripts at all: the "build" step that Meson performs is basically just to copy over the files into the build directory, which is required so that our tests know to pick them up for an out-of-tree build.

The status quo is somewhat confusing for our users though, as the build steps need to be enabled manually by passing `-Dcontrib=completion` to Meson. So the user explicitly asks for completion scripts, but all they get is that we copy them into the build directory and execute tests.

Teach Meson to install completions for Bash and Zsh into the prefix. For now, we try to do the "right thing" and install the scripts into the installation prefix at their canonical paths. These paths should be standardized enough these days so that this works alright for most distributions. If we ever discover that these paths don't work well we can still introduce build options at a later point in time.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
Hi,

this patch is a result from the discussion at [1]. Thanks!

Patrick

[1]: <Z-uLqQd7QHZq-tB7@akshay.is>
---
 contrib/completion/meson.build | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

Hi Patrick,

On 2025-04-07 09:42 +0200, Patrick Steinhardt wrote:

Awesome, thanks for the patch! I applied it on top of git 2.49.0 and can confirm completion scripts get auto-installed at their appropriate locations under datadir. The datadir can also be customized by passing in '-Ddatadir' to `meson setup` so it's pretty flexible.

One thing of note is that the git completion script for zsh also depends on the bash completion script.

So if you use a non-standard install location like I do (I'm pretty weird, I use macOS with a package manager I've written myself), you'll get an error with the git completion not being able to find the bash script. The fix is to tell zsh where the bash completion script is located. This is also helpfully communicated in the completion script for zsh:

    # You need git's bash completion script installed. By default bash-completion's
    # location will be used (e.g. pkg-config --variable=completionsdir bash-completion).
    #
    # If your bash completion script is somewhere else, you can specify the
    # location in your ~/.zshrc:
    #
    #  zstyle ':completion:*:*:git:*' script ~/.git-completion.bash

Adding the zstyle line to my ~/.zshrc made the completion script work without issues.

Most people won't run into this since if you have this installed in the standard locations, it should just work, and the zsh script does have logic to look for additional paths it may be under. I just wanted to mention it for info.

Cheers,

Akshay Hegde wrote:

I wonder whether it is proper to install the completion scripts relative to git's $datadir by default.

I think the default ought to use the pkg-config call to get the completionsdir variable, as the zsh completion script suggests. I am presuming that's something meson can do rather trivially, just as it would do to find the compile options for git's various build dependencies?

I don't know if that becomes too messy to be worthwhile when determining whether git is being installed by a normal user in $HOME or by a privileged user in a system-wide prefix like /usr.

(Or, perhaps more confusingly, in /usr/local, while the bash-completion bits are in /usr. /usr/local is one of the prefixes bash-completion uses by default, so that one would happen to work.)

Todd Zullinger <tmz@pobox.com> writes:

Yes, exactly. We left it out of what Makefile does for that exact reason. Distros will do what is best for their environment, and I do not think, unlike pkg-config used to figure out distro specific locations when doing a system-wide install, there is a location that will make everybody happy in the context of per-user installation.

If we were to install these completion script from make or meson, I suspect that we'd eventually need a separate make variable or meson configuration item (whose default value can come from $datadir unless there is a better setting that already exists in our system) that is only used to specify the location completion script.

Thanks.

On 4/9/25 1:42 PM, Junio C Hamano wrote:

bash-completion looks for scripts in a few different places, with a common theme that there is a "datadir" followed by the literal path bash-completion/completions -- some values for the datadir:

- $XDG_DATA_HOME defaulting to ~/.local/share
- entries in $PATH / the dirname for the absolute path to the completed
  program, if they match */bin/ or */sbin/ will calculate an additional
  datadir value of */share/
- $XDG_DATA_DIRS as a :-list defaulting to /usr/local/share:/usr/share

This is very difficult to get wrong, you are virtually guaranteed to get essentially any conceivable layout handled. Entry #2 on my list is pretty much the ultimate recourse, since as long as you leave meson datadir and bindir alone you can install into absolutely any prefix, no matter how weird, and successfully invoking `git` itself will as a side effect add the correct bash completion file.

And that also means that distros automatically do the right thing -- just configure with prefix=/usr and we get /usr/share/bash-completion/completions as expected

With zsh, things are a lot shakier. Canonically, there is a designated loader list for all zsh functions, including completions, and that is $fpath. It doesn't attempt to do anything fancy like indexing into $PATH.

The default zsh ./configure settings will add these two directories, and nothing else:

/usr/local/share/zsh/site-functions /usr/share/zsh/site-functions

So, it works if and only if you build software using a prefix of /usr or else /usr/local, and if you install software in $HOME then you are ummmm encouraged to have your ~/.zshrc manually add some directory of your arbitrary choosing.

Oh, and it also doesn't work on Debian, because of https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=934926

(I'm aware of this bug because when Joey Hess said "The simple fact is that as an upstream author who used the debian locations because they were the ones that worked on my system, I get bug reports from users of other systems that it's not right for wider uses of zsh." -- I was the user who caused him to file that bug in the first place.)

tl;dr on Debian, the directories which you are allowed to use are

/usr/local/share/zsh/site-functions /usr/share/zsh/vendor-functions /usr/share/zsh/vendor-completions

with the intention that you use the third one. They seem adamant that "vendor-completions" is such a better name than "site-functions" that they will require all debian packages to manually move their completions from the latter to the former, probably after running "meson install"...

So, my personal feelings on this patch are that we can and should unambiguously install the bash completion, but it would be reasonable to defer handling zsh until someone figures out how to do it correctly, which may be impossible.

Eli Schwartz <eschwartz@gentoo.org> writes:

OK, so that is clear and easy.  Next to where we have

    infodir = $(prefix)/share/info

we add

    bash_completion_dir = $(prefix)/share/bash-completion/completions

and everybody would be happy.  We do the parallel on the meson side.

Sounds good.  Or just use

    zsh_completion_dir = $(prefix)/share/zsh/site-functions

perhaps. Those who are making personal installation under $HOME at least would know that what they have under $prefix mirrors the /usr/{bin,lib,share,....}/ if things were installed for host, so even though zsh does not look into there, at least the layout would be familiar to the user. But I am even happier if we decide to leave it out as you suggested.

Thanks.

On Thu, Apr 17, 2025 at 07:31:55AM -0700, Junio C Hamano wrote:

Okay, makes sense.

Okay, I'll leave zsh out then. We can still add it at a later point in time if it ever becomes clear what we should be doing.

Patrick

The shell completion scripts in "contrib/completion" are being tested, but none of our build systems support installing them. This is somewhat confusing for Meson, where users can explicitly enable building these scripts via `-Dcontrib=completion`. This option only controlls whether the completions are built and tested against, where "building" is a bit of an euphemism for "copying them into the build directory".

Teach both our Makefile and Meson to install our Bash completion script. For now, this is the only completion script that we're installing given that Bash completions "just work" with a canonical well-known location nowadays. Other completion scripts, like for example the one for zsh, don't have a well-known location and/or require extra steps by the user to make them available. As such, we skip installing these scripts for now, but we may do so in the future if we ever figure out a proper way to do this.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
Hi,

this patch is a result from the discussion at [1]. Thanks!

Changes in v2:
 - Only install Bash completion for now.
 - Also install Bash completion via our Makefile.
 - Link to v1: https://lore.kernel.org/r/20250407-b4-pks-meson-install-completions-v1-1-8a7eb8b9284b@pks.im

Patrick

[1]: <Z-uLqQd7QHZq-tB7@akshay.is>
---
 Makefile                       |  6 ++++++
 contrib/completion/meson.build | 18 ++++++++++++++++++
 2 files changed, 24 insertions(+)