5 files changed, 58 insertions, 12 deletions
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index f91e4f0627..1eba702a06 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -1275,10 +1275,12 @@ exist, the next-higher scope in the hierarchy applies.
 							*:chd* *:chdir*
 :chd[ir][!] [path]	Same as |:cd|.
 
-					*:tc* *:tcd* *E5000* *E5001* *E5002*
-:tc[d][!] {path}        Like |:cd|, but set the current directory for the
-			current tab and window.  The current directory for
-			other tabs and windows is not changed.
+							*:tc* *:tcd*
+:tc[d][!] {path}	Like |:cd|, but only set the directory for the current
+			tab.  The current window will also use this directory.
+			The current directory is not changed for windows in
+			other tabs and for windows in the current tab that
+			have their own window-local directory.
 
 							*:tcd-*
 :tc[d][!] -		Change to the previous current directory (before the
@@ -1303,8 +1305,8 @@ exist, the next-higher scope in the hierarchy applies.
 :pw[d]			Print the current directory name.
 			Also see |getcwd()|.
 
-So long as no |:tcd| or |:lcd| command has been used, all windows share the
-same "current directory".  Using a command to jump to another window doesn't
+So long as no |:lcd| or |:tcd| command has been used, all windows share the
+same current directory.  Using a command to jump to another window doesn't
 change anything for the current directory.
 
 When |:lcd| has been used for a window, the specified directory becomes the
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index e956ccaa77..4467afaa16 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2316,6 +2316,7 @@ chansend({id}, {data})		Number	Writes {data} to channel
 char2nr({expr}[, {utf8}])	Number	ASCII/UTF-8 value of first char in {expr}
 charidx({string}, {idx} [, {countcc}])
 				Number	char index of byte {idx} in {string}
+chdir({dir})			String	change current working directory
 cindent({lnum})		Number	C indent for line {lnum}
 clearmatches([{win}])		none	clear all matches
 col({expr})			Number	column nr of cursor or mark
@@ -2461,6 +2462,7 @@ 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|
 hasmapto({what} [, {mode} [, {abbr}]])
 				Number	|TRUE| if mapping to {what} exists
 histadd({history}, {item})	String	add an item to a history
@@ -3280,6 +3282,27 @@ charidx({string}, {idx} [, {countcc}])
 			echo charidx('áb́ć', 6, 1)	returns 4
 			echo charidx('áb́ć', 16)		returns -1
 
+chdir({dir})						*chdir()*
+		Change the current working directory to {dir}.  The scope of
+		the directory change depends on the directory of the current
+		window:
+			- If the current window has a window-local directory
+			  (|:lcd|), then changes the window local directory.
+			- Otherwise, if the current tabpage has a local
+			  directory (|:tcd|) then changes the tabpage local
+			  directory.
+			- Otherwise, changes the global directory.
+		If successful, returns the previous working directory.  Pass
+		this to another chdir() to restore the directory.
+		On failure, returns an empty string.
+
+		Example: >
+			let save_dir = chdir(newdir)
+			if save_dir
+			   " ... do some work
+			   call chdir(save_dir)
+			endif
+<
 cindent({lnum})						*cindent()*
 		Get the amount of indent for line {lnum} according the C
 		indenting rules, as with 'cindent'.
@@ -4987,6 +5010,8 @@ getcwd([{winnr}[, {tabnr}]])				*getcwd()*
 			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.
 
 		Can also be used as a |method|: >
 			GetWinnr()->getcwd()
diff --git a/runtime/doc/usr_22.txt b/runtime/doc/usr_22.txt
index 56fe5ada2b..f53d578456 100644
--- a/runtime/doc/usr_22.txt
+++ b/runtime/doc/usr_22.txt
@@ -202,14 +202,28 @@ the other window.  This is called a local directory. >
 	:pwd
 	/home/Bram/VeryLongFileName
 
-So long as no ":lcd" command has been used, all windows share the same current
-directory.  Doing a ":cd" command in one window will also change the current
+So long as no `:lcd` command has been used, all windows share the same current
+directory.  Doing a `:cd` command in one window will also change the current
 directory of the other window.
-   For a window where ":lcd" has been used a different current directory is
-remembered.  Using ":cd" or ":lcd" in other windows will not change it.
-   When using a ":cd" command in a window that uses a different current
+   For a window where `:lcd` has been used a different current directory is
+remembered.  Using `:cd` or `:lcd` in other windows will not change it.
+   When using a `:cd` command in a window that uses a different current
 directory, it will go back to using the shared directory.
 
+
+TAB LOCAL DIRECTORY
+
+When you open a new tab page, it uses the directory of the window in the
+previous tab page from which the new tab page was opened. You can change the
+directory of the current tab page using the `:tcd` command. All the windows in
+a tab page share this directory except for windows with a window-local
+directory. Any new windows opened in this tab page will use this directory as
+the current working directory. Using a `:cd` command in a tab page will not
+change the working directory of tab pages which have a tab local directory.
+When the global working directory is changed using the ":cd" command in a tab
+page, it will also change the current tab page working directory.
+
+
 ==============================================================================
 *22.3*	Finding a file
 
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index c575dd9fd8..6a9284dac9 100644
--- a/runtime/doc/usr_41.txt
+++ b/runtime/doc/usr_41.txt
@@ -785,9 +785,10 @@ System functions and manipulation of files:
 	isdirectory()		check if a directory exists
 	getfsize()		get the size of a file
 	getcwd()		get the current working directory
-	haslocaldir()		check if current window used |:lcd|
+	haslocaldir()		check if current window used |:lcd| or |:tcd|
 	tempname()		get the name of a temporary file
 	mkdir()			create a new directory
+	chdir()			change current working directory
 	delete()		delete a file
 	rename()		rename a file
 	system()		get the result of a shell command as a string
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index c85cae4004..7e7bb7d62f 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -197,6 +197,10 @@ 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