diff options
Diffstat (limited to 'runtime/doc/recover.txt')
| -rw-r--r-- | runtime/doc/recover.txt | 238 |
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: |