share/vim/vim58/doc/recover.txt

   1 *recover.txt*   For Vim version 5.8.  Last change: 2000 Dec 21
   2
   3
   4                   VIM REFERENCE MANUAL    by Bram Moolenaar
   5
   6
   7 Recovery after a crash                                  *crash-recovery*
   8
   9 You have spent several hours typing in that text that has to be finished
  10 next morning, and then disaster strikes: Your computer crashes.
  11
  12                         DON'T PANIC!
  13
  14 You can recover most of your changes from the files that Vim uses to store
  15 the contents of the file.  Mostly you can recover your work with one command:
  16         vim -r filename
  17
  18 1. The swap file        |swap-file|
  19 2. Recovery             |recovery|
  20
  21 ==============================================================================
  22 1. The swap file                                        *swap-file*
  23
  24 Vim stores the things you changed in a swap file.  Using the original file
  25 you started from plus the swap file you can mostly recover your work.
  26
  27 You can see the name of the current swap file being used with the command:
  28
  29         :sw[apname]                                     *:sw* *:swapname*
  30
  31 The name of the swap file is normally the same as the file you are editing,
  32 with the extension ".swp".
  33 - On Unix, a '.' is prepended to swap file names in the same directory as the
  34   edited file.  This avoids that the swap file shows up in a directory
  35   listing.
  36 - On MS-DOS machines and when the 'shortname' option is on, any '.' in the
  37   original file name is replaced with '_'.
  38 - If this file already exists (e.g., when you are recovering from a crash) a
  39   warning is given and another extension is used, ".swo", ".swn", etc.
  40 - An existing file will never be overwritten.
  41 - The swap file is deleted as soon as Vim stops editing the file.
  42
  43 Technical: The replacement of '.' with '_' is done to avoid problems with
  44            MS-DOS compatible filesystems (e.g., crossdos, multidos).  If Vim
  45            is able to detect that the file is on an MS-DOS-like filesystem, a
  46            flag is set that has the same effect as the 'shortname' option.
  47            This flag is reset when you start editing another file.
  48
  49            If the ".swp" file name already exists, the last character is
  50            decremented until there is no file with that name or ".swa" is
  51            reached.  In the last case, no swap file is created.
  52
  53 By setting the 'directory' option you can place the swap file in another place
  54 than where the edited file is.
  55 Advantages:
  56 - You will not pollute the directories with ".swp" files.
  57 - When the 'directory' is on another partition, reduce the risk of damaging
  58   the file system where the file is (in a crash).
  59 Disadvantages:
  60 - You can get name collisions from files with the same name but in different
  61   directories (although Vim tries to avoid that by comparing the path name).
  62   This will result in bogus ATTENTION warning messages.
  63 - When you use your home directory, and somebody else tries to edit the same
  64   file, he will not see your swap file and will not get the ATTENTION waring
  65   message.
  66 On the Amiga you can also use a recoverable ram disk, but there is no 100%
  67 guarantee that this works.  Putting swap files in a normal ram disk (like RAM:
  68 on the Amiga) or in a place that is cleared when rebooting (like /tmp on Unix)
  69 makes no sense, you will lose the swap file in a crash.
  70
  71 If you want to put swap files in a fixed place, put a command resembling the
  72 following ones in your .vimrc:
  73         :set dir=dh2:tmp        (for Amiga)
  74         :set dir=~/tmp          (for Unix)
  75         :set dir=c:\\tmp        (for MS-DOS and Win32)
  76 This is also very handy when editing files on floppy.  Of course you will have
  77 to create that "tmp" directory for this to work!
  78
  79 For read-only files, a swap file is not used.  Unless the file is big, causing
  80 the amount of memory used to be higher than given with 'maxmem' or
  81 'maxmemtot'.  And when making a change to a read-only file, the swap file is
  82 created anyway.
  83
  84 The 'swapfile' option can be reset to avoid creating a swapfile.
  85
  86
  87 Detecting an existing swap file ~
  88                                                         *ATTENTION*
  89 When starting to edit a file, Vim checks if a swap file already exists for
  90 that file.  If there is one, you will get a message indicating that something
  91 is wrong:
  92
  93         ATTENTION
  94         Found a swap file by the name "../doc/help.txt.swp"
  95                      dated: Thu May 16 11:46:31 1996
  96                  file name: ~mool/vim/vim/doc/help.txt
  97                  host name: Kibaale
  98                  user name: mool
  99                 process ID: 211 (still running)
 100         While opening file "../doc/help.txt"
 101                      dated: Wed May 15 21:38:40 1996
 102
 103 You are to take one of four actions:
 104
 105 1. Quit editing this file, because another edit session is active on this
 106    file.  Continuing to edit will result in two versions of the same file.
 107    The one that is written last will overwrite the other one, resulting in
 108    loss of changes.  The text "(still running)" indicates that the process
 109    editing this file runs on the same computer (Unix only).  When working over
 110    a network you will not see this message, because the process will be
 111    running on another computer.
 112 2. Proceed with caution.  Making changes to the file is likely to cause
 113    trouble.  If you are only viewing a file it should be OK.
 114 3. Recover a previously crashed edit session.  See below |recovery|.
 115 4. Delete the swap file, if you don't want to recover the file.
 116
 117 If you really don't want to see this message, you can add the 'A' flag to the
 118 'shortmess' option.  But it's very unusual that you need this.
 119
 120 If dialogs are supported you will be asked to select one of five choices:
 121
 122 > Swap file already exists!
 123 > [O]pen Read-Only, (E)dit anyway, (R)ecover, (Q)uit, (D)elete it:
 124
 125 O  Open the file readonly.  Use this when you just want to view the file and
 126    don't need to recover it.
 127 E  Edit the file anyway.  Use this with caution!
 128 R  Recover the file from the swap file.  Use this if you know that the swap
 129    file contains changes that you want to recover.  See |recovery|.
 130 Q  When just starting Vim: Quit Vim.  When starting Vim with files in several
 131    windows, Vim quits only if there is a swap file for the first one.  When
 132    using an edit command: Don't load the file, go back to the previously
 133    edited file.
 134 D  Delete the swap file.  Use this when you are sure you no longer need it.
 135    On Unix this choice is only offered when the process that created the swap
 136    file does not seem to be running.
 137
 138 Vim cannot always detect that a swap file already exists for a file.  This is
 139 the case when the other edit session puts the swap files in another
 140 directory or when the path name for the file is different when editing it on
 141 different machines.
 142
 143
 144 Updating the swapfile ~
 145
 146 The swap file is updated after typing 200 characters or when you have not
 147 typed anything for four seconds.  This only happens if the buffer was
 148 changed, not when you only moved around.  The reason why it is not kept up to
 149 date all the time is that this would slow down normal work too much.  You can
 150 change the 200 character count with the 'updatecount' option.  You can set
 151 the time with the 'updatetime' option.  The time is given in milliseconds.
 152 After writing to the swap file Vim syncs the file to disk.  This takes some
 153 time, especially on busy Unix systems.  If you don't want this you can set the
 154 'swapsync' option to an empty string.  The risk of losing work becomes bigger
 155 though.  On some non-Unix systems (MS-DOS, Amiga) the swap file won't be
 156 written at all.
 157
 158 If the writing to the swap file is not wanted, it can be switched off by
 159 setting the 'updatecount' option to 0.  The same is done when starting Vim
 160 with the "-n" option.  Writing can be switched back on by setting the
 161 'updatecount' option to non-zero.  Swap files will be created for all buffers
 162 when doing this.  But when setting 'updatecount' to zero, the existing swap
 163 files will not be removed, it will only affect files that will be opened
 164 after this.
 165
 166 If you want to make sure that your changes are in the swap file use this
 167 command:
 168
 169                                                         *:pre* *:preserve*
 170 :pre[serve]             Write all text for all buffers into swap file.  The
 171                         original file is no longer needed for recovery.  {Vi:
 172                         emergency exit}
 173
 174 A Vim swap file can be recognized by the first six characters: "b0VIM ".
 175 After that comes the version number, e.g., "3.0".
 176
 177 ==============================================================================
 178 2. Recovery                                             *recovery*
 179
 180 In most cases recovery is quite easy: Start Vim on the same file you were
 181 editing when the crash happened, with the "-r" option added.  Vim will read
 182 the ".swp" file and may read bits and pieces of the original file.
 183
 184 Example:
 185 >       vim -r help.txt
 186
 187 If you were editing without a file name, give an empty string as argument:
 188 >       vim -r ""
 189
 190 If there are several swap files that look they may be the one you want to
 191 use, a list is given of these swap files and you are requested to enter the
 192 number of the one you want to use.  In case you don't know which one to use,
 193 just try them one by one and check the resulting files if they are what you
 194 expected.
 195
 196 If you know which swap file needs to be used, you can recover by giving the
 197 swap file name.  Vim will then find out the name of the original file from
 198 the swap file.
 199
 200 Example:
 201 >       Vim -r .help.txt.swo
 202
 203 This is also handy when the swap file is in another directory than expected.
 204 If this still does not work, see what file names Vim reports and rename the
 205 files accordingly.  Check the 'directory' option to see where Vim may have
 206 put the swap file.
 207
 208 Note: Vim tries to find the swap file by searching the directories in the
 209 'dir' option, looking for files that match "filename.sw?".  If wildcard
 210 expansion doesn't work (e.g., when the 'shell' option is invalid), Vim does a
 211 desparate try to find the file "filename.swp".  If that fails too, you will
 212 have to give the name of the swapfile itself to be able to recover the file.
 213
 214 Another way to do recovery is to start Vim and use the ":recover" command.
 215 This is easy when you start Vim to edit a file and you get the "ATTENTION:
 216 Found a swap file ..." message.  In this case the single command ":recover"
 217 will do the work.  You can also give the name of the file or the swap file to
 218 the recover command:
 219                                                         *:rec* *:recover*
 220 :rec[over] [file]       Try to recover [file] from the swap file.  If [file]
 221                         is not given use the file name for the current
 222                         buffer.  The current contents of the buffer are lost.
 223                         This command fails if the buffer was modified.
 224
 225 :rec[over]! [file]      Like ":recover", but any changes in the current
 226                         buffer are lost.
 227
 228 Vim has some intelligence about what to do if the swap file is corrupt in
 229 some way.  If Vim has doubt about what it found, it will give an error
 230 message and insert lines with "???" in the text.  If you see an error message
 231 while recovering, search in the file for "???" to see what is wrong.  You may
 232 want to cut and paste to get the text you need.
 233
 234 Be sure that the recovery was successful before overwriting the original
 235 file or deleting the swap file.  It is good practice to write the recovered
 236 file elsewhere and run 'diff' to find out if the changes you want are in the
 237 recovered file.
 238
 239 Once you are sure the recovery is ok delete the swap file.  Otherwise, you
 240 will continue to get warning messages that the ".swp" file already exists.
 241
 242 {Vi: recovers in another way and sends mail if there is something to recover}
 243
 244  vim:tw=78:ts=8:sw=8: