summaryrefslogtreecommitdiff
path: root/runtime/doc/usr_07.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_07.txt')
-rw-r--r--runtime/doc/usr_07.txt479
1 files changed, 479 insertions, 0 deletions
diff --git a/runtime/doc/usr_07.txt b/runtime/doc/usr_07.txt
new file mode 100644
index 000000000..b41977699
--- /dev/null
+++ b/runtime/doc/usr_07.txt
@@ -0,0 +1,479 @@
+*usr_07.txt* For Vim version 7.0aa. Last change: 2004 Mar 12
+
+ VIM USER MANUAL - by Bram Moolenaar
+
+ Editing more than one file
+
+
+No matter how many files you have, you can edit them without leaving Vim.
+Define a list of files to work on and jump from one to the other. Copy text
+from one file and put it in another one.
+
+|07.1| Edit another file
+|07.2| A list of files
+|07.3| Jumping from file to file
+|07.4| Backup files
+|07.5| Copy text between files
+|07.6| Viewing a file
+|07.7| Changing the file name
+
+ Next chapter: |usr_08.txt| Splitting windows
+ Previous chapter: |usr_06.txt| Using syntax highlighting
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*07.1* Edit another file
+
+So far you had to start Vim for every file you wanted to edit. There is a
+simpler way. To start editing another file, use this command: >
+
+ :edit foo.txt
+
+You can use any file name instead of "foo.txt". Vim will close the current
+file and open the new one. If the current file has unsaved changes, however,
+Vim displays an error message and does not open the new file:
+
+ E37: No write since last change (use ! to override) ~
+
+ Note:
+ Vim puts an error ID at the start of each error message. If you do
+ not understand the message or what caused it, look in the help system
+ for this ID. In this case: >
+
+ :help E37
+
+At this point, you have a number of alternatives. You can write the file
+using this command: >
+
+ :write
+
+Or you can force Vim to discard your changes and edit the new file, using the
+force (!) character: >
+
+ :edit! foo.txt
+
+If you want to edit another file, but not write the changes in the current
+file yet, you can make it hidden: >
+
+ :hide edit foo.txt
+
+The text with changes is still there, but you can't see it. This is further
+explained in section |22.4|: The buffer list.
+
+==============================================================================
+*07.2* A list of files
+
+You can start Vim to edit a sequence of files. For example: >
+
+ vim one.c two.c three.c
+
+This command starts Vim and tells it that you will be editing three files.
+Vim displays just the first file. After you have done your thing in this
+file, to edit the next file you use this command: >
+
+ :next
+
+If you have unsaved changes in the current file, you will get an error
+message and the ":next" will not work. This is the same problem as with
+":edit" mentioned in the previous section. To abandon the changes: >
+
+ :next!
+
+But mostly you want to save the changes and move on to the next file. There
+is a special command for this: >
+
+ :wnext
+
+This does the same as using two separate commands: >
+
+ :write
+ :next
+
+
+WHERE AM I?
+
+To see which file in the argument list you are editing, look in the window
+title. It should show something like "(2 of 3)". This means you are editing
+the second file out of three files.
+ If you want to see the list of files, use this command: >
+
+ :args
+
+This is short for "arguments". The output might look like this:
+
+ one.c [two.c] three.c ~
+
+These are the files you started Vim with. The one you are currently editing,
+"two.c", is in square brackets.
+
+
+MOVING TO OTHER ARGUMENTS
+
+To go back one file: >
+
+ :previous
+
+This is just like the ":next" command, except that it moves in the other
+direction. Again, there is a shortcut command for when you want to write the
+file first: >
+
+ :wprevious
+
+To move to the very last file in the list: >
+
+ :last
+
+And to move back to the first one again: >
+
+ :first
+
+There is no ":wlast" or ":wfirst" command though!
+
+You can use a count for ":next" and ":previous". To skip two files forward: >
+
+ :2next
+
+
+AUTOMATIC WRITING
+
+When moving around the files and making changes, you have to remember to use
+":write". Otherwise you will get an error message. If you are sure you
+always want to write modified files, you can tell Vim to automatically write
+them: >
+
+ :set autowrite
+
+When you are editing a file which you may not want to write, switch it off
+again: >
+
+ :set noautowrite
+
+
+EDITING ANOTHER LIST OF FILES
+
+You can redefine the list of files without the need to exit Vim and start it
+again. Use this command to edit three other files: >
+
+ :args five.c six.c seven.h
+
+Or use a wildcard, like it's used in the shell: >
+
+ :args *.txt
+
+Vim will take you to the first file in the list. Again, if the current file
+has changes, you can either write the file first, or use ":args!" (with !
+added) to abandon the changes.
+
+
+DID YOU EDIT THE LAST FILE?
+ *arglist-quit*
+When you use a list of files, Vim assumes you want to edit them all. To
+protect you from exiting too early, you will get this error when you didn't
+edit the last file in the list yet:
+
+ E173: 46 more files to edit ~
+
+If you really want to exit, just do it again. Then it will work (but not when
+you did other commands in between).
+
+==============================================================================
+*07.3* Jumping from file to file
+
+To quickly jump between two files, press CTRL-^ (on English-US keyboards the ^
+is above the 6 key). Example: >
+
+ :args one.c two.c three.c
+
+You are now in one.c. >
+
+ :next
+
+Now you are in two.c. Now use CTRL-^ to go back to one.c. Another CTRL-^ and
+you are back in two.c. Another CTRL-^ and you are in one.c again. If you now
+do: >
+
+ :next
+
+You are in three.c. Notice that the CTRL-^ command does not change the idea
+of where you are in the list of files. Only commands like ":next" and
+":previous" do that.
+
+The file you were previously editing is called the "alternate" file. When you
+just started Vim CTRL-^ will not work, since there isn't a previous file.
+
+
+PREDEFINED MARKS
+
+After jumping to another file, you can use two predefined marks which are very
+useful: >
+
+ `"
+
+This takes you to the position where the cursor was when you left the file.
+Another mark that is remembered is the position where you made the last
+change: >
+
+ `.
+
+Suppose you are editing the file "one.txt". Somewhere halfway the file you
+use "x" to delete a character. Then you go to the last line with "G" and
+write the file with ":w". You edit several other files, and then use ":edit
+one.txt" to come back to "one.txt". If you now use `" Vim jumps to the last
+line of the file. Using `. takes you to the position where you deleted the
+character. Even when you move around in the file `" and `. will take you to
+the remembered position. At least until you make another change or leave the
+file.
+
+
+FILE MARKS
+
+In chapter 4 was explained how you can place a mark in a file with "mx" and
+jump to that position with "`x". That works within one file. If you edit
+another file and place marks there, these are specific for that file. Thus
+each file has its own set of marks, they are local to the file.
+ So far we were using marks with a lowercase letter. There are also marks
+with an uppercase letter. These are global, they can be used from any file.
+For example suppose that we are editing the file "foo.txt". Go to halfway the
+file ("50%") and place the F mark there (F for foo): >
+
+ 50%mF
+
+Now edit the file "bar.txt" and place the B mark (B for bar) at its last line:
+>
+ GmB
+
+Now you can use the "'F" command to jump back to halfway foo.txt. Or edit yet
+another file, type "'B" and you are at the end of bar.txt again.
+
+The file marks are remembered until they are placed somewhere else. Thus you
+can place the mark, do hours of editing and still be able to jump back to that
+mark.
+ It's often useful to think of a simple connection between the mark letter
+and where it is placed. For example, use the H mark in a header file, M in
+a Makefile and C in a C code file.
+
+To see where a specific mark is, give an argument to the ":marks" command: >
+
+ :marks M
+
+You can also give several arguments: >
+
+ :marks MCP
+
+Don't forget that you can use CTRL-O and CTRL-I to jump to older and newer
+positions without placing marks there.
+
+==============================================================================
+*07.4* Backup files
+
+Usually Vim does not produce a backup file. If you want to have one, all you
+need to do is execute the following command: >
+
+ :set backup
+
+The name of the backup file is the original file with a ~ added to the end.
+If your file is named data.txt, for example, the backup file name is
+data.txt~.
+ If you do not like the fact that the backup files end with ~, you can
+change the extension: >
+
+ :set backupext=.bak
+
+This will use data.txt.bak instead of data.txt~.
+ Another option that matters here is 'backupdir'. It specifies where the
+backup file is written. The default, to write the backup in the same
+directory as the original file, will mostly be the right thing.
+
+ Note:
+ When the 'backup' option isn't set but the 'writebackup' is, Vim will
+ still create a backup file. However, it is deleted as soon as writing
+ the file was completed successfully. This functions as a safety
+ against losing your original file when writing fails in some way (disk
+ full is the most common cause; being hit by lightning might be
+ another, although less common).
+
+
+KEEPING THE ORIGINAL FILE
+
+If you are editing source files, you might want to keep the file before you
+make any changes. But the backup file will be overwritten each time you write
+the file. Thus it only contains the previous version, not the first one.
+ To make Vim keep the original file, set the 'patchmode' option. This
+specifies the extension used for the first backup of a changed file. Usually
+you would do this: >
+
+ :set patchmode=.orig
+
+When you now edit the file data.txt for the first time, make changes and write
+the file, Vim will keep a copy of the unchanged file under the name
+"data.txt.orig".
+ If you make further changes to the file, Vim will notice that
+"data.txt.orig" already exists and leave it alone. Further backup files will
+then be called "data.txt~" (or whatever you specified with 'backupext').
+ If you leave 'patchmode' empty (that is the default), the original file
+will not be kept.
+
+==============================================================================
+*07.5* Copy text between files
+
+This explains how to copy text from one file to another. Let's start with a
+simple example. Edit the file that contains the text you want to copy. Move
+the cursor to the start of the text and press "v". This starts Visual mode.
+Now move the cursor to the end of the text and press "y". This yanks (copies)
+the selected text.
+ To copy the above paragraph, you would do: >
+
+ :edit thisfile
+ /This
+ vjjjj$y
+
+Now edit the file you want to put the text in. Move the cursor to the
+character where you want the text to appear after. Use "p" to put the text
+there. >
+ :edit otherfile
+ /There
+ p
+
+Of course you can use many other commands to yank the text. For example, to
+select whole lines start Visual mode with "V". Or use CTRL-V to select a
+rectangular block. Or use "Y" to yank a single line, "yaw" to yank-a-word,
+etc.
+ The "p" command puts the text after the cursor. Use "P" to put the text
+before the cursor. Notice that Vim remembers if you yanked a whole line or a
+block, and puts it back that way.
+
+
+USING REGISTERS
+
+When you want to copy several pieces of text from one file to another, having
+to switch between the files and writing the target file takes a lot of time.
+To avoid this, copy each piece of text to its own register.
+ A register is a place where Vim stores text. Here we will use the
+registers named a to z (later you will find out there are others). Let's copy
+a sentence to the f register (f for First): >
+
+ "fyas
+
+The "yas" command yanks a sentence like before. It's the "f that tells Vim
+the text should be place in the f register. This must come just before the
+yank command.
+ Now yank three whole lines to the l register (l for line): >
+
+ "l3Y
+
+The count could be before the "l just as well. To yank a block of text to the
+b (for block) register: >
+
+ CTRL-Vjjww"by
+
+Notice that the register specification "b is just before the "y" command.
+This is required. If you would have put it before the "w" command, it would
+not have worked.
+ Now you have three pieces of text in the f, l and b registers. Edit
+another file, move around and place the text where you want it: >
+
+ "fp
+
+Again, the register specification "f comes before the "p" command.
+ You can put the registers in any order. And the text stays in the register
+until you yank something else into it. Thus you can put it as many times as
+you like.
+
+When you delete text, you can also specify a register. Use this to move
+several pieces of text around. For example, to delete-a-word and write it in
+the w register: >
+
+ "wdaw
+
+Again, the register specification comes before the delete command "d".
+
+
+APPENDING TO A FILE
+
+When collecting lines of text into one file, you can use this command: >
+
+ :write >> logfile
+
+This will write the text of the current file to the end of "logfile". Thus it
+is appended. This avoids that you have to copy the lines, edit the log file
+and put them there. Thus you save two steps. But you can only append to the
+end of a file.
+ To append only a few lines, select them in Visual mode before typing
+":write". In chapter 10 you will learn other ways to select a range of lines.
+
+==============================================================================
+*07.6* Viewing a file
+
+Sometimes you only want to see what a file contains, without the intention to
+ever write it back. There is the risk that you type ":w" without thinking and
+overwrite the original file anyway. To avoid this, edit the file read-only.
+ To start Vim in readonly mode, use this command: >
+
+ vim -R file
+
+On Unix this command should do the same thing: >
+
+ view file
+
+You are now editing "file" in read-only mode. When you try using ":w" you
+will get an error message and the file won't be written.
+ When you try to make a change to the file Vim will give you a warning:
+
+ W10: Warning: Changing a readonly file ~
+
+The change will be done though. This allows for formatting the file, for
+example, to be able to read it easily.
+ If you make changes to a file and forgot that it was read-only, you can
+still write it. Add the ! to the write command to force writing.
+
+If you really want to forbid making changes in a file, do this: >
+
+ vim -M file
+
+Now every attempt to change the text will fail. The help files are like this,
+for example. If you try to make a change you get this error message:
+
+ E21: Cannot make changes, 'modifiable' is off ~
+
+You could use the -M argument to setup Vim to work in a viewer mode. This is
+only voluntary though, since these commands will remove the protection: >
+
+ :set modifiable
+ :set write
+
+==============================================================================
+*07.7* Changing the file name
+
+A clever way to start editing a new file is by using an existing file that
+contains most of what you need. For example, you start writing a new program
+to move a file. You know that you already have a program that copies a file,
+thus you start with: >
+
+ :edit copy.c
+
+You can delete the stuff you don't need. Now you need to save the file under
+a new name. The ":saveas" command can be used for this: >
+
+ :saveas move.c
+
+Vim will write the file under the given name, and edit that file. Thus the
+next time you do ":write", it will write "move.c". "copy.c" remains
+unmodified.
+ When you want to change the name of the file you are editing, but don't
+want to write the file, you can use this command: >
+
+ :file move.c
+
+Vim will mark the file as "not edited". This means that Vim knows this is not
+the file you started editing. When you try to write the file, you might get
+this message:
+
+ E13: File exists (use ! to override) ~
+
+This protects you from accidentally overwriting another file.
+
+==============================================================================
+
+Next chapter: |usr_08.txt| Splitting windows
+
+Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: