[PATCH] meson: install shell completion scripts

[PATCH] meson: install shell completion scripts

[Patrick Steinhardt]

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(-)

diff --git a/contrib/completion/meson.build b/contrib/completion/meson.build
index 3a9ddab5940..019c1457488 100644
--- a/contrib/completion/meson.build
+++ b/contrib/completion/meson.build
@@ -1,16 +1,42 @@
-foreach script : [
-  'git-completion.bash',
-  'git-completion.tcsh',
-  'git-completion.zsh',
-  'git-prompt.sh'
-]
+foreach script, config : {
+  'git-completion.bash': {
+    'filename': 'git',
+    'install_dir': get_option('datadir') / 'bash-completion/completions',
+  },
+  'git-completion.tcsh': {},
+  'git-completion.zsh': {
+    'filename': '_git',
+    'install_dir': get_option('datadir') / 'zsh/site-functions',
+  },
+  'git-prompt.sh': {},
+}
+  # We have to discern between the test dependency and the installed file. Our
+  # tests assume the completion scripts to have the same name as the in-tree
+  # files, but the installed filenames need to match the executable's basename.
   if meson.version().version_compare('>=1.3.0')
     test_dependencies += fs.copyfile(script)
+
+    if config.has_key('install_dir')
+      fs.copyfile(script, config.get('filename'),
+        install: true,
+        install_dir: config.get('install_dir'),
+      )
+    endif
   else
     configure_file(
       input: script,
       output: script,
       copy: true,
     )
+
+    if config.has_key('install_dir')
+      configure_file(
+        input: script,
+        output: config.get('filename'),
+        copy: true,
+        install: true,
+        install_dir: config.get('install_dir'),
+      )
+    endif
   endif
 endforeach

---
base-commit: 5b97a56fa0e7d580dc8865b73107407c9b3f0eff
change-id: 20250407-b4-pks-meson-install-completions-e5552f1ae2bf

Re: [PATCH] meson: install shell completion scripts

[Akshay Hegde]

Hi Patrick,

On 2025-04-07 09:42 +0200, Patrick Steinhardt wrote:
> Hi,
>
> this patch is a result from the discussion at [1]. Thanks!
>
> Patrick
>
> [1]: <Z-uLqQd7QHZq-tB7@akshay.is>

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

Re: [PATCH] meson: install shell completion scripts

[Todd Zullinger]

Akshay Hegde wrote:
> Hi Patrick,
> 
> On 2025-04-07 09:42 +0200, Patrick Steinhardt wrote:
>> Hi,
>>
>> this patch is a result from the discussion at [1]. Thanks!
>>
>> Patrick
>>
>> [1]: <Z-uLqQd7QHZq-tB7@akshay.is>
> 
> 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.

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

Re: [PATCH] meson: install shell completion scripts

[Junio C Hamano]

Todd Zullinger <tmz@pobox.com> writes:

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

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.

Re: [PATCH] meson: install shell completion scripts

[Eli Schwartz]

[-- Attachment #1.1: Type: text/plain, Size: 4564 bytes --]

On 4/9/25 1:42 PM, Junio C Hamano wrote:
> Todd Zullinger <tmz@pobox.com> writes:
> 
>>> 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.
>>
>> 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.
> 
> 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.


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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 236 bytes --]

Re: [PATCH] meson: install shell completion scripts

[Junio C Hamano]

Eli Schwartz <eschwartz@gentoo.org> writes:

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

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.


> With zsh, things are a lot shakier. ...
> ... (a lot of explanation on zsh installation path quirks omitted)
> 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.

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.

Re: [PATCH] meson: install shell completion scripts

[Patrick Steinhardt]

On Thu, Apr 17, 2025 at 07:31:55AM -0700, Junio C Hamano wrote:
> Eli Schwartz <eschwartz@gentoo.org> writes:
> 
> > 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:
> > ...
> > ... 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
> 
> 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.

Okay, makes sense.

> > With zsh, things are a lot shakier. ...
> > ... (a lot of explanation on zsh installation path quirks omitted)
> > 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.
> 
> 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.

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

[PATCH v2] contrib/completion: install Bash completion

[Patrick Steinhardt]

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(+)

diff --git a/Makefile b/Makefile
index ac32d2d0bda..118592414b5 100644
--- a/Makefile
+++ b/Makefile
@@ -618,6 +618,7 @@ prefix = $(HOME)
 bindir = $(prefix)/bin
 mandir = $(prefix)/share/man
 infodir = $(prefix)/share/info
+bash_completion_dir = $(prefix)/share/bash-completion/completions
 gitexecdir = libexec/git-core
 mergetoolsdir = $(gitexecdir)/mergetools
 sharedir = $(prefix)/share
@@ -2321,6 +2322,7 @@ bindir_relative_SQ = $(subst ','\'',$(bindir_relative))
 mandir_SQ = $(subst ','\'',$(mandir))
 mandir_relative_SQ = $(subst ','\'',$(mandir_relative))
 infodir_relative_SQ = $(subst ','\'',$(infodir_relative))
+bash_completion_dir_SQ = $(subst ','\'',$(bash_completion_dir))
 perllibdir_SQ = $(subst ','\'',$(perllibdir))
 localedir_SQ = $(subst ','\'',$(localedir))
 localedir_relative_SQ = $(subst ','\'',$(localedir_relative))
@@ -3565,6 +3567,10 @@ endif
 ifneq (,$X)
 	$(foreach p,$(patsubst %$X,%,$(filter %$X,$(ALL_COMMANDS_TO_INSTALL) $(OTHER_PROGRAMS))), test '$(DESTDIR_SQ)$(gitexec_instdir_SQ)/$p' -ef '$(DESTDIR_SQ)$(gitexec_instdir_SQ)/$p$X' || $(RM) '$(DESTDIR_SQ)$(gitexec_instdir_SQ)/$p';)
 endif
+ifndef NO_BASH_COMPLETION
+	$(INSTALL) -d -m 755 '$(DESTDIR_SQ)$(bash_completion_dir_SQ)' && \
+	$(INSTALL) -m 644 contrib/completion/git-completion.bash '$(DESTDIR_SQ)$(bash_completion_dir_SQ)/git'
+endif
 
 	bindir=$$(cd '$(DESTDIR_SQ)$(bindir_SQ)' && pwd) && \
 	execdir=$$(cd '$(DESTDIR_SQ)$(gitexec_instdir_SQ)' && pwd) && \
diff --git a/contrib/completion/meson.build b/contrib/completion/meson.build
index 3a9ddab5940..576125b083d 100644
--- a/contrib/completion/meson.build
+++ b/contrib/completion/meson.build
@@ -14,3 +14,21 @@ foreach script : [
     )
   endif
 endforeach
+
+# We have to discern between the test dependency and the installed file. Our
+# tests assume the completion scripts to have the same name as the in-tree
+# files, but the installed filenames need to match the executable's basename.
+if meson.version().version_compare('>=1.3.0')
+  fs.copyfile('git-completion.bash', 'git',
+    install: true,
+    install_dir: get_option('datadir') / 'bash-completion/completions',
+  )
+else
+  configure_file(
+    input: 'git-completion.bash',
+    output: 'git',
+    copy: true,
+    install: true,
+    install_dir: get_option('datadir') / 'bash-completion/completions',
+  )
+endif

---
base-commit: 5b97a56fa0e7d580dc8865b73107407c9b3f0eff
change-id: 20250407-b4-pks-meson-install-completions-e5552f1ae2bf