docs: clarify chdir/CWD behaviors #16083

runtime/doc/editing.txt

@@ -1331,11 +1331,12 @@ window the current directory is changed to the last specified local current
 directory.  If none was specified, the global or tab-local directory is used.
 
 When changing tabs the same behaviour applies.  If the current tab has no
-local working directory the global working directory is used.  When a |:cd|
-command is used, the current window and tab will lose their local current
-directories and will use the global current directory from now on.  When
-a |:tcd| command is used, only the current window will lose its local working
-directory.
+local working directory the global working directory is used.
+
+When a |:cd| command is used, the current window and tab will lose their local
+current directories and will use the global current directory from now on.
+When a |:tcd| command is used, only the current window will lose its local
+working directory.
 
 After using |:cd| the full path name will be used for reading and writing
 files.  On some networked file systems this may cause problems.  The result of

runtime/doc/eval.txt

@@ -2461,8 +2461,8 @@ globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]])
 has({feature})			Number	|TRUE| if feature {feature} supported
 has_key({dict}, {key})		Number	|TRUE| if {dict} has entry {key}
 haslocaldir([{winnr} [, {tabnr}]])
-				Number	|TRUE| if current window executed |:lcd|
-					or |:tcd|
+				Number	|TRUE| if the window executed |:lcd| or
+					the tab executed |:tcd|
 hasmapto({what} [, {mode} [, {abbr}]])
 				Number	|TRUE| if mapping to {what} exists
 histadd({history}, {item})	String	add an item to a history
@@ -5012,6 +5012,7 @@ getcwd([{winnr}[, {tabnr}]])				*getcwd()*
 		{winnr} can be the window number or the |window-ID|.
 		If both {winnr} and {tabnr} are -1 the global working
 		directory is returned.
+		Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
 
 		Can also be used as a |method|: >
 			GetWinnr()->getcwd()
@@ -5774,8 +5775,9 @@ has_key({dict}, {key})					*has_key()*
 			mydict->has_key(key)
 
 haslocaldir([{winnr}[, {tabnr}]])			*haslocaldir()*
-		The result is a Number, which is 1 when the tabpage or window
-		has set a local path via |:tcd| or |:lcd|, otherwise 0.
+		The result is a Number, which is 1 when the window has set a
+		local path via |:lcd| or when {winnr} is -1 and the tabpage
+		has set a local path via |:tcd|, otherwise 0.
 
 		Tabs and windows are identified by their respective numbers,
 		0 means current tab or window. Missing argument implies 0.
@@ -5787,6 +5789,7 @@ haslocaldir([{winnr}[, {tabnr}]])			*haslocaldir()*
 		With {winnr} and {tabnr} use the window in that tabpage.
 		{winnr} can be the window number or the |window-ID|.
 		If {winnr} is -1 it is ignored, only the tab is resolved.
+		Throw error if the arguments are invalid. |E5000| |E5001| |E5002|
 
 		Can also be used as a |method|: >
 			GetWinnr()->haslocaldir()

runtime/doc/options.txt

@@ -1159,9 +1159,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 'cdpath' 'cd'		string	(default: equivalent to $CDPATH or ",,")
 			global
 	This is a list of directories which will be searched when using the
-	|:cd| and |:lcd| commands, provided that the directory being searched
-	for has a relative path, not an absolute part starting with "/", "./"
-	or "../", the 'cdpath' option is not used then.
+	|:cd|, |:tcd| and |:lcd| commands, provided that the directory being
+	searched for has a relative path, not an absolute part starting with
+	"/", "./" or "../", the 'cdpath' option is not used then.
 	The 'cdpath' option's value has the same form and semantics as
 	|'path'|.  Also see |file-searching|.
 	The default value is taken from $CDPATH, with a "," prepended to look

runtime/doc/vim_diff.txt

@@ -180,7 +180,6 @@ Commands:
   |:match| can be invoked before highlight group is defined
 
 Events:
-  |DirChanged| can be triggered when switching to another window
   |Signal|
   |TabNewEntered|
   |TermClose|
@@ -197,10 +196,6 @@ Functions:
   |stdpath()|
   |system()|, |systemlist()| can run {cmd} directly (without 'shell')
   |matchadd()| can be called before highlight group is defined
-  |getcwd()| and |haslocaldir()| may throw errors. *E5000* *E5001* *E5002*
-  |haslocaldir()|'s only possible return values are 0 and 1, it never returns 2.
-  `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global
-  working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
 Highlight groups:
   |highlight-blend| controls blend level for a highlight group
@@ -253,6 +248,8 @@ Variables:
 Nvim always builds with all features, in contrast to Vim which may have
 certain features removed/added at compile-time. |feature-compile|
 
+Some Vim features were changed in Nvim, and vice versa.
+
 If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
 are always available and may be used simultaneously. See |provider-python|.
 
@@ -428,6 +425,15 @@ Vimscript compatibility:
   `shell_error` does not alias to |v:shell_error|
   `this_session` does not alias to |v:this_session|
 
+Working directory (Vim implemented some of these later than Nvim):
+- |DirChanged| can be triggered when switching to another window.
+- |getcwd()| and |haslocaldir()| may throw errors if the tab page or window
+  cannot be found.  *E5000* *E5001* *E5002*
+- |haslocaldir()| only checks for tab-local directory when -1 is passed as
+  window number, and its only possible returns values are 0 and 1.
+- `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global
+  working directory. Use `getcwd(-1, -1)` to get the global working directory.
+
 ==============================================================================
 5. Missing legacy features				 *nvim-features-missing*