@c This is part of the Emacs manual.@c Copyright (C) 1985,86,87,93,94,95,97,00,2001 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@iftex@chapter Killing and Moving Text @dfn{Killing} means erasing text and copying it into the @dfn{killring}, from which it can be retrieved by @dfn{yanking} it. Some systemsuse the terms ``cutting'' and ``pasting'' for these operations. The most common way of moving or copying text within Emacs is to kill itand later yank it elsewhere in one or more places. This is very safebecause Emacs remembers several recent kills, not just the last one. Itis versatile, because the many commands for killing syntactic units canalso be used for moving those units. But there are other ways ofcopying text for special purposes. Emacs has only one kill ring for all buffers, so you can kill text inone buffer and yank it in another buffer.@end iftex@node Killing, Yanking, Mark, Top@section Deletion and Killing@cindex killing text@cindex cutting text@cindex deletion Most commands which erase text from the buffer save it in the killring so that you can move or copy it to other parts of the buffer.These commands are known as @dfn{kill} commands. The rest of thecommands that erase text do not save it in the kill ring; they are knownas @dfn{delete} commands. (This distinction is made only for erasure oftext in the buffer.) If you do a kill or delete command by mistake, youcan use the @kbd{C-x u} (@code{undo}) command to undo it(@pxref{Undo}).@vindex kill-read-only-ok@cindex read-only text, killing You cannot kill read-only text, since such text does not allow anykind of modification. But some users like to use the kill commands tocopy read-only text into the kill ring, without actually changing it.If you set the variable @code{kill-read-only-ok} to a non-@code{nil}value, the kill commands work specially in a read-only buffer: theymove over text, and copy it to the kill ring, without actuallydeleting it from the buffer. When this happens, a message in the echoarea tells you what is happening. The delete commands include @kbd{C-d} (@code{delete-char}) and@key{DEL} (@code{delete-backward-char}), which delete only onecharacter at a time, and those commands that delete only spaces ornewlines. Commands that can destroy significant amounts of nontrivialdata generally do a kill operation instead. The commands' names andindividual descriptions use the words @samp{kill} and @samp{delete} tosay which kind of operation they perform.@cindex Delete Selection mode@cindex mode, Delete Selection@findex delete-selection-mode Many window systems follow the convention that insertion while textis selected deletes the selected text. You can make Emacs behave thisway by enabling Delete Selection mode, with @kbd{M-xdelete-selection-mode}, or using Custom. Another effect of this modeis that @key{DEL}, @kbd{C-d} and some other keys, when a selectionexists, will kill the whole selection. It also enables Transient Markmode (@pxref{Transient Mark}).@menu* Deletion:: Commands for deleting small amounts of text and blank areas.* Killing by Lines:: How to kill entire lines of text at one time.* Other Kill Commands:: Commands to kill large regions of text and syntactic units such as words and sentences. @end menu@need 1500@node Deletion@subsection Deletion@findex delete-backward-char@findex delete-char Deletion means erasing text and not saving it in the kill ring. Forthe most part, the Emacs commands that delete text are those thaterase just one character or only whitespace.@table @kbd@item C-d@itemx @key{Delete}Delete next character (@code{delete-char}). If your keyboard has a@key{Delete} function key (usually located in the edit keypad), Emacsbinds it to @code{delete-char} as well.@item @key{DEL}@itemx @key{BS}Delete previous character (@code{delete-backward-char}). Some keyboardsrefer to this key as a ``backspace key'' and label it with a left arrow.@item M-\Delete spaces and tabs around point (@code{delete-horizontal-space}).@item M-@key{SPC}Delete spaces and tabs around point, leaving one space(@code{just-one-space}).@item C-x C-oDelete blank lines around the current line (@code{delete-blank-lines}).@item M-^Join two lines by deleting the intervening newline, along with anyindentation following it (@code{delete-indentation}).@end table@kindex DEL@kindex C-d The most basic delete commands are @kbd{C-d} (@code{delete-char}) and@key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes thecharacter after point, the one the cursor is ``on top of.'' Thisdoesn't move point. @key{DEL} deletes the character before the cursor,and moves point back. You can delete newlines like any other charactersin the buffer; deleting a newline joins two lines. Actually, @kbd{C-d}and @key{DEL} aren't always delete commands; when given arguments, theykill instead, since they can erase more than one character this way.@kindex BACKSPACE@kindex BS@kindex DELETE Every keyboard has a large key, labeled @key{DEL}, @key{BACKSPACE},@key{BS} or @key{DELETE}, which is a short distance above the@key{RET} or @key{ENTER} key and is normally used for erasing what youhave typed. Regardless of the actual name on the key, in Emacs it isequivalent to @key{DEL}---or it should be. Many keyboards (including standard PC keyboards) have a@key{BACKSPACE} key a short ways above @key{RET} or @key{ENTER}, and a@key{DELETE} key elsewhere. In that case, the @key{BACKSPACE} key is@key{DEL}, and the @key{DELETE} key is equivalent to @kbd{C-d}---or itshould be. Why do we say ``or it should be''? When Emacs starts up using awindow system, it determines automatically which key or keys should beequivalent to @key{DEL}. As a result, @key{BACKSPACE} and/or @key{DELETE}keys normally do the right things. But in some unusual cases Emacsgets the wrong information from the system. If these keys don't dowhat they ought to do, you need to tell Emacs which key to use for@key{DEL}. @xref{DEL Does Not Delete}, for how to do this.@findex normal-erase-is-backspace-mode On most text-only terminals, Emacs cannot tell which keys thekeyboard really has, so it follows a uniform plan which may or may notfit your keyboard. The uniform plan is that the ASCII @key{DEL}character deletes, and the ASCII @key{BS} (backspace) character asksfor help (it is the same as @kbd{C-h}). If this is not right for yourkeyboard, such as if you find that the key which ought to delete backwardsenters Help instead, see @ref{DEL Does Not Delete}.@kindex M-\@findex delete-horizontal-space@kindex M-SPC@findex just-one-space The other delete commands are those which delete only whitespacecharacters: spaces, tabs and newlines. @kbd{M-\}(@code{delete-horizontal-space}) deletes all the spaces and tabcharacters before and after point. @kbd{M-@key{SPC}}(@code{just-one-space}) does likewise but leaves a single space afterpoint, regardless of the number of spaces that existed previously (evenif there were none before). @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank linesafter the current line. If the current line is blank, it deletes allblank lines preceding the current line as well (leaving one blank line,the current line). @kbd{M-^} (@code{delete-indentation}) joins the current line and theprevious line, by deleting a newline and all surrounding spaces, usuallyleaving a single space. @xref{Indentation,M-^}.@node Killing by Lines@subsection Killing by Lines@table @kbd@item C-kKill rest of line or one or more lines (@code{kill-line}).@end table@kindex C-k@findex kill-line The simplest kill command is @kbd{C-k}. If given at the beginning ofa line, it kills all the text on the line, leaving it blank. When usedon a blank line, it kills the whole line including its newline. To killan entire non-blank line, go to the beginning and type @kbd{C-k} twice. More generally, @kbd{C-k} kills from point up to the end of the line,unless it is at the end of a line. In that case it kills the newlinefollowing point, thus merging the next line into the current one.Spaces and tabs that you can't see at the end of the line are ignoredwhen deciding which case applies, so if point appears to be at the endof the line, you can be sure @kbd{C-k} will kill the newline. When @kbd{C-k} is given a positive argument, it kills that many linesand the newlines that follow them (however, text on the current linebefore point is not killed). With a negative argument @minus{}@var{n}, itkills @var{n} lines preceding the current line (together with the texton the current line before point). Thus, @kbd{C-u - 2 C-k} at the frontof a line kills the two previous lines. @kbd{C-k} with an argument of zero kills the text before point on thecurrent line.@vindex kill-whole-line If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} atthe very beginning of a line kills the entire line including thefollowing newline. This variable is normally @code{nil}.@node Other Kill Commands@subsection Other Kill Commands@findex kill-region@kindex C-w@table @kbd@item C-wKill region (from point to the mark) (@code{kill-region}).@item M-dKill word (@code{kill-word}). @xref{Words}.@item M-@key{DEL}Kill word backwards (@code{backward-kill-word}).@item C-x @key{DEL}Kill back to beginning of sentence (@code{backward-kill-sentence}).@xref{Sentences}.@item M-kKill to end of sentence (@code{kill-sentence}).@item C-M-kKill the following balanced expression (@code{kill-sexp}). @xref{Expressions}.@item M-z @var{char}Kill through the next occurrence of @var{char} (@code{zap-to-char}).@end table A kill command which is very general is @kbd{C-w}(@code{kill-region}), which kills everything between point and themark. With this command, you can kill any contiguous sequence ofcharacters, if you first set the region around them.@kindex M-z@findex zap-to-char A convenient way of killing is combined with searching: @kbd{M-z}(@code{zap-to-char}) reads a character and kills from point up to (andincluding) the next occurrence of that character in the buffer. Anumeric argument acts as a repeat count. A negative argument means tosearch backward and kill text before point. Other syntactic units can be killed: words, with @kbd{M-@key{DEL}}and @kbd{M-d} (@pxref{Words}); balanced expressions, with @kbd{C-M-k}(@pxref{Expressions}); and sentences, with @kbd{C-x @key{DEL}} and@kbd{M-k} (@pxref{Sentences}).@refill You can use kill commands in read-only buffers. They don't actuallychange the buffer, and they beep to warn you of that, but they do copythe text you tried to kill into the kill ring, so you can yank it intoother buffers. Most of the kill commands move point across the textthey copy in this way, so that successive kill commands build up asingle kill ring entry as usual.@node Yanking, Accumulating Text, Killing, Top@section Yanking@cindex moving text@cindex copying text@cindex kill ring@cindex yanking@cindex pasting @dfn{Yanking} means reinserting text previously killed. This is whatsome systems call ``pasting.'' The usual way to move or copy text is tokill it and then yank it elsewhere one or more times.@table @kbd@item C-yYank last killed text (@code{yank}).@item M-yReplace text just yanked with an earlier batch of killed text(@code{yank-pop}).@item M-wSave region as last killed text without actually killing it(@code{kill-ring-save}).@item C-M-wAppend next kill to last batch of killed text (@code{append-next-kill}).@end table@menu* Kill Ring:: Where killed text is stored. Basic yanking.* Appending Kills:: Several kills in a row all yank together.* Earlier Kills:: Yanking something killed some time ago.@end menu@node Kill Ring@subsection The Kill Ring All killed text is recorded in the @dfn{kill ring}, a list of blocks oftext that have been killed. There is only one kill ring, shared by allbuffers, so you can kill text in one buffer and yank it in another buffer.This is the usual way to move text from one file to another.(@xref{Accumulating Text}, for some other ways.)@kindex C-y@findex yank The command @kbd{C-y} (@code{yank}) reinserts the text of the most recentkill. It leaves the cursor at the end of the text. It sets the mark atthe beginning of the text. @xref{Mark}. @kbd{C-u C-y} leaves the cursor in front of the text, and sets themark after it. This happens only if the argument is specified with justa @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u}and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}).@kindex M-w@findex kill-ring-save To copy a block of text, you can use @kbd{M-w}(@code{kill-ring-save}), which copies the region into the kill ringwithout removing it from the buffer. This is approximately equivalentto @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does notalter the undo history and does not temporarily change the screen.@node Appending Kills@subsection Appending Kills@cindex appending kills in the ring@cindex television Normally, each kill command pushes a new entry onto the kill ring.However, two or more kill commands in a row combine their text into asingle entry, so that a single @kbd{C-y} yanks all the text as a unit,just as it was before it was killed. Thus, if you want to yank text as a unit, you need not kill all of itwith one command; you can keep killing line after line, or word afterword, until you have killed it all, and you can still get it all back atonce. Commands that kill forward from point add onto the end of the previouskilled text. Commands that kill backward from point add text onto thebeginning. This way, any sequence of mixed forward and backward killcommands puts all the killed text into one entry without rearrangement.Numeric arguments do not break the sequence of appending kills. Forexample, suppose the buffer contains this text:@exampleThis is a line @point{}of sample text.@end example@noindentwith point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-dM-@key{DEL}}, killing alternately forward and backward, you end up with@samp{a line of sample} as one entry in the kill ring, and @samp{Thisis@ @ text.} in the buffer. (Note the double space between @samp{is}and @samp{text}, which you can clean up with @kbd{M-@key{SPC}} or@kbd{M-q}.) Another way to kill the same text is to move back two words with@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}.This produces exactly the same results in the buffer and in the killring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all goingbackward; once again, the result is the same. The text in the kill ringentry always has the same order that it had in the buffer before youkilled it.@kindex C-M-w@findex append-next-kill If a kill command is separated from the last kill command by othercommands (not just numeric arguments), it starts a new entry on the killring. But you can force it to append by first typing the command@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w}tells the following command, if it is a kill command, to append the textit kills to the last killed text, instead of starting a new entry. With@kbd{C-M-w}, you can kill several separated pieces of text andaccumulate them to be yanked back in one place.@refill A kill command following @kbd{M-w} does not append to the text that@kbd{M-w} copied into the kill ring.@node Earlier Kills@subsection Yanking Earlier Kills@cindex yanking previous kills@kindex M-y@findex yank-pop To recover killed text that is no longer the most recent kill, use the@kbd{M-y} command (@code{yank-pop}). It takes the text previouslyyanked and replaces it with the text from an earlier kill. So, torecover the text of the next-to-the-last kill, first use @kbd{C-y} toyank the last kill, and then use @kbd{M-y} to replace it with theprevious kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another@kbd{M-y}. You can understand @kbd{M-y} in terms of a ``last yank'' pointer whichpoints at an entry in the kill ring. Each time you kill, the ``lastyank'' pointer moves to the newly made entry at the front of the ring.@kbd{C-y} yanks the entry which the ``last yank'' pointer points to.@kbd{M-y} moves the ``last yank'' pointer to a different entry, and thetext in the buffer changes to match. Enough @kbd{M-y} commands can movethe pointer to any entry in the ring, so you can get any entry into thebuffer. Eventually the pointer reaches the end of the ring; the next@kbd{M-y} loops back around to the first entry again. @kbd{M-y} moves the ``last yank'' pointer around the ring, but it doesnot change the order of the entries in the ring, which always runs fromthe most recent kill at the front to the oldest one still remembered. @kbd{M-y} can take a numeric argument, which tells it how many entriesto advance the ``last yank'' pointer by. A negative argument moves thepointer toward the front of the ring; from the front of the ring, itmoves ``around'' to the last entry and continues forward from there. Once the text you are looking for is brought into the buffer, you canstop doing @kbd{M-y} commands and it will stay there. It's just a copyof the kill ring entry, so editing it in the buffer does not changewhat's in the ring. As long as no new killing is done, the ``lastyank'' pointer remains at the same place in the kill ring, so repeating@kbd{C-y} will yank another copy of the same previous kill. If you know how many @kbd{M-y} commands it would take to find thetext you want, you can yank that text in one step using @kbd{C-y} witha numeric argument. @kbd{C-y} with an argument restores the text fromthe specified kill ring entry, counting back from the most recent as1. Thus, @kbd{C-u 2 C-y} gets the next-to-the-last block of killedtext---it is equivalent to @kbd{C-y M-y}. @kbd{C-y} with a numericargument starts counting from the ``last yank'' pointer, and sets the``last yank'' pointer to the entry that it yanks.@vindex kill-ring-max The length of the kill ring is controlled by the variable@code{kill-ring-max}; no more than that many blocks of killed text aresaved.@vindex kill-ring The actual contents of the kill ring are stored in a variable named@code{kill-ring}; you can view the entire contents of the kill ring withthe command @kbd{C-h v kill-ring}.@node Accumulating Text, Rectangles, Yanking, Top@section Accumulating Text@findex append-to-buffer@findex prepend-to-buffer@findex copy-to-buffer@findex append-to-file@cindex accumulating scattered text Usually we copy or move text by killing it and yanking it, but thereare other methods convenient for copying one block of text in manyplaces, or for copying many scattered blocks of text into one place. Tocopy one block to many places, store it in a register(@pxref{Registers}). Here we describe the commands to accumulatescattered pieces of text into a buffer or into a file.@table @kbd@item M-x append-to-bufferAppend region to the contents of a specified buffer.@item M-x prepend-to-bufferPrepend region to the contents of a specified buffer.@item M-x copy-to-bufferCopy region into a specified buffer, deleting that buffer's old contents.@item M-x insert-bufferInsert the contents of a specified buffer into current buffer at point.@item M-x append-to-fileAppend region to the contents of a specified file, at the end.@end table To accumulate text into a buffer, use @kbd{M-x append-to-buffer}.This reads a buffer name, then inserts a copy of the region into thebuffer specified. If you specify a nonexistent buffer,@code{append-to-buffer} creates the buffer. The text is insertedwherever point is in that buffer. If you have been using the buffer forediting, the copied text goes into the middle of the text of the buffer,starting from wherever point happens to be at that moment. Point in that buffer is left at the end of the copied text, sosuccessive uses of @code{append-to-buffer} accumulate the text in thespecified buffer in the same order as they were copied. Strictlyspeaking, @code{append-to-buffer} does not always append to the textalready in the buffer---it appends only if point in that buffer is at the end.However, if @code{append-to-buffer} is the only command you use to altera buffer, then point is always at the end. @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer}except that point in the other buffer is left before the copied text, sosuccessive prependings add text in reverse order. @kbd{M-xcopy-to-buffer} is similar, except that any existing text in the otherbuffer is deleted, so the buffer is left containing just the text newlycopied into it. To retrieve the accumulated text from another buffer, use thecommand @kbd{M-x insert-buffer}; this too takes @var{buffername} as anargument. It inserts a copy of the whole text in buffer@var{buffername} into the current buffer at point, and sets the markafter the inserted text. Alternatively, you can select the otherbuffer for editing, then copy text from it by killing.@xref{Buffers}, for background information on buffers. Instead of accumulating text within Emacs, in a buffer, you can appendtext directly into a file with @kbd{M-x append-to-file}, which takes@var{filename} as an argument. It adds the text of the region to the endof the specified file. The file is changed immediately on disk. You should use @code{append-to-file} only with files that are@emph{not} being visited in Emacs. Using it on a file that you areediting in Emacs would change the file behind Emacs's back, whichcan lead to losing some of your editing.@node Rectangles, Registers, Accumulating Text, Top@section Rectangles@cindex rectangle@cindex columns (and rectangles)@cindex killing rectangular areas of text The rectangle commands operate on rectangular areas of the text: allthe characters between a certain pair of columns, in a certain range oflines. Commands are provided to kill rectangles, yank killed rectangles,clear them out, fill them with blanks or text, or delete them. Rectanglecommands are useful with text in multicolumn formats, and for changingtext into or out of such formats. When you must specify a rectangle for a command to work on, you do itby putting the mark at one corner and point at the opposite corner. Therectangle thus specified is called the @dfn{region-rectangle} becauseyou control it in much the same way as the region is controlled. Butremember that a given combination of point and mark values can beinterpreted either as a region or as a rectangle, depending on thecommand that uses them. If point and the mark are in the same column, the rectangle theydelimit is empty. If they are in the same line, the rectangle is oneline high. This asymmetry between lines and columns comes aboutbecause point (and likewise the mark) is between two columns, but withina line.@table @kbd@item C-x r kKill the text of the region-rectangle, saving its contents as the ``last killed rectangle'' (@code{kill-rectangle}).@item C-x r dDelete the text of the region-rectangle (@code{delete-rectangle}).@item C-x r yYank the last killed rectangle with its upper left corner at point(@code{yank-rectangle}).@item C-x r oInsert blank space to fill the space of the region-rectangle(@code{open-rectangle}). This pushes the previous contents of theregion-rectangle rightward.@item M-x clear-rectangleClear the region-rectangle by replacing its contents with spaces.@item M-x delete-whitespace-rectangleDelete whitespace in each of the lines on the specified rectangle,starting from the left edge column of the rectangle.@item C-x r t @var{string} @key{RET}Replace rectangle contents with @var{string} on each line.(@code{string-rectangle}).@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET}Insert @var{string} on each line of the rectangle.@end table The rectangle operations fall into two classes: commands fordeleting and inserting rectangles, and commands for blank rectangles.@kindex C-x r k@kindex C-x r d@findex kill-rectangle@findex delete-rectangle There are two ways to get rid of the text in a rectangle: you candiscard the text (delete it) or save it as the ``last killed''rectangle. The commands for these two ways are @kbd{C-x r d}(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). Ineither case, the portion of each line that falls inside the rectangle'sboundaries is deleted, causing any following text on the line tomove left into the gap. Note that ``killing'' a rectangle is not killing in the usual sense; therectangle is not stored in the kill ring, but in a special place thatcan only record the most recent rectangle killed. This is because yankinga rectangle is so different from yanking linear text that different yankcommands have to be used and yank-popping is hard to make sense of.@kindex C-x r y@findex yank-rectangle To yank the last killed rectangle, type @kbd{C-x r y}(@code{yank-rectangle}). Yanking a rectangle is the opposite of killingone. Point specifies where to put the rectangle's upper left corner.The rectangle's first line is inserted there, the rectangle's secondline is inserted at the same horizontal position, but one linevertically down, and so on. The number of lines affected is determinedby the height of the saved rectangle. You can convert single-column lists into double-column lists usingrectangle killing and yanking; kill the second half of the list as arectangle and then yank it beside the first line of the list.@xref{Two-Column}, for another way to edit multi-column text. You can also copy rectangles into and out of registers with @kbd{C-x rr @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,RectangleRegisters}.@kindex C-x r o@findex open-rectangle@findex clear-rectangle There are two commands you can use for making blank rectangles:@kbd{M-x clear-rectangle} which blanks out existing text, and @kbd{C-x ro} (@code{open-rectangle}) which inserts a blank rectangle. Clearing arectangle is equivalent to deleting it and then inserting a blankrectangle of the same size.@findex delete-whitespace-rectangle The command @kbd{M-x delete-whitespace-rectangle} deletes horizontalwhitespace starting from a particular column. This applies to each ofthe lines in the rectangle, and the column is specified by the leftedge of the rectangle. The right edge of the rectangle does not makeany difference to this command.@kindex C-x r t@findex string-rectangle The command @kbd{C-x r t} (@code{string-rectangle}) replaces thecontents of a region-rectangle with a string on each line. Thestring's width need not be the same as the width of the rectangle. Ifthe string's width is less, the text after the rectangle shifts left;if the string is wider than the rectangle, the text after therectangle shifts right.@findex string-insert-rectangle The command @kbd{M-x string-insert-rectangle} is similar to @code{string-rectangle}, but inserts the string on each line, shifting the original text to the right.