docs(api): pattern is not expanded for autocommands (#20812)

Problem: Unlike `:autocmd`, `nvim_create_autocommand()` does not expand
environment variables in the `pattern`, which is unexpected.

Solution: Add a note to the documentation explaining this and suggesting
using `expand()` explicitly.

1 files changed, 8 insertions, 1 deletions

diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
index b5c695b9ce..3dfe77ba38 100644
--- a/src/nvim/api/autocmd.c
+++ b/src/nvim/api/autocmd.c
@@ -401,6 +401,13 @@ cleanup:
 ///   pattern = { "*.py", "*.pyi" }
 /// </pre>
 ///
+/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
+/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
+/// Instead, |expand()| such variables explicitly:
+/// <pre>
+///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
+/// </pre>
+///
 /// Example values for event:
 /// <pre>
 ///   "BufWritePre"
@@ -411,7 +418,7 @@ cleanup:
 /// @param opts Dictionary of autocommand options:
 ///             - group (string|integer) optional: the autocommand group name or
 ///             id to match against.
-///             - pattern (string|array) optional: pattern or patterns to match
+///             - pattern (string|array) optional: pattern or patterns to match literally
 ///             against |autocmd-pattern|.
 ///             - buffer (integer) optional: buffer number for buffer local autocommands
 ///             |autocmd-buflocal|. Cannot be used with {pattern}.