Adding upstream version 2:9.1.0016.upstream/2%9.1.0016

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 238 insertions, 0 deletions

diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt
new file mode 100644
index 0000000..fd817eb
--- /dev/null
+++ b/runtime/doc/recover.txt
@@ -0,0 +1,238 @@
+*recover.txt*   For Vim version 9.1.  Last change: 2023 Apr 22
+
+
+		  VIM REFERENCE MANUAL    by Bram Moolenaar
+
+
+Recovery after a crash					*crash-recovery*
+
+You have spent several hours typing in that text that has to be finished
+next morning, and then disaster strikes: Your computer crashes.
+
+			DON'T PANIC!
+
+You can recover most of your changes from the files that Vim uses to store
+the contents of the file.  Mostly you can recover your work with one command:
+	vim -r filename
+
+1. The swap file	|swap-file|
+2. Recovery		|recovery|
+
+==============================================================================
+1. The swap file					*swap-file*
+
+Vim stores the things you changed in a swap file.  Using the original file
+you started from plus the swap file you can mostly recover your work.
+
+You can see the name of the current swap file being used with the command:
+
+	:sw[apname]					*:sw* *:swapname*
+
+Or you can use the |swapname()| function, which also allows for seeing the
+swap file name of other buffers.
+
+The name of the swap file is normally the same as the file you are editing,
+with the extension ".swp".
+- On Unix, a '.' is prepended to swap file names in the same directory as the
+  edited file.  This avoids that the swap file shows up in a directory
+  listing.
+- On MS-Windows machines and when the 'shortname' option is on, any '.' in the
+  original file name is replaced with '_'.
+- If this file already exists (e.g., when you are recovering from a crash) a
+  warning is given and another extension is used, ".swo", ".swn", etc.
+- An existing file will never be overwritten.
+- The swap file is deleted as soon as Vim stops editing the file.
+
+Technical: The replacement of '.' with '_' is done to avoid problems with
+	   MS-DOS compatible filesystems (e.g., crossdos, multidos).  If Vim
+	   is able to detect that the file is on an MS-DOS-like filesystem, a
+	   flag is set that has the same effect as the 'shortname' option.
+	   This flag is reset when you start editing another file.
+							*E326*
+	   If the ".swp" file name already exists, the last character is
+	   decremented until there is no file with that name or ".saa" is
+	   reached.  In the last case, no swap file is created.
+
+By setting the 'directory' option you can place the swap file in another place
+than where the edited file is.
+Advantages:
+- You will not pollute the directories with ".swp" files.
+- When the 'directory' is on another partition, reduce the risk of damaging
+  the file system where the file is (in a crash).
+Disadvantages:
+- You can get name collisions from files with the same name but in different
+  directories (although Vim tries to avoid that by comparing the path name).
+  This will result in bogus ATTENTION warning messages.
+- When you use your home directory, and somebody else tries to edit the same
+  file, that user will not see your swap file and will not get the ATTENTION
+  warning message.
+On the Amiga you can also use a recoverable ram disk, but there is no 100%
+guarantee that this works.  Putting swap files in a normal ram disk (like RAM:
+on the Amiga) or in a place that is cleared when rebooting (like /tmp on Unix)
+makes no sense, you will lose the swap file in a crash.
+
+If you want to put swap files in a fixed place, put a command resembling the
+following ones in your .vimrc:
+	:set dir=dh2:tmp	(for Amiga)
+	:set dir=~/tmp		(for Unix)
+	:set dir=c:\\tmp	(for Win32)
+This is also very handy when editing files on floppy.  Of course you will have
+to create that "tmp" directory for this to work!
+
+For read-only files, a swap file is not used.  Unless the file is big, causing
+the amount of memory used to be higher than given with 'maxmem' or
+'maxmemtot'.  And when making a change to a read-only file, the swap file is
+created anyway.
+
+The 'swapfile' option can be reset to avoid creating a swapfile.  And the
+|:noswapfile| modifier can be used to not create a swapfile for a new buffer.
+
+:nos[wapfile]   {command}			*:nos* *:noswapfile*
+		Execute {command}. If it contains a command that loads a new
+		buffer, it will be loaded without creating a swapfile and the
+		'swapfile' option will be reset.  If a buffer already had a
+		swapfile it is not removed and 'swapfile' is not reset.
+
+
+Detecting an existing swap file ~
+
+You can find this in the user manual, section |11.3|.
+
+
+Updating the swapfile ~
+
+The swap file is updated after typing 200 characters or when you have not
+typed anything for four seconds.  This only happens if the buffer was
+changed, not when you only moved around.  The reason why it is not kept up to
+date all the time is that this would slow down normal work too much.  You can
+change the 200 character count with the 'updatecount' option.  You can set
+the time with the 'updatetime' option.  The time is given in milliseconds.
+After writing to the swap file Vim syncs the file to disk.  This takes some
+time, especially on busy Unix systems.  If you don't want this you can set the
+'swapsync' option to an empty string.  The risk of losing work becomes bigger
+though.  On some non-Unix systems (MS-Windows, Amiga) the swap file won't be
+written at all.
+
+If the writing to the swap file is not wanted, it can be switched off by
+setting the 'updatecount' option to 0.  The same is done when starting Vim
+with the "-n" option.  Writing can be switched back on by setting the
+'updatecount' option to non-zero.  Swap files will be created for all buffers
+when doing this.  But when setting 'updatecount' to zero, the existing swap
+files will not be removed, it will only affect files that will be opened
+after this.
+
+If you want to make sure that your changes are in the swap file use this
+command:
+
+					*:pre* *:preserve* *E313* *E314*
+:pre[serve]		Write all text for the current buffer into its swap
+			file.  The original file is no longer needed for
+			recovery.  This sets a flag in the current buffer.
+			When the '&' flag is present in 'cpoptions' the swap
+			file will not be deleted for this buffer when Vim
+			exits and the buffer is still loaded |cpo-&|.
+
+A Vim swap file can be recognized by the first six characters: "b0VIM ".
+After that comes the version number, e.g., "3.0".
+
+
+Links and symbolic links ~
+
+On Unix it is possible to have two names for the same file.  This can be done
+with hard links and with symbolic links (symlinks).
+
+For hard links Vim does not know the other name of the file.  Therefore, the
+name of the swapfile will be based on the name you used to edit the file.
+There is no check for editing the same file by the other name too, because Vim
+cannot find the other swapfile (except for searching all of your harddisk,
+which would be very slow).
+
+For symbolic links Vim resolves the links to find the name of the actual file.
+The swap file name is based on that name.  Thus it doesn't matter by what name
+you edit the file, the swap file name will normally be the same.  However,
+there are exceptions:
+- When the directory of the actual file is not writable the swapfile is put
+  elsewhere.
+- When the symbolic links somehow create a loop you get an *E773* error
+  message and the unmodified file name will be used.  You won't be able to
+  save your file normally.
+
+==============================================================================
+2. Recovery					*recovery* *E308* *E311*
+
+Basic file recovery is explained in the user manual: |usr_11.txt|.
+
+Another way to do recovery is to start Vim and use the ":recover" command.
+This is easy when you start Vim to edit a file and you get the "ATTENTION:
+Found a swap file ..." message.  In this case the single command ":recover"
+will do the work.  You can also give the name of the file or the swap file to
+the recover command:
+					*:rec* *:recover* *E305* *E306* *E307*
+:rec[over] [file]	Try to recover [file] from the swap file.  If [file]
+			is not given use the file name for the current
+			buffer.  The current contents of the buffer are lost.
+			This command fails if the buffer was modified.
+
+:rec[over]! [file]	Like ":recover", but any changes in the current
+			buffer are lost.
+
+						*E312* *E309* *E310* *E1364*
+Vim has some intelligence about what to do if the swap file is corrupt in
+some way.  If Vim has doubt about what it found, it will give an error
+message and insert lines with "???" in the text.  If you see an error message
+while recovering, search in the file for "???" to see what is wrong.  You may
+want to cut and paste to get the text you need.
+
+The most common remark is "???LINES MISSING".  This means that Vim cannot read
+the text from the original file.  This can happen if the system crashed and
+parts of the original file were not written to disk.
+
+Be sure that the recovery was successful before overwriting the original
+file or deleting the swap file.  It is good practice to write the recovered
+file elsewhere and run 'diff' to find out if the changes you want are in the
+recovered file.  Or use |:DiffOrig|.
+
+Once you are sure the recovery is ok delete the swap file.  Otherwise, you
+will continue to get warning messages that the ".swp" file already exists.
+
+
+
+ENCRYPTION AND THE SWAP FILE				*:recover-crypt*
+
+When the text file is encrypted the swap file is encrypted as well.  This
+makes recovery a bit more complicated.  When recovering from a swap file and
+encryption has been used, you will be asked to enter one or two crypt keys.
+
+If the text file does not exist you will only be asked to enter the crypt key
+for the swap file.
+
+If the text file does exist, it may be encrypted in a different way than the
+swap file.  You will be asked for the crypt key twice:
+
+	Need encryption key for "/tmp/tt" ~
+	Enter encryption key: ****** ~
+	"/tmp/tt" [crypted] 23200L, 522129C ~
+	Using swap file "/tmp/.tt.swp" ~
+	Original file "/tmp/tt" ~
+	Swap file is encrypted: "/tmp/.tt.swp" ~
+	If you entered a new crypt key but did not write the text file, ~
+	enter the new crypt key. ~
+	If you wrote the text file after changing the crypt key press enter ~
+	to use the same key for text file and swap file ~
+	Enter encryption key:  ~
+
+You can be in one of these two situations:
+
+1. The encryption key was not changed, or after changing the key the text file
+   was written.  You will be prompted for the crypt key twice.  The second
+   time you can simply press Enter.  That means the same key is used for the
+   text file and the swap file.
+2. You entered a new encryption key, but did not save the text file.  Vim will
+   then use the new key for the swap file, and the text file will still be
+   encrypted with the old key.  At the second prompt enter the new key.
+
+Note that after recovery the key of the swap file will be used for the text
+file.  Thus if you write the text file, you need to use that new key.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: