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: [PATCH] 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.
---
 runtime/doc/api.txt    | 8 +++++++-
 src/nvim/api/autocmd.c | 9 ++++++++-
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index b949f3016e..8928650a39 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3267,6 +3267,12 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
       pattern = { "*.py", "*.pyi" }
 <
 
+    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: >
+      pattern = vim.fn.expand("~") .. "/some/path/*.py"
+<
+
     Example values for event: >
       "BufWritePre"
       {"CursorHold", "BufWritePre", "BufWritePost"}
@@ -3279,7 +3285,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                  • group (string|integer) optional: the autocommand group name
                    or id to match against.
                  • pattern (string|array) optional: pattern or patterns to
-                   match against |autocmd-pattern|.
+                   match literally against |autocmd-pattern|.
                  • buffer (integer) optional: buffer number for buffer local
                    autocommands |autocmd-buflocal|. Cannot be used with
                    {pattern}.
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}.