From a215da823f1c8aa1f57802cf5b41d1353f804670 Mon Sep 17 00:00:00 2001
From: Robert <robertosheagamedev@gmail.com>
Date: Tue, 21 Oct 2025 18:40:02 +0100
Subject: [PATCH] docs(vimfn): getcwd() behavior #36222

(cherry picked from commit cf48741227a9aa77533d5adfd2379e7c16c71363)
---
 runtime/doc/vimfn.txt           | 11 +++++++----
 runtime/lua/vim/_meta/vimfn.lua | 11 +++++++----
 src/nvim/eval.lua               | 11 +++++++----
 3 files changed, 21 insertions(+), 12 deletions(-)

diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt
index 93f5428776..2af7fbeea0 100644
--- a/runtime/doc/vimfn.txt
+++ b/runtime/doc/vimfn.txt
@@ -3485,16 +3485,19 @@ getcwd([{winnr} [, {tabnr}]])                                         *getcwd()*
 		With no arguments, returns the name of the effective
 		|current-directory|. With {winnr} or {tabnr} the working
 		directory of that scope is returned, and 'autochdir' is
-		ignored.
-		Tabs and windows are identified by their respective numbers,
-		0 means current tab or window. Missing tab number implies 0.
-		Thus the following are equivalent: >vim
+		ignored. Tabs and windows are identified by their respective
+		numbers, 0 means current tab or window. Missing tab number
+		implies 0. Thus the following are equivalent: >vim
 			getcwd(0)
 			getcwd(0, 0)
 <		If {winnr} is -1 it is ignored, only the tab is resolved.
 		{winnr} can be the window number or the |window-ID|.
 		If both {winnr} and {tabnr} are -1 the global working
 		directory is returned.
+		Note: When {tabnr} is -1 Vim returns an empty string to
+		signal that it is invalid, whereas Nvim returns either the
+		global working directory if {winnr} is -1 or the working
+		directory of the window indicated by {winnr}.
 		Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
 
                 Parameters: ~
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index bd77474d59..34862b6dc2 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3124,16 +3124,19 @@ function vim.fn.getcursorcharpos(winid) end
 --- With no arguments, returns the name of the effective
 --- |current-directory|. With {winnr} or {tabnr} the working
 --- directory of that scope is returned, and 'autochdir' is
---- ignored.
---- Tabs and windows are identified by their respective numbers,
---- 0 means current tab or window. Missing tab number implies 0.
---- Thus the following are equivalent: >vim
+--- ignored. Tabs and windows are identified by their respective
+--- numbers, 0 means current tab or window. Missing tab number
+--- implies 0. Thus the following are equivalent: >vim
 ---   getcwd(0)
 ---   getcwd(0, 0)
 --- <If {winnr} is -1 it is ignored, only the tab is resolved.
 --- {winnr} can be the window number or the |window-ID|.
 --- If both {winnr} and {tabnr} are -1 the global working
 --- directory is returned.
+--- Note: When {tabnr} is -1 Vim returns an empty string to
+--- signal that it is invalid, whereas Nvim returns either the
+--- global working directory if {winnr} is -1 or the working
+--- directory of the window indicated by {winnr}.
 --- Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
 ---
 --- @param winnr? integer
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index f6a7b5a871..67aa3c1595 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -3915,16 +3915,19 @@ M.funcs = {
       With no arguments, returns the name of the effective
       |current-directory|. With {winnr} or {tabnr} the working
       directory of that scope is returned, and 'autochdir' is
-      ignored.
-      Tabs and windows are identified by their respective numbers,
-      0 means current tab or window. Missing tab number implies 0.
-      Thus the following are equivalent: >vim
+      ignored. Tabs and windows are identified by their respective
+      numbers, 0 means current tab or window. Missing tab number
+      implies 0. Thus the following are equivalent: >vim
       	getcwd(0)
       	getcwd(0, 0)
       <If {winnr} is -1 it is ignored, only the tab is resolved.
       {winnr} can be the window number or the |window-ID|.
       If both {winnr} and {tabnr} are -1 the global working
       directory is returned.
+      Note: When {tabnr} is -1 Vim returns an empty string to
+      signal that it is invalid, whereas Nvim returns either the
+      global working directory if {winnr} is -1 or the working
+      directory of the window indicated by {winnr}.
       Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
 
     ]=],