From f44ad753801d881f5352c9182167ced18e79e456 Mon Sep 17 00:00:00 2001
From: Christian Clason <c.clason@uni-graz.at>
Date: Thu, 27 Oct 2022 22:31:58 +0200
Subject: 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.
---
 src/nvim/api/autocmd.c | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

(limited to 'src/nvim/api/autocmd.c')

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