FR: Confusion about filetype=sh, and treesitter language bash

[stagnation]

Is your feature request related to a problem? Please describe. This is something that is not very clear in the documentation. I wanted to create new textobjects for "variables", or expansions in shell scripts, bash. And I'm very happy that it was quite easy, knowing what to do, but the documentation can be improved.

I want treesitter targets for variable expansions like:

• "$foo": around to include the dollar and inside just the variable name (already a group).
• "${foo_variable}: just the same.
• "${foo[@]}: a bash array, has a little more complex structure.

Thanks to :InspectTree, and :EditQuery I could construct the custom queries quite quickly, though it was a little hard to find pointers to these, amazing, built-in functions. I have previously use the treesitter-playground, which not mentioned the new functions in its readme.

But got stumped after creating my filetype-specific after-query: after/queries/sh/textobjects.scm.

The new custom captures did not work, and it was hard to understand why. Tinkering with the general function example I could observe some things.

The mapping is not created if the query does not match anything: So it is just available for relevant languages (makes sense but I did not see this in the docs). This could be verified thusly

File: after/queries/bash/textobjects.scm
; extends
(function_definition) @custom_capture

(command_substitution (_) @subprocess.inner) @subprocess.outer

[
 (simple_expansion (variable_name) @nils.inner) @nils.outer
 (expansion (_) @nils.inner) @nils.outer
]

File: after/queries/python/textobjects.scm
; extends
(function_definition) @custom_capture

# Shows that the custom capture is available for python
nvim +'set filetype=python' +'verbose map aF'
# But no mapping exists for sh
nvim +'set filetype=sh' +'verbose map aF'

It is good to have the python example to verify the expected behavior, thank you for that. Then it occurred to me that it maybe should be bash, as that is what is listed in the table. And that solves it.

filetype=sh requires queries for bash.

Describe the solution you'd like Clearer instructions for creating custom captures, and that the filetype and query languages are not always the same. This could be improved further with a way to show which scm files are loaded, like :scriptnames, so I could see a built-in bash.scm, but no sh.scm.