/usr/share/doc/vim-doc/html/change.html is in vim-doc 2:7.3.429-2ubuntu2.2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 | <HTML>
<HEAD>
<META HTTP-EQUIV="Content-type" content="text/html; charset=ISO-8859-1">
<TITLE>Vim documentation: change</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<H1>Vim documentation: change</H1>
<A NAME="top"></A>
<A HREF="index.html">main help file</A>
<HR>
<PRE>
*<A NAME="change.txt"></A><B>change.txt</B>* For Vim version 7.3. Last change: 2012 Jan 04
VIM REFERENCE MANUAL by <A HREF="intro.html#Bram">Bram</A> <A HREF="intro.html#Moolenaar">Moolenaar</A>
This file describes commands that delete or change text. In this context,
<A HREF="#changing">changing</A> text means <A HREF="#deleting">deleting</A> the text and <A HREF="#replacing">replacing</A> <A HREF="motion.html#it">it</A> with other text using
one command. You can <A HREF="undo.html#undo">undo</A> all of these commands. You can repeat the non-Ex
commands with the "<A HREF="repeat.html#.">.</A>" command.
1. Deleting text |<A HREF="#deleting">deleting</A>|
2. Delete and insert |<A HREF="#delete-insert">delete-insert</A>|
3. Simple changes |<A HREF="#simple-change">simple-change</A>| *<A NAME="changing"></A><B>changing</B>*
4. Complex changes |<A HREF="#complex-change">complex-change</A>|
4.1 Filter commands |<A HREF="#filter">filter</A>|
4.2 Substitute |<A HREF="#:substitute">:substitute</A>|
4.3 Search and replace |<A HREF="#search-replace">search-replace</A>|
4.4 Changing tabs |<A HREF="#change-tabs">change-tabs</A>|
5. Copying and moving text |<A HREF="#copy-move">copy-move</A>|
6. Formatting text |<A HREF="#formatting">formatting</A>|
7. Sorting text |<A HREF="#sorting">sorting</A>|
For <A HREF="insert.html#inserting">inserting</A> text see |<A HREF="insert.html">insert.txt</A>|.
==============================================================================
1. Deleting text *<A NAME="deleting"></A><B>deleting</B>* *<A NAME="E470"></A><B>E470</B>*
["x]<Del> or *<A NAME="<Del>"></A><B><Del></B>* *<A NAME="x"></A><B>x</B>* *<A NAME="dl"></A><B>dl</B>*
["x]x Delete <A HREF="intro.html#[count]">[count]</A> characters under and after the cursor
[into <A HREF="sponsor.html#register">register</A> x] (not |<A HREF="motion.html#linewise">linewise</A>|). Does the same <A HREF="motion.html#as">as</A>
"<A HREF="#dl">dl</A>".
The <A HREF="#<Del>"><Del></A> key does not take a <A HREF="intro.html#[count]">[count]</A>. Instead, <A HREF="motion.html#it">it</A>
deletes the last character of the <A HREF="intro.html#count">count</A>.
See |<A HREF="options.html#:fixdel">:fixdel</A>| if the <A HREF="#<Del>"><Del></A> key does not <A HREF="diff.html#do">do</A> what you
want. See |<A HREF="options.html#'whichwrap'">'whichwrap'</A>| for <A HREF="#deleting">deleting</A> a line break
(join lines). {Vi does not support <Del>}
*<A NAME="X"></A><B>X</B>* *<A NAME="dh"></A><B>dh</B>*
["x]X Delete <A HREF="intro.html#[count]">[count]</A> characters before the cursor [into
<A HREF="sponsor.html#register">register</A> x] (not |<A HREF="motion.html#linewise">linewise</A>|). Does the same <A HREF="motion.html#as">as</A> "<A HREF="#dh">dh</A>".
Also see |<A HREF="options.html#'whichwrap'">'whichwrap'</A>|.
*<A NAME="d"></A><B>d</B>*
["x]d{motion} Delete text that <A HREF="intro.html#{motion}">{motion}</A> moves over [into <A HREF="sponsor.html#register">register</A>
x]. See below for exceptions.
*<A NAME="dd"></A><B>dd</B>*
["x]dd Delete <A HREF="intro.html#[count]">[count]</A> lines [into <A HREF="sponsor.html#register">register</A> x] |<A HREF="motion.html#linewise">linewise</A>|.
*<A NAME="D"></A><B>D</B>*
["x]D Delete the characters under the cursor until the end
of the line and [count]-1 more lines [into <A HREF="sponsor.html#register">register</A>
x]; synonym for "d$".
(not |<A HREF="motion.html#linewise">linewise</A>|)
When the '<A HREF="pattern.html##">#</A>' flag is in <A HREF="options.html#'cpoptions'">'cpoptions'</A> the <A HREF="intro.html#count">count</A> is
ignored.
{Visual}["x]x or *<A NAME="v_x"></A><B>v_x</B>* *<A NAME="v_d"></A><B>v_d</B>* *<A NAME="v_<Del>"></A><B>v_<Del></B>*
{Visual}["x]d or
{Visual}["x]<Del> Delete the highlighted text [into <A HREF="sponsor.html#register">register</A> x] (for
<A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
{Visual}["x]CTRL-H or *<A NAME="v_CTRL-H"></A><B>v_CTRL-H</B>* *<A NAME="v_<BS>"></A><B>v_<BS></B>*
{Visual}["x]<BS> When in <A HREF="visual.html#Select">Select</A> mode: Delete the highlighted text [into
<A HREF="sponsor.html#register">register</A> x].
{Visual}["x]X or *<A NAME="v_X"></A><B>v_X</B>* *<A NAME="v_D"></A><B>v_D</B>* *<A NAME="v_b_D"></A><B>v_b_D</B>*
{Visual}["x]D Delete the highlighted lines [into <A HREF="sponsor.html#register">register</A> x] (for
<A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). In Visual block mode,
"<A HREF="#D">D</A>" deletes the highlighted text plus all text until
the end of the line. {not in Vi}
*<A NAME=":d"></A><B>:d</B>* *<A NAME=":de"></A><B>:de</B>* *<A NAME=":del"></A><B>:del</B>* *<A NAME=":delete"></A><B>:delete</B>* *<A NAME=":dl"></A><B>:dl</B>*
:[range]d[elete] [x] Delete <A HREF="cmdline.html#[range]">[range]</A> lines (default: current line) [into
<A HREF="sponsor.html#register">register</A> x].
:[range]d[elete] [x] {count}
Delete {count} lines, starting with <A HREF="cmdline.html#[range]">[range]</A>
(default: current line |<A HREF="cmdline.html#cmdline-ranges">cmdline-ranges</A>|) [into
<A HREF="sponsor.html#register">register</A> x].
These commands delete text. You can repeat them with the "<A HREF="repeat.html#.">.</A>" command
(except "<A HREF="#:d">:d</A>") and <A HREF="undo.html#undo">undo</A> them. Use <A HREF="visual.html#Visual">Visual</A> mode to delete blocks of text. See
|<A HREF="#registers">registers</A>| for an explanation of registers.
An exception for the d{motion} command: If the motion is not <A HREF="motion.html#linewise">linewise</A>, the
start and end of the motion are not in the same line, and there are only
blanks before the start and after the end of the motion, the delete becomes
<A HREF="motion.html#linewise">linewise</A>. This means that the delete also removes the line of blanks that you
might expect to remain. Use the |<A HREF="motion.html#o_v">o_v</A>| <A HREF="motion.html#operator">operator</A> to force the motion to be
<A HREF="motion.html#characterwise">characterwise</A>.
Trying to delete an empty region of text (e.g., "d0" in the first column)
is an error when <A HREF="options.html#'cpoptions'">'cpoptions'</A> includes the '<A HREF="motion.html#E">E</A>' flag.
*<A NAME="J"></A><B>J</B>*
<A HREF="#J">J</A> Join <A HREF="intro.html#[count]">[count]</A> lines, with a minimum of two lines.
Remove the indent and insert up to two spaces (see
below).
*<A NAME="v_J"></A><B>v_J</B>*
{Visual}J Join the highlighted lines, with a minimum of two
lines. Remove the indent and insert up to two spaces
(see below). {not in Vi}
*<A NAME="gJ"></A><B>gJ</B>*
<A HREF="#gJ">gJ</A> Join <A HREF="intro.html#[count]">[count]</A> lines, with a minimum of two lines.
Don't insert or remove any spaces. {not in Vi}
*<A NAME="v_gJ"></A><B>v_gJ</B>*
{Visual}gJ Join the highlighted lines, with a minimum of two
lines. Don't insert or remove any spaces. {not in
Vi}
*<A NAME=":j"></A><B>:j</B>* *<A NAME=":join"></A><B>:join</B>*
:[range]j[oin][!] [flags]
Join <A HREF="cmdline.html#[range]">[range]</A> lines. Same <A HREF="motion.html#as">as</A> "<A HREF="#J">J</A>", except with [!]
the join does not insert or delete any spaces.
If a <A HREF="cmdline.html#[range]">[range]</A> has equal start and end values, this
command does nothing. The default behavior is to
join the current line with the line below <A HREF="motion.html#it">it</A>.
{not in <A HREF="intro.html#Vi">Vi</A>: !}
See |<A HREF="cmdline.html#ex-flags">ex-flags</A>| for [flags].
:[range]j[oin][!] {count} [flags]
Join {count} lines, starting with <A HREF="cmdline.html#[range]">[range]</A> (default:
current line |<A HREF="cmdline.html#cmdline-ranges">cmdline-ranges</A>|). Same <A HREF="motion.html#as">as</A> "<A HREF="#J">J</A>", except
with [!] the join does not insert or delete any
spaces.
{not in <A HREF="intro.html#Vi">Vi</A>: !}
See |<A HREF="cmdline.html#ex-flags">ex-flags</A>| for [flags].
These commands delete the <A HREF="intro.html#<EOL>"><EOL></A> between lines. This has the effect of joining
multiple lines into one line. You can repeat these commands (except "<A HREF="#:j">:j</A>") and
<A HREF="undo.html#undo">undo</A> them.
These commands, except "<A HREF="#gJ">gJ</A>", insert one space in place of the <A HREF="intro.html#<EOL>"><EOL></A> unless
there is trailing white space or the next line starts with a '<A HREF="motion.html#)">)</A>'. These
commands, except "<A HREF="#gJ">gJ</A>", delete any leading white space on the next line. If
the <A HREF="options.html#'joinspaces'">'joinspaces'</A> option is on, these commands insert two spaces after a '<A HREF="repeat.html#.">.</A>',
'<A HREF="#!">!</A>' or '<A HREF="pattern.html#?">?</A>' (but if <A HREF="options.html#'cpoptions'">'cpoptions'</A> includes the '<A HREF="motion.html#j">j</A>' flag, they insert two spaces
only after a '.').
The '<A HREF="motion.html#B">B</A>' and '<A HREF="motion.html#M">M</A>' flags in <A HREF="options.html#'formatoptions'">'formatoptions'</A> change the behavior for <A HREF="insert.html#inserting">inserting</A>
spaces before and after a <A HREF="mbyte.html#multi-byte">multi-byte</A> character |<A HREF="#fo-table">fo-table</A>|.
==============================================================================
2. Delete and insert *<A NAME="delete-insert"></A><B>delete-insert</B>* *<A NAME="replacing"></A><B>replacing</B>*
*<A NAME="R"></A><B>R</B>*
<A HREF="#R">R</A> Enter <A HREF="insert.html#Replace">Replace</A> mode: Each character you type replaces
an existing character, starting with the character
under the cursor. Repeat the entered text [count]-1
times. See |<A HREF="insert.html#Replace-mode">Replace-mode</A>| for more details.
*<A NAME="gR"></A><B>gR</B>*
<A HREF="#gR">gR</A> Enter Virtual <A HREF="insert.html#Replace">Replace</A> mode: Each character you type
replaces existing characters in screen space. So a
<A HREF="motion.html#<Tab>"><Tab></A> may replace several characters at once.
Repeat the entered text [count]-1 times. See
|<A HREF="insert.html#Virtual-Replace-mode">Virtual-Replace-mode</A>| for more details.
{not available when compiled without the |<A HREF="various.html#+vreplace">+vreplace</A>|
feature}
*<A NAME="c"></A><B>c</B>*
["x]c{motion} Delete <A HREF="intro.html#{motion}">{motion}</A> text [into <A HREF="sponsor.html#register">register</A> x] and start
insert. When <A HREF="options.html#'cpoptions'">'cpoptions'</A> includes the '<A HREF="motion.html#E">E</A>' flag and
there is no text to delete (e.g., with "cTx" when the
cursor is just after an 'x'), an error occurs and
insert mode does not start (this is <A HREF="intro.html#Vi">Vi</A> compatible).
When <A HREF="options.html#'cpoptions'">'cpoptions'</A> does not include the '<A HREF="motion.html#E">E</A>' flag, the
"<A HREF="#c">c</A>" command always starts insert mode, even if there
is no text to delete.
*<A NAME="cc"></A><B>cc</B>*
["x]cc Delete <A HREF="intro.html#[count]">[count]</A> lines [into <A HREF="sponsor.html#register">register</A> x] and start
insert |<A HREF="motion.html#linewise">linewise</A>|. If <A HREF="options.html#'autoindent'">'autoindent'</A> is on, preserve
the indent of the first line.
*<A NAME="C"></A><B>C</B>*
["x]C Delete from the cursor position to the end of the
line and [count]-1 more lines [into <A HREF="sponsor.html#register">register</A> x], and
start insert. Synonym for c$ (not |<A HREF="motion.html#linewise">linewise</A>|).
*<A NAME="s"></A><B>s</B>*
["x]s Delete <A HREF="intro.html#[count]">[count]</A> characters [into <A HREF="sponsor.html#register">register</A> x] and start
insert (s stands for Substitute). Synonym for "cl"
(not |<A HREF="motion.html#linewise">linewise</A>|).
*<A NAME="S"></A><B>S</B>*
["x]S Delete <A HREF="intro.html#[count]">[count]</A> lines [into <A HREF="sponsor.html#register">register</A> x] and start
insert. Synonym for "<A HREF="#cc">cc</A>" |<A HREF="motion.html#linewise">linewise</A>|.
{Visual}["x]c or *<A NAME="v_c"></A><B>v_c</B>* *<A NAME="v_s"></A><B>v_s</B>*
{Visual}["x]s Delete the highlighted text [into <A HREF="sponsor.html#register">register</A> x] and
start insert (for <A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not
in Vi}
*<A NAME="v_r"></A><B>v_r</B>*
{Visual}["x]r{char} <A HREF="insert.html#Replace">Replace</A> all selected characters by {char}.
*<A NAME="v_C"></A><B>v_C</B>*
{Visual}["x]C Delete the highlighted lines [into <A HREF="sponsor.html#register">register</A> x] and
start insert. In <A HREF="visual.html#Visual">Visual</A> block mode <A HREF="motion.html#it">it</A> works
differently |<A HREF="visual.html#v_b_C">v_b_C</A>|. {not in Vi}
*<A NAME="v_S"></A><B>v_S</B>*
{Visual}["x]S Delete the highlighted lines [into <A HREF="sponsor.html#register">register</A> x] and
start insert (for <A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not
in Vi}
*<A NAME="v_R"></A><B>v_R</B>*
{Visual}["x]R Currently just like {Visual}["x]S. In a next version
<A HREF="motion.html#it">it</A> might work differently. {not in Vi}
Notes:
- You can end <A HREF="insert.html#Insert">Insert</A> and <A HREF="insert.html#Replace">Replace</A> mode with <A HREF="intro.html#<Esc>"><Esc></A>.
- See the section "<A HREF="insert.html#Insert">Insert</A> and <A HREF="insert.html#Replace">Replace</A> mode" |<A HREF="insert.html#mode-ins-repl">mode-ins-repl</A>| for the other
special characters in these modes.
- The effect of <A HREF="intro.html#[count]">[count]</A> takes place after Vim exits <A HREF="insert.html#Insert">Insert</A> or <A HREF="insert.html#Replace">Replace</A> mode.
- When the <A HREF="options.html#'cpoptions'">'cpoptions'</A> option contains '<A HREF="motion.html#$">$</A>' and the change is within one line,
Vim continues to show the text to be deleted and puts a '<A HREF="motion.html#$">$</A>' at the last
deleted character.
See |<A HREF="#registers">registers</A>| for an explanation of registers.
<A HREF="insert.html#Replace">Replace</A> mode is just like <A HREF="insert.html#Insert">Insert</A> mode, except that every character you enter
deletes one character. If you reach the end of a line, Vim appends any
further characters (just like <A HREF="insert.html#Insert">Insert</A> mode). In <A HREF="insert.html#Replace">Replace</A> mode, the backspace
key restores the original text (if there was any). (See section "<A HREF="insert.html#Insert">Insert</A> and
<A HREF="insert.html#Replace">Replace</A> mode" |<A HREF="insert.html#mode-ins-repl">mode-ins-repl</A>|).
*<A NAME="cw"></A><B>cw</B>* *<A NAME="cW"></A><B>cW</B>*
Special <A HREF="#case">case</A>: When the cursor is in a <A HREF="motion.html#word">word</A>, "<A HREF="#cw">cw</A>" and "<A HREF="#cW">cW</A>" <A HREF="diff.html#do">do</A> not include the
white space after a <A HREF="motion.html#word">word</A>, they only change up to the end of the <A HREF="motion.html#word">word</A>. This is
because Vim interprets "<A HREF="#cw">cw</A>" <A HREF="motion.html#as">as</A> change-word, and a <A HREF="motion.html#word">word</A> does not include the
following white space.
{Vi: "<A HREF="#cw">cw</A>" when on a blank followed by other blanks changes only the first
blank; this is probably a bug, because "dw" deletes all the blanks; use the
'<A HREF="motion.html#w">w</A>' flag in <A HREF="options.html#'cpoptions'">'cpoptions'</A> to make <A HREF="motion.html#it">it</A> work like <A HREF="intro.html#Vi">Vi</A> anyway}
If you prefer "<A HREF="#cw">cw</A>" to include the space after a <A HREF="motion.html#word">word</A>, use this <A HREF="map.html#mapping">mapping</A>:
<B> :map cw dwi</B>
Or use "caw" (see |<A HREF="motion.html#aw">aw</A>|).
*<A NAME=":c"></A><B>:c</B>* *<A NAME=":ch"></A><B>:ch</B>* *<A NAME=":change"></A><B>:change</B>*
:{range}c[hange][!] <A HREF="insert.html#Replace">Replace</A> lines of text with some different text.
Type a line containing only "<A HREF="repeat.html#.">.</A>" to stop <A HREF="#replacing">replacing</A>.
Without {range}, this command changes only the current
line.
Adding [!] toggles <A HREF="options.html#'autoindent'">'autoindent'</A> for the time this
command is executed.
==============================================================================
3. Simple changes *<A NAME="simple-change"></A><B>simple-change</B>*
*<A NAME="r"></A><B>r</B>*
r{char} <A HREF="insert.html#Replace">Replace</A> the character under the cursor with {char}.
If {char} is a <A HREF="motion.html#<CR>"><CR></A> or <A HREF="motion.html#<NL>"><NL></A>, a line break replaces the
character. To replace with a real <A HREF="motion.html#<CR>"><CR></A>, use <A HREF="visual.html#CTRL-V">CTRL-V</A>
<A HREF="motion.html#<CR>"><CR></A>. <A HREF="visual.html#CTRL-V">CTRL-V</A> <A HREF="motion.html#<NL>"><NL></A> replaces with a <A HREF="intro.html#<Nul>"><Nul></A>.
{Vi: <A HREF="visual.html#CTRL-V">CTRL-V</A> <A HREF="motion.html#<CR>"><CR></A> still replaces with a line break,
cannot replace something with a <CR>}
If you give a <A HREF="intro.html#[count]">[count]</A>, Vim replaces <A HREF="intro.html#[count]">[count]</A> characters
with <A HREF="intro.html#[count]">[count]</A> {char}s. When {char} is a <A HREF="motion.html#<CR>"><CR></A> or <A HREF="motion.html#<NL>"><NL></A>,
however, Vim inserts only one <A HREF="motion.html#<CR>"><CR></A>: "5r<CR>" replaces
five characters with a single line break.
When {char} is a <A HREF="motion.html#<CR>"><CR></A> or <A HREF="motion.html#<NL>"><NL></A>, Vim performs
autoindenting. This works just like <A HREF="#deleting">deleting</A> the
characters that are replaced and then doing
"i<CR><Esc>".
{char} can be entered <A HREF="motion.html#as">as</A> a digraph |<A HREF="#digraph-arg">digraph-arg</A>|.
|<A HREF="map.html#:lmap">:lmap</A>| mappings apply to {char}. The <A HREF="editing.html#CTRL-^">CTRL-^</A> command
in <A HREF="insert.html#Insert">Insert</A> mode can be used to switch this on/off
|<A HREF="insert.html#i_CTRL-^">i_CTRL-^</A>|. See |<A HREF="mbyte.html#utf-8-char-arg">utf-8-char-arg</A>| about using
composing characters when <A HREF="options.html#'encoding'">'encoding'</A> is <A HREF="mbyte.html#Unicode">Unicode</A>.
*<A NAME="gr"></A><B>gr</B>*
gr{char} <A HREF="insert.html#Replace">Replace</A> the virtual characters under the cursor with
{char}. This replaces in screen space, not file
space. See |<A HREF="#gR">gR</A>| and |<A HREF="insert.html#Virtual-Replace-mode">Virtual-Replace-mode</A>| for more
details. As with |<A HREF="#r">r</A>| a <A HREF="intro.html#count">count</A> may be given.
{char} can be entered like with |<A HREF="#r">r</A>|.
{not available when compiled without the |<A HREF="various.html#+vreplace">+vreplace</A>|
feature}
*<A NAME="digraph-arg"></A><B>digraph-arg</B>*
The argument for <A HREF="intro.html#Normal">Normal</A> mode commands like |<A HREF="#r">r</A>| and |<A HREF="motion.html#t">t</A>| is a single character.
When <A HREF="options.html#'cpo'">'cpo'</A> doesn't contain the '<A HREF="#D">D</A>' flag, this character can also be entered
like |<A HREF="digraph.html#digraphs">digraphs</A>|. First type CTRL-K and then the two digraph characters.
{not available when compiled without the |<A HREF="various.html#+digraphs">+digraphs</A>| feature}
*<A NAME="case"></A><B>case</B>*
The following commands change the <A HREF="#case">case</A> of letters. The currently active
|<A HREF="mbyte.html#locale">locale</A>| is used. See |<A HREF="mlang.html#:language">:language</A>|. The LC_CTYPE value matters here.
*<A NAME="~"></A><B>~</B>*
~ <A HREF="options.html#'notildeop'">'notildeop'</A> option: Switch <A HREF="#case">case</A> of the character
under the cursor and move the cursor to the right.
If a <A HREF="intro.html#[count]">[count]</A> is given, <A HREF="diff.html#do">do</A> that many characters. {Vi:
no count}
~{motion} <A HREF="options.html#'tildeop'">'tildeop'</A> option: switch <A HREF="#case">case</A> of <A HREF="intro.html#{motion}">{motion}</A> text. {Vi:
tilde cannot be used <A HREF="motion.html#as">as</A> an operator}
*<A NAME="g~"></A><B>g~</B>*
g~{motion} Switch <A HREF="#case">case</A> of <A HREF="intro.html#{motion}">{motion}</A> text. {not in Vi}
<A HREF="#g~g~">g~g~</A> *<A NAME="g~g~"></A><B>g~g~</B>* *<A NAME="g~~"></A><B>g~~</B>*
<A HREF="#g~~">g~~</A> Switch <A HREF="#case">case</A> of current line. {not in Vi}.
*<A NAME="v_~"></A><B>v_~</B>*
{Visual}~ Switch <A HREF="#case">case</A> of highlighted text (for <A HREF="intro.html#{Visual}">{Visual}</A> see
|<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
*<A NAME="v_U"></A><B>v_U</B>*
{Visual}U Make highlighted text <A HREF="#uppercase">uppercase</A> (for <A HREF="intro.html#{Visual}">{Visual}</A> see
|<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
*<A NAME="gU"></A><B>gU</B>* *<A NAME="uppercase"></A><B>uppercase</B>*
gU{motion} Make <A HREF="intro.html#{motion}">{motion}</A> text <A HREF="#uppercase">uppercase</A>. {not in Vi}
Example:
<B> :map! <C-F> <Esc>gUiw`]a</B>
This works in <A HREF="insert.html#Insert">Insert</A> mode: press <A HREF="scroll.html#CTRL-F">CTRL-F</A> to make the
<A HREF="motion.html#word">word</A> before the cursor <A HREF="#uppercase">uppercase</A>. Handy to type
words in <A HREF="#lowercase">lowercase</A> and then make them <A HREF="#uppercase">uppercase</A>.
<A HREF="#gUgU">gUgU</A> *<A NAME="gUgU"></A><B>gUgU</B>* *<A NAME="gUU"></A><B>gUU</B>*
<A HREF="#gUU">gUU</A> Make current line <A HREF="#uppercase">uppercase</A>. {not in Vi}.
*<A NAME="v_u"></A><B>v_u</B>*
{Visual}u Make highlighted text <A HREF="#lowercase">lowercase</A> (for <A HREF="intro.html#{Visual}">{Visual}</A> see
|<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
*<A NAME="gu"></A><B>gu</B>* *<A NAME="lowercase"></A><B>lowercase</B>*
gu{motion} Make <A HREF="intro.html#{motion}">{motion}</A> text <A HREF="#lowercase">lowercase</A>. {not in Vi}
<A HREF="#gugu">gugu</A> *<A NAME="gugu"></A><B>gugu</B>* *<A NAME="guu"></A><B>guu</B>*
<A HREF="#guu">guu</A> Make current line <A HREF="#lowercase">lowercase</A>. {not in Vi}.
*<A NAME="g?"></A><B>g?</B>* *<A NAME="rot13"></A><B>rot13</B>*
g?{motion} Rot13 encode <A HREF="intro.html#{motion}">{motion}</A> text. {not in Vi}
*<A NAME="v_g?"></A><B>v_g?</B>*
{Visual}g? Rot13 encode the highlighted text (for <A HREF="intro.html#{Visual}">{Visual}</A> see
|<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
<A HREF="#g?g?">g?g?</A> *<A NAME="g?g?"></A><B>g?g?</B>* *<A NAME="g??"></A><B>g??</B>*
<A HREF="#g??">g??</A> Rot13 encode current line. {not in Vi}.
To turn one line into title caps, make every first <A HREF="print.html#letter">letter</A> of a <A HREF="motion.html#word">word</A>
<A HREF="#uppercase">uppercase</A>:
<B> :s/\v<(.)(\w*)/\u\1\L\2/g</B>
<B><FONT COLOR="PURPLE">Adding and subtracting </FONT></B>
*<A NAME="CTRL-A"></A><B>CTRL-A</B>*
<A HREF="#CTRL-A">CTRL-A</A> Add <A HREF="intro.html#[count]">[count]</A> to the number or alphabetic character at
or after the cursor. {not in Vi}
*<A NAME="CTRL-X"></A><B>CTRL-X</B>*
<A HREF="#CTRL-X">CTRL-X</A> Subtract <A HREF="intro.html#[count]">[count]</A> from the number or alphabetic
character at or after the cursor. {not in Vi}
The <A HREF="#CTRL-A">CTRL-A</A> and <A HREF="#CTRL-X">CTRL-X</A> commands work for (signed) decimal numbers, unsigned
<A HREF="eval.html#octal">octal</A> and hexadecimal numbers and alphabetic characters. This depends on the
<A HREF="options.html#'nrformats'">'nrformats'</A> option.
- When <A HREF="options.html#'nrformats'">'nrformats'</A> includes "<A HREF="eval.html#octal">octal</A>", Vim considers numbers starting with a '<A HREF="motion.html#0">0</A>'
to be <A HREF="eval.html#octal">octal</A>, unless the number includes a '8' or '9'. Other numbers are
decimal and may have a preceding minus sign.
If the cursor is on a number, the commands apply to that number; otherwise
Vim uses the number to the right of the cursor.
- When <A HREF="options.html#'nrformats'">'nrformats'</A> includes "hex", Vim assumes numbers starting with '0x' or
'0X' are hexadecimal. The <A HREF="#case">case</A> of the rightmost <A HREF="print.html#letter">letter</A> in the number
determines the <A HREF="#case">case</A> of the resulting hexadecimal number. If there is no
<A HREF="print.html#letter">letter</A> in the current number, Vim uses the previously detected <A HREF="#case">case</A>.
- When <A HREF="options.html#'nrformats'">'nrformats'</A> includes "alpha", Vim will change the alphabetic character
under or after the cursor. This is useful to make lists with an alphabetic
index.
For numbers with leading zeros (including all <A HREF="eval.html#octal">octal</A> and hexadecimal numbers),
Vim preserves the number of characters in the number when possible. <A HREF="#CTRL-A">CTRL-A</A> on
"0077" results in "0100", <A HREF="#CTRL-X">CTRL-X</A> on "0x100" results in "0x0ff".
There is one exception: When a number that starts with a zero is found not to
be <A HREF="eval.html#octal">octal</A> (it contains a '8' or '9'), but <A HREF="options.html#'nrformats'">'nrformats'</A> does include "<A HREF="eval.html#octal">octal</A>",
leading zeros are removed to avoid that the result may be recognized <A HREF="motion.html#as">as</A> an
<A HREF="eval.html#octal">octal</A> number.
Note that when <A HREF="options.html#'nrformats'">'nrformats'</A> includes "<A HREF="eval.html#octal">octal</A>", decimal numbers with leading
zeros cause mistakes, because they can be confused with <A HREF="eval.html#octal">octal</A> numbers.
The <A HREF="#CTRL-A">CTRL-A</A> command is very useful in a <A HREF="map.html#macro">macro</A>. Example: Use the following
steps to make a numbered list.
1. Create the first list entry, make sure <A HREF="motion.html#it">it</A> starts with a number.
2. qa - start <A HREF="repeat.html#recording">recording</A> into <A HREF="sponsor.html#register">register</A> '<A HREF="insert.html#a">a</A>'
3. <A HREF="#Y">Y</A> - <A HREF="#yank">yank</A> the entry
4. <A HREF="#p">p</A> - put a copy of the entry below the first one
5. <A HREF="#CTRL-A">CTRL-A</A> - increment the number
6. <A HREF="repeat.html#q">q</A> - stop <A HREF="repeat.html#recording">recording</A>
7. <count>@a - repeat the <A HREF="#yank">yank</A>, put and increment <A HREF="map.html#<count>"><count></A> times
SHIFTING LINES LEFT OR RIGHT *<A NAME="shift-left-right"></A><B>shift-left-right</B>*
*<A NAME="<"></A><B><</B>*
<{motion} Shift <A HREF="intro.html#{motion}">{motion}</A> lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> leftwards.
*<A NAME="<<"></A><B><<</B>*
<A HREF="#<<"><<</A> Shift <A HREF="intro.html#[count]">[count]</A> lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> leftwards.
*<A NAME="v_<"></A><B>v_<</B>*
{Visual}[count]< Shift the highlighted lines <A HREF="intro.html#[count]">[count]</A> <A HREF="options.html#'shiftwidth'">'shiftwidth'</A>
leftwards (for <A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in
Vi}
*<A NAME=">"></A><B>></B>*
>{motion} Shift <A HREF="intro.html#{motion}">{motion}</A> lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> rightwards.
*<A NAME=">>"></A><B>>></B>*
<A HREF="#>>">>></A> Shift <A HREF="intro.html#[count]">[count]</A> lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> rightwards.
*<A NAME="v_>"></A><B>v_></B>*
{Visual}[count]> Shift the highlighted lines <A HREF="intro.html#[count]">[count]</A> <A HREF="options.html#'shiftwidth'">'shiftwidth'</A>
rightwards (for <A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in
Vi}
*<A NAME=":<"></A><B>:<</B>*
:[range]< Shift <A HREF="cmdline.html#[range]">[range]</A> lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> left. Repeat '<A HREF="#<"><</A>'
for shifting multiple 'shiftwidth's.
:[range]< {count} Shift {count} lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> left, starting
with <A HREF="cmdline.html#[range]">[range]</A> (default current line |<A HREF="cmdline.html#cmdline-ranges">cmdline-ranges</A>|).
Repeat '<A HREF="#<"><</A>' for shifting multiple 'shiftwidth's.
:[range]le[ft] [indent] left align lines in <A HREF="cmdline.html#[range]">[range]</A>. Sets the indent in the
lines to [indent] (default 0). {not in Vi}
*<A NAME=":>"></A><B>:></B>*
:[range]> [flags] Shift {count} <A HREF="cmdline.html#[range]">[range]</A> lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> right.
Repeat '<A HREF="#>">></A>' for shifting multiple 'shiftwidth's.
See |<A HREF="cmdline.html#ex-flags">ex-flags</A>| for [flags].
:[range]> {count} [flags]
Shift {count} lines one <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> right, starting
with <A HREF="cmdline.html#[range]">[range]</A> (default current line |<A HREF="cmdline.html#cmdline-ranges">cmdline-ranges</A>|).
Repeat '<A HREF="#>">></A>' for shifting multiple 'shiftwidth's.
See |<A HREF="cmdline.html#ex-flags">ex-flags</A>| for [flags].
The "<A HREF="#>">></A>" and "<A HREF="#<"><</A>" commands are handy for <A HREF="#changing">changing</A> the indentation within
programs. Use the <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> option to set the size of the white space
which these commands insert or delete. Normally the <A HREF="options.html#'shiftwidth'">'shiftwidth'</A> option is 8,
but you can set <A HREF="motion.html#it">it</A> to, say, 3 to make smaller indents. The <A HREF="intro.html#shift">shift</A> leftwards
stops when there is no indent. The <A HREF="intro.html#shift">shift</A> right does not affect empty lines.
If the <A HREF="options.html#'shiftround'">'shiftround'</A> option is on, the indent is rounded to a multiple of
<A HREF="options.html#'shiftwidth'">'shiftwidth'</A>.
If the <A HREF="options.html#'smartindent'">'smartindent'</A> option is on, or <A HREF="options.html#'cindent'">'cindent'</A> is on and <A HREF="options.html#'cinkeys'">'cinkeys'</A> contains
'<A HREF="pattern.html##">#</A>', <A HREF="intro.html#shift">shift</A> right does not affect lines starting with '<A HREF="pattern.html##">#</A>' (these are supposed
to be C preprocessor lines that must stay in column 1).
When the <A HREF="options.html#'expandtab'">'expandtab'</A> option is off (this is the default) Vim uses <Tab>s <A HREF="motion.html#as">as</A>
much <A HREF="motion.html#as">as</A> possible to make the indent. You can use ">><<" to replace an indent
made out of spaces with the same indent made out of <Tab>s (and a few spaces
if necessary). If the <A HREF="options.html#'expandtab'">'expandtab'</A> option is on, Vim uses only spaces. Then
you can use ">><<" to replace <Tab>s in the indent by spaces (or use
":retab!").
To move a line several 'shiftwidth's, use <A HREF="visual.html#Visual">Visual</A> mode or the "<A HREF="cmdline.html#:">:</A>" commands.
For example:
<B> Vjj4> move three lines 4 indents to the right</B>
<B> :<<< move current line 3 indents to the left</B>
<B> :>> 5 move 5 lines 2 indents to the right</B>
<B> :5>> move line 5 2 indents to the right</B>
==============================================================================
4. Complex changes *<A NAME="complex-change"></A><B>complex-change</B>*
4.1 Filter commands *<A NAME="filter"></A><B>filter</B>*
A <A HREF="#filter">filter</A> is a program that accepts text at standard input, changes <A HREF="motion.html#it">it</A> in some
way, and sends <A HREF="motion.html#it">it</A> to standard output. You can use the commands below to send
some text through a <A HREF="#filter">filter</A>, so that <A HREF="motion.html#it">it</A> is replaced by the <A HREF="#filter">filter</A> output.
Examples of filters are "sort", which sorts lines alphabetically, and
"indent", which formats C program files (you need a version of indent that
works like a <A HREF="#filter">filter</A>; not all versions <A HREF="diff.html#do">do</A>). The <A HREF="options.html#'shell'">'shell'</A> option specifies the
shell Vim uses to execute the <A HREF="#filter">filter</A> command (See also the <A HREF="options.html#'shelltype'">'shelltype'</A>
option). You can repeat <A HREF="#filter">filter</A> commands with "<A HREF="repeat.html#.">.</A>". Vim does not recognize a
comment (starting with '"'') after the "<A HREF="various.html#:!">:!</A>" command.
*<A NAME="!"></A><B>!</B>*
!{motion}{filter} Filter <A HREF="intro.html#{motion}">{motion}</A> text lines through the external
program {filter}.
*<A NAME="!!"></A><B>!!</B>*
!!{filter} Filter <A HREF="intro.html#[count]">[count]</A> lines through the external program
{filter}.
*<A NAME="v_!"></A><B>v_!</B>*
{Visual}!{filter} Filter the highlighted lines through the external
program {filter} (for <A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|).
{not in Vi}
:{range}![!]{filter} [!][arg] *<A NAME=":range!"></A><B>:range!</B>*
Filter {range} lines through the external program
{filter}. Vim replaces the optional bangs with the
latest given command and appends the optional [arg].
Vim saves the output of the <A HREF="#filter">filter</A> command in a
temporary file and then reads the file into the buffer
|<A HREF="#tempfile">tempfile</A>|. Vim uses the <A HREF="options.html#'shellredir'">'shellredir'</A> option to
redirect the <A HREF="#filter">filter</A> output to the temporary file.
However, if the <A HREF="options.html#'shelltemp'">'shelltemp'</A> option is off then pipes
are used when possible (on <A HREF="os_unix.html#Unix">Unix</A>).
When the '<A HREF="#R">R</A>' flag is included in <A HREF="options.html#'cpoptions'">'cpoptions'</A> marks in
the filtered lines are deleted, unless the
|<A HREF="motion.html#:keepmarks">:keepmarks</A>| command is used. Example:
<B> :keepmarks '<,'>!sort</B>
When the number of lines after filtering is <A HREF="various.html#less">less</A> than
before, marks in the missing lines are deleted anyway.
*<A NAME="="></A><B>=</B>*
={motion} Filter <A HREF="intro.html#{motion}">{motion}</A> lines through the external program
given with the <A HREF="options.html#'equalprg'">'equalprg'</A> option. When the <A HREF="options.html#'equalprg'">'equalprg'</A>
option is empty (this is the default), use the
internal <A HREF="#formatting">formatting</A> function |<A HREF="indent.html#C-indenting">C-indenting</A>| and
|<A HREF="options.html#'lisp'">'lisp'</A>|. But when <A HREF="options.html#'indentexpr'">'indentexpr'</A> is not empty, <A HREF="motion.html#it">it</A> will
be used instead |<A HREF="indent.html#indent-expression">indent-expression</A>|. When Vim was
compiled without internal <A HREF="#formatting">formatting</A> then the "indent"
program is used <A HREF="motion.html#as">as</A> a last resort.
*<A NAME="=="></A><B>==</B>*
<A HREF="#==">==</A> Filter <A HREF="intro.html#[count]">[count]</A> lines like with ={motion}.
*<A NAME="v_="></A><B>v_=</B>*
{Visual}= Filter the highlighted lines like with ={motion}.
{not in Vi}
*<A NAME="tempfile"></A><B>tempfile</B>* *<A NAME="setuid"></A><B>setuid</B>*
Vim uses temporary files for filtering, generating diffs and also for
<A HREF="eval.html#tempname()">tempname()</A>. For <A HREF="os_unix.html#Unix">Unix</A>, the file will be in a private directory (only
accessible by the current user) to avoid security problems (e.g., a symlink
attack or other people reading your file). When Vim exits the directory and
all files in <A HREF="motion.html#it">it</A> are deleted. When Vim has the <A HREF="#setuid">setuid</A> bit set this may cause
problems, the temp file is owned by the <A HREF="#setuid">setuid</A> user but the <A HREF="#filter">filter</A> command
probably runs <A HREF="motion.html#as">as</A> the original user.
On <A HREF="os_msdos.html#MS-DOS">MS-DOS</A> and <A HREF="os_os2.html#OS/2">OS/2</A> the first of these directories that works is used: $TMP,
$TEMP, c:\TMP, c:\TEMP.
For <A HREF="os_unix.html#Unix">Unix</A> the list of directories is: $TMPDIR, /tmp, current-dir, <A HREF="options.html#$HOME">$HOME</A>.
For <A HREF="os_win32.html#MS-Windows">MS-Windows</A> the GetTempFileName() system function is used.
For other systems the tmpnam() library function is used.
4.2 Substitute *<A NAME=":substitute"></A><B>:substitute</B>*
*<A NAME=":s"></A><B>:s</B>* *<A NAME=":su"></A><B>:su</B>*
:[range]s[ubstitute]/{pattern}/{string}/[flags] <A HREF="intro.html#[count]">[count]</A>
For each line in <A HREF="cmdline.html#[range]">[range]</A> replace a match of {pattern}
with {string}.
For the {pattern} see |<A HREF="pattern.html#pattern">pattern</A>|.
{string} can be a literal string, or something
special; see |<A HREF="#sub-replace-special">sub-replace-special</A>|.
When <A HREF="cmdline.html#[range]">[range]</A> and <A HREF="intro.html#[count]">[count]</A> are omitted, replace in the
current line only.
When <A HREF="intro.html#[count]">[count]</A> is given, replace in <A HREF="intro.html#[count]">[count]</A> lines,
starting with the last line in <A HREF="cmdline.html#[range]">[range]</A>. When <A HREF="cmdline.html#[range]">[range]</A>
is omitted start in the current line.
Also see |<A HREF="cmdline.html#cmdline-ranges">cmdline-ranges</A>|.
See |<A HREF="#:s_flags">:s_flags</A>| for [flags].
:[range]s[ubstitute] [flags] <A HREF="intro.html#[count]">[count]</A>
:[range]&[&][flags] <A HREF="intro.html#[count]">[count]</A> *<A NAME=":&"></A><B>:&</B>*
Repeat last <A HREF="#:substitute">:substitute</A> with same search <A HREF="pattern.html#pattern">pattern</A> and
substitute string, but without the same flags. You
may add [flags], see |<A HREF="#:s_flags">:s_flags</A>|.
Note that after "<A HREF="#:substitute">:substitute</A>" the '<A HREF="#&">&</A>' flag can't be
used, it's recognized <A HREF="motion.html#as">as</A> a <A HREF="pattern.html#pattern">pattern</A> separator.
The space between "<A HREF="#:substitute">:substitute</A>" and the '<A HREF="#c">c</A>', '<A HREF="index.html#g">g</A>' and
'<A HREF="#r">r</A>' flags isn't required, but in scripts it's a good
idea to keep <A HREF="motion.html#it">it</A> to avoid confusion.
:[range]~[&][flags] <A HREF="intro.html#[count]">[count]</A> *<A NAME=":~"></A><B>:~</B>*
Repeat last substitute with same substitute string
but with last used search <A HREF="pattern.html#pattern">pattern</A>. This is like
":&r". See |<A HREF="#:s_flags">:s_flags</A>| for [flags].
*<A NAME="&"></A><B>&</B>*
<A HREF="#&">&</A> Synonym for "<A HREF="#:s">:s</A>" (repeat last substitute). Note
that the flags are not remembered, thus <A HREF="motion.html#it">it</A> might
actually work differently. You can use ":&&" to keep
the flags.
*<A NAME="g&"></A><B>g&</B>*
<A HREF="#g&">g&</A> Synonym for ":%s//~/&" (repeat last substitute on all
lines with the same flags).
Mnemonic: global substitute. {not in Vi}
*<A NAME=":snomagic"></A><B>:snomagic</B>* *<A NAME=":sno"></A><B>:sno</B>*
:[range]sno[magic] <A HREF="eval.html#...">...</A> Same <A HREF="motion.html#as">as</A> "<A HREF="#:substitute">:substitute</A>", but always use <A HREF="options.html#'nomagic'">'nomagic'</A>.
{not in Vi}
*<A NAME=":smagic"></A><B>:smagic</B>* *<A NAME=":sm"></A><B>:sm</B>*
:[range]sm[agic] <A HREF="eval.html#...">...</A> Same <A HREF="motion.html#as">as</A> "<A HREF="#:substitute">:substitute</A>", but always use <A HREF="options.html#'magic'">'magic'</A>.
{not in Vi}
*<A NAME=":s_flags"></A><B>:s_flags</B>*
The flags that you can use for the substitute commands:
[&] Must be the first one: Keep the flags from the previous substitute
command. Examples:
<B> :&&</B>
<B> :s/this/that/&</B>
Note that "<A HREF="#:s">:s</A>" and "<A HREF="#:&">:&</A>" don't keep the flags.
{not in Vi}
[c] Confirm each substitution. Vim highlights the matching string (with
|<A HREF="syntax.html#hl-IncSearch">hl-IncSearch</A>|). You can type: *<A NAME=":s_c"></A><B>:s_c</B>*
'<A HREF="#y">y</A>' to substitute this match
'<A HREF="motion.html#l">l</A>' to substitute this match and then quit ("last")
'<A HREF="pattern.html#n">n</A>' to skip this match
<A HREF="intro.html#<Esc>"><Esc></A> to quit substituting
'<A HREF="insert.html#a">a</A>' to substitute this and all remaining matches {not in Vi}
'<A HREF="repeat.html#q">q</A>' to quit substituting {not in Vi}
<A HREF="scroll.html#CTRL-E">CTRL-E</A> to scroll the screen up {not in <A HREF="intro.html#Vi">Vi</A>, not available when
compiled without the |<A HREF="various.html#+insert_expand">+insert_expand</A>| feature}
<A HREF="scroll.html#CTRL-Y">CTRL-Y</A> to scroll the screen down {not in <A HREF="intro.html#Vi">Vi</A>, not available when
compiled without the |<A HREF="various.html#+insert_expand">+insert_expand</A>| feature}
If the <A HREF="options.html#'edcompatible'">'edcompatible'</A> option is on, Vim remembers the [c] flag and
toggles <A HREF="motion.html#it">it</A> each time you use <A HREF="motion.html#it">it</A>, but resets <A HREF="motion.html#it">it</A> when you give a new
search <A HREF="pattern.html#pattern">pattern</A>.
{not in <A HREF="intro.html#Vi">Vi</A>: highlighting of the match, other responses than '<A HREF="#y">y</A>' or 'n'}
[e] When the search <A HREF="pattern.html#pattern">pattern</A> fails, <A HREF="diff.html#do">do</A> not issue an error message and, in
particular, continue in maps <A HREF="motion.html#as">as</A> if no error occurred. This is most
useful to prevent the "No match" error from breaking a <A HREF="map.html#mapping">mapping</A>. Vim
does not suppress the following error <A HREF="message.html#messages">messages</A>, however:
Regular expressions can't be delimited by letters
\ should be followed by /, ? or <A HREF="#&">&</A>
No previous substitute regular <A HREF="eval.html#expression">expression</A>
Trailing characters
Interrupted
{not in Vi}
[g] <A HREF="insert.html#Replace">Replace</A> all occurrences in the line. Without this argument,
replacement occurs only for the first occurrence in each line. If
the <A HREF="options.html#'edcompatible'">'edcompatible'</A> option is on, Vim remembers this flag and toggles
<A HREF="motion.html#it">it</A> each time you use <A HREF="motion.html#it">it</A>, but resets <A HREF="motion.html#it">it</A> when you give a new search
<A HREF="pattern.html#pattern">pattern</A>. If the <A HREF="options.html#'gdefault'">'gdefault'</A> option is on, this flag is on by default
and the [g] argument switches <A HREF="motion.html#it">it</A> off.
[i] Ignore <A HREF="#case">case</A> for the <A HREF="pattern.html#pattern">pattern</A>. The <A HREF="options.html#'ignorecase'">'ignorecase'</A> and <A HREF="options.html#'smartcase'">'smartcase'</A> <A HREF="options.html#options">options</A>
are not used.
{not in Vi}
[I] Don't ignore <A HREF="#case">case</A> for the <A HREF="pattern.html#pattern">pattern</A>. The <A HREF="options.html#'ignorecase'">'ignorecase'</A> and <A HREF="options.html#'smartcase'">'smartcase'</A>
<A HREF="options.html#options">options</A> are not used.
{not in Vi}
[n] Report the number of matches, <A HREF="diff.html#do">do</A> not actually substitute. The [c]
flag is ignored. The matches are reported <A HREF="motion.html#as">as</A> if <A HREF="options.html#'report'">'report'</A> is zero.
Useful to |<A HREF="tips.html#count-items">count-items</A>|.
[p] Print the line containing the last substitute.
[#] Like [p] and prepend the line number.
[l] Like [p] but print the text like |<A HREF="various.html#:list">:list</A>|.
[r] Only useful in combination with "<A HREF="#:&">:&</A>" or "<A HREF="#:s">:s</A>" without arguments. ":&r"
works the same way <A HREF="motion.html#as">as</A> "<A HREF="#:~">:~</A>": When the search <A HREF="pattern.html#pattern">pattern</A> is empty, use the
previously used search <A HREF="pattern.html#pattern">pattern</A> instead of the search <A HREF="pattern.html#pattern">pattern</A> from the
last substitute or "<A HREF="repeat.html#:global">:global</A>". If the last command that did a search
was a substitute or "<A HREF="repeat.html#:global">:global</A>", there is no effect. If the last
command was a search command such <A HREF="motion.html#as">as</A> "<A HREF="pattern.html#/">/</A>", use the <A HREF="pattern.html#pattern">pattern</A> from that
command.
For "<A HREF="#:s">:s</A>" with an argument this already happens:
<B> :s/blue/red/</B>
<B> /green</B>
<B> :s//red/ or :~ or :&r</B>
The last commands will replace "green" with "red".
<B> :s/blue/red/</B>
<B> /green</B>
<B> :&</B>
The last command will replace "blue" with "red".
{not in Vi}
Note that there is no flag to change the "magicness" of the <A HREF="pattern.html#pattern">pattern</A>. A
different command is used instead, or you can use |<A HREF="pattern.html#/\v">/\v</A>| and friends. The
reason is that the flags can only be found by skipping the <A HREF="pattern.html#pattern">pattern</A>, and in
order to skip the <A HREF="pattern.html#pattern">pattern</A> the "magicness" must be known. Catch 22!
If the {pattern} for the substitute command is empty, the command uses the
<A HREF="pattern.html#pattern">pattern</A> from the last substitute or "<A HREF="repeat.html#:global">:global</A>" command. If there is none, but
there is a previous search <A HREF="pattern.html#pattern">pattern</A>, that one is used. With the [r] flag, the
command uses the <A HREF="pattern.html#pattern">pattern</A> from the last substitute, "<A HREF="repeat.html#:global">:global</A>", or search
command.
If the {string} is omitted the substitute is done <A HREF="motion.html#as">as</A> if it's empty. Thus the
matched <A HREF="pattern.html#pattern">pattern</A> is deleted. The separator after {pattern} can also be left
out then. Example:
<B> :%s/TESTING</B>
This deletes "TESTING" from all lines, but only one per line.
For compatibility with <A HREF="intro.html#Vi">Vi</A> these two exceptions are allowed:
"\/{string}/" and "\?{string}?" <A HREF="diff.html#do">do</A> the same <A HREF="motion.html#as">as</A> "//{string}/r".
"\&{string}&" does the same <A HREF="motion.html#as">as</A> "//{string}/".
*<A NAME="E146"></A><B>E146</B>*
Instead of the '<A HREF="pattern.html#/">/</A>' which surrounds the <A HREF="pattern.html#pattern">pattern</A> and replacement string, you
can use any other single-byte character, but not an alphanumeric character,
'\', '"'' or '|'. This is useful if you want to include a '<A HREF="pattern.html#/">/</A>' in the search
<A HREF="pattern.html#pattern">pattern</A> or replacement string. Example:
<B> :s+/+//+</B>
For the definition of a pattern, see |<A HREF="pattern.html#pattern">pattern</A>|. In <A HREF="visual.html#Visual">Visual</A> block mode, use
|<A HREF="pattern.html#/\%V">/\%V</A>| in the <A HREF="pattern.html#pattern">pattern</A> to have the substitute work in the block only.
Otherwise <A HREF="motion.html#it">it</A> works on whole lines anyway.
*<A NAME="sub-replace-special"></A><B>sub-replace-special</B>* *<A NAME=":s\="></A><B>:s\=</B>*
When the {string} starts with "\=" <A HREF="motion.html#it">it</A> is evaluated <A HREF="motion.html#as">as</A> an <A HREF="eval.html#expression">expression</A>, see
|<A HREF="#sub-replace-expression">sub-replace-expression</A>|. You can use that for complex replacement or special
characters.
Otherwise these characters in {string} have a special meaning:
*<A NAME=":s%"></A><B>:s%</B>*
When {string} is equal to "<A HREF="motion.html#%">%</A>" and '<A HREF="pattern.html#/">/</A>' is included with the <A HREF="options.html#'cpoptions'">'cpoptions'</A> option,
then the {string} of the previous substitute command is used, see |<A HREF="options.html#cpo-/">cpo-/</A>|
<B><FONT COLOR="PURPLE">magic nomagic action </FONT></B>
<A HREF="#&">&</A> \& replaced with the whole matched <A HREF="pattern.html#pattern">pattern</A> *<A NAME="s/\&"></A><B>s/\&</B>*
\& <A HREF="#&">&</A> replaced with <A HREF="#&">&</A>
<A HREF="#\0">\0</A> replaced with the whole matched <A HREF="pattern.html#pattern">pattern</A> *<A NAME="\0"></A><B>\0</B>* *<A NAME="s/\0"></A><B>s/\0</B>*
\1 replaced with the matched <A HREF="pattern.html#pattern">pattern</A> in the first
pair of () *<A NAME="s/\1"></A><B>s/\1</B>*
\2 replaced with the matched <A HREF="pattern.html#pattern">pattern</A> in the second
pair of () *<A NAME="s/\2"></A><B>s/\2</B>*
.. .. *<A NAME="s/\3"></A><B>s/\3</B>*
\9 replaced with the matched <A HREF="pattern.html#pattern">pattern</A> in the ninth
pair of () *<A NAME="s/\9"></A><B>s/\9</B>*
~ \~ replaced with the {string} of the previous
substitute *<A NAME="s~"></A><B>s~</B>*
\~ ~ replaced with ~ *<A NAME="s/\~"></A><B>s/\~</B>*
\u next character made <A HREF="#uppercase">uppercase</A> *<A NAME="s/\u"></A><B>s/\u</B>*
\U following characters made <A HREF="#uppercase">uppercase</A>, until \E *<A NAME="s/\U"></A><B>s/\U</B>*
\l next character made <A HREF="#lowercase">lowercase</A> *<A NAME="s/\l"></A><B>s/\l</B>*
\L following characters made <A HREF="#lowercase">lowercase</A>, until \E *<A NAME="s/\L"></A><B>s/\L</B>*
\e end of \u, \U, \l and \L (NOTE: not <Esc>!) *<A NAME="s/\e"></A><B>s/\e</B>*
\E end of \u, \U, \l and \L *<A NAME="s/\E"></A><B>s/\E</B>*
<A HREF="motion.html#<CR>"><CR></A> split line in two at this point
(Type the <A HREF="motion.html#<CR>"><CR></A> <A HREF="motion.html#as">as</A> <A HREF="visual.html#CTRL-V">CTRL-V</A> <A HREF="intro.html#<Enter>"><Enter></A>) *<A NAME="s<CR>"></A><B>s<CR></B>*
\r idem *<A NAME="s/\r"></A><B>s/\r</B>*
\<CR> insert a <A HREF="intro.html#carriage-return">carriage-return</A> (CTRL-M)
(Type the <A HREF="motion.html#<CR>"><CR></A> <A HREF="motion.html#as">as</A> <A HREF="visual.html#CTRL-V">CTRL-V</A> <A HREF="intro.html#<Enter>"><Enter></A>) *<A NAME="s/\<CR>"></A><B>s/\<CR></B>*
\n insert a <A HREF="motion.html#<NL>"><NL></A> (<NUL> in the file)
(does NOT break the line) *<A NAME="s/\n"></A><B>s/\n</B>*
\b insert a <A HREF="motion.html#<BS>"><BS></A> *<A NAME="s/\b"></A><B>s/\b</B>*
\t insert a <A HREF="motion.html#<Tab>"><Tab></A> *<A NAME="s/\t"></A><B>s/\t</B>*
\\ insert a single <A HREF="intro.html#backslash">backslash</A> *<A NAME="s/\\"></A><B>s/\\</B>*
\x where <A HREF="#x">x</A> is any character not mentioned above:
Reserved for future expansion
The special meaning is also used inside the third argument {sub} of
the |<A HREF="eval.html#substitute()">substitute()</A>| function with the following exceptions:
- A <A HREF="motion.html#%">%</A> inserts a percent literally without regard to <A HREF="options.html#'cpoptions'">'cpoptions'</A>.
- magic is always set without regard to <A HREF="options.html#'magic'">'magic'</A>.
- A ~ inserts a tilde literally.
- <A HREF="motion.html#<CR>"><CR></A> and \r inserts a <A HREF="intro.html#carriage-return">carriage-return</A> (CTRL-M).
- \<CR> does not have a special meaning. it's just one of \x.
Examples:
<B> :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx"</B>
<B> :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb"</B>
<B> :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines)</B>
<B> :s/$/\^M/ modifies "abcde" to "abcde^M"</B>
<B> :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla"</B>
Note: In previous versions <A HREF="visual.html#CTRL-V">CTRL-V</A> was handled in a special way. Since this is
not <A HREF="intro.html#Vi">Vi</A> compatible, this was removed. Use a <A HREF="intro.html#backslash">backslash</A> instead.
<B><FONT COLOR="PURPLE">command text result </FONT></B>
:s/aa/a^Ma/ aa a<line-break>a
:s/aa/a\^Ma/ aa a^Ma
:s/aa/a\\^Ma/ aa a\<line-break>a
(you need to type <A HREF="visual.html#CTRL-V">CTRL-V</A> <A HREF="motion.html#<CR>"><CR></A> to get a ^M here)
The numbering of "\1", "\2" etc. is done based on which "\(" comes first in
the <A HREF="pattern.html#pattern">pattern</A> (going left to right). When a parentheses group matches several
times, the last one will be used for "\1", "\2", etc. Example:
<B> :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x"</B>
When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\),
either the first or second <A HREF="pattern.html#pattern">pattern</A> in parentheses did not match, so either
\1 or \2 is empty. Example:
<B> :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x"</B>
Substitute with an <A HREF="eval.html#expression">expression</A> *<A NAME="sub-replace-expression"></A><B>sub-replace-expression</B>*
*<A NAME="sub-replace-\="></A><B>sub-replace-\=</B>*
When the substitute string starts with "\=" the remainder is interpreted <A HREF="motion.html#as">as</A> an
<A HREF="eval.html#expression">expression</A>. This does not work recursively: a |<A HREF="eval.html#substitute()">substitute()</A>| function inside
the <A HREF="eval.html#expression">expression</A> cannot use "\=" for the substitute string.
The special meaning for characters <A HREF="motion.html#as">as</A> mentioned at |<A HREF="#sub-replace-special">sub-replace-special</A>| does
not apply except for "<A HREF="motion.html#<CR>"><CR></A>". A <A HREF="motion.html#<NL>"><NL></A> character is used <A HREF="motion.html#as">as</A> a line break, you
can get one with a double-quote string: "\n". Prepend a <A HREF="intro.html#backslash">backslash</A> to get a
real <A HREF="motion.html#<NL>"><NL></A> character (which will be a NUL in the file).
The "\=" <A HREF="intro.html#notation">notation</A> can also be used inside the third argument {sub} of
|<A HREF="eval.html#substitute()">substitute()</A>| function. In this <A HREF="#case">case</A>, the special meaning for characters <A HREF="motion.html#as">as</A>
mentioned at |<A HREF="#sub-replace-special">sub-replace-special</A>| does not apply at all. Especially, <A HREF="motion.html#<CR>"><CR></A> and
<A HREF="motion.html#<NL>"><NL></A> are interpreted not <A HREF="motion.html#as">as</A> a line break but <A HREF="motion.html#as">as</A> a <A HREF="intro.html#carriage-return">carriage-return</A> and a
new-line respectively.
When the result is a |<A HREF="eval.html#List">List</A>| then the items are joined with separating line
breaks. Thus each item becomes a line, except that they can contain line
breaks themselves.
The whole matched text can be accessed with "submatch(0)". The text matched
with the first pair of () with "submatch(1)". Likewise for further
sub-matches in ().
Be careful: The separation character must not appear in the <A HREF="eval.html#expression">expression</A>!
Consider using a character like "<A HREF="repeat.html#@">@</A>" or "<A HREF="cmdline.html#:">:</A>". There is no problem if the result
of the <A HREF="eval.html#expression">expression</A> contains the separation character.
Examples:
<B> :s@\n@\="\r" . expand("$HOME") . "\r"@</B>
This replaces an end-of-line with a new line containing the value of <A HREF="options.html#$HOME">$HOME</A>.
<B> s/E/\="\<Char-0x20ac>"/g</B>
This replaces each '<A HREF="motion.html#E">E</A>' character with a euro sign. Read more in |<A HREF="map.html#<Char->"><Char-></A>|.
4.3 Search and replace *<A NAME="search-replace"></A><B>search-replace</B>*
*<A NAME=":pro"></A><B>:pro</B>* *<A NAME=":promptfind"></A><B>:promptfind</B>*
:promptf[ind] [string]
Put up a Search <A HREF="gui_w32.html#dialog">dialog</A>. When [string] is given, <A HREF="motion.html#it">it</A> is
used <A HREF="motion.html#as">as</A> the initial search string.
{only for <A HREF="os_win32.html#Win32">Win32</A>, <A HREF="gui_x11.html#Motif">Motif</A> and <A HREF="gui_x11.html#GTK">GTK</A> GUI}
*<A NAME=":promptr"></A><B>:promptr</B>* *<A NAME=":promptrepl"></A><B>:promptrepl</B>*
:promptr[epl] [string]
Put up a Search/Replace <A HREF="gui_w32.html#dialog">dialog</A>. When [string] is
given, <A HREF="motion.html#it">it</A> is used <A HREF="motion.html#as">as</A> the initial search string.
{only for <A HREF="os_win32.html#Win32">Win32</A>, <A HREF="gui_x11.html#Motif">Motif</A> and <A HREF="gui_x11.html#GTK">GTK</A> GUI}
4.4 Changing tabs *<A NAME="change-tabs"></A><B>change-tabs</B>*
*<A NAME=":ret"></A><B>:ret</B>* *<A NAME=":retab"></A><B>:retab</B>*
:[range]ret[ab][!] [new_tabstop]
<A HREF="insert.html#Replace">Replace</A> all sequences of <A HREF="pattern.html#white-space">white-space</A> containing a
<A HREF="motion.html#<Tab>"><Tab></A> with new strings of <A HREF="pattern.html#white-space">white-space</A> using the new
tabstop value given. If you <A HREF="diff.html#do">do</A> not specify a new
tabstop size or <A HREF="motion.html#it">it</A> is zero, Vim uses the current value
of <A HREF="options.html#'tabstop'">'tabstop'</A>.
The current value of <A HREF="options.html#'tabstop'">'tabstop'</A> is always used to
compute the width of existing tabs.
With !, Vim also replaces strings of only normal
spaces with tabs where appropriate.
With <A HREF="options.html#'expandtab'">'expandtab'</A> on, Vim replaces all tabs with the
appropriate number of spaces.
This command sets <A HREF="options.html#'tabstop'">'tabstop'</A> to the new value given,
and if performed on the whole file, which is default,
should not make any visible change.
Careful: This command modifies any <A HREF="motion.html#<Tab>"><Tab></A> characters
inside of strings in a C program. Use "\t" to avoid
this (that's a good habit anyway).
":retab!" may also change a sequence of spaces by
<A HREF="motion.html#<Tab>"><Tab></A> characters, which can mess up a <A HREF="eval.html#printf()">printf()</A>.
{not in Vi}
Not available when |<A HREF="various.html#+ex_extra">+ex_extra</A>| feature was disabled at
compile time.
*<A NAME="retab-example"></A><B>retab-example</B>*
Example for using autocommands and "<A HREF="#:retab">:retab</A>" to edit a file which is stored
with tabstops at 8 but edited with tabstops set at 4. Warning: white space
inside of strings can change! Also see <A HREF="options.html#'softtabstop'">'softtabstop'</A> option.
<B> :auto BufReadPost *.xx retab! 4</B>
<B> :auto BufWritePre *.xx retab! 8</B>
<B> :auto BufWritePost *.xx retab! 4</B>
<B> :auto BufNewFile *.xx set ts=4</B>
==============================================================================
5. Copying and moving text *<A NAME="copy-move"></A><B>copy-move</B>*
*<A NAME="quote"></A><B>quote</B>*
"{a-zA-Z0-9.%#:-"} Use <A HREF="sponsor.html#register">register</A> {a-zA-Z0-9.%#:-"} for next delete, <A HREF="#yank">yank</A>
or put (use <A HREF="#uppercase">uppercase</A> character to append with
delete and <A HREF="#yank">yank</A>) ({.%#:} only work with put).
*<A NAME=":reg"></A><B>:reg</B>* *<A NAME=":registers"></A><B>:registers</B>*
:reg[isters] Display the contents of all numbered and named
<A HREF="#registers">registers</A>. If a <A HREF="sponsor.html#register">register</A> is written to for |<A HREF="various.html#:redir">:redir</A>|
<A HREF="motion.html#it">it</A> will not be listed.
{not in Vi}
:reg[isters] {arg} Display the contents of the numbered and named
<A HREF="#registers">registers</A> that are mentioned in {arg}. For example:
<B> :dis 1a</B>
to display <A HREF="#registers">registers</A> '1' and '<A HREF="insert.html#a">a</A>'. Spaces are allowed
in {arg}. {not in Vi}
*<A NAME=":di"></A><B>:di</B>* *<A NAME=":display"></A><B>:display</B>*
:di[splay] [arg] Same <A HREF="motion.html#as">as</A> <A HREF="#:registers">:registers</A>. {not in Vi}
*<A NAME="y"></A><B>y</B>* *<A NAME="yank"></A><B>yank</B>*
["x]y{motion} Yank <A HREF="intro.html#{motion}">{motion}</A> text [into <A HREF="sponsor.html#register">register</A> x]. When no
characters are to be yanked (e.g., "y0" in column 1),
this is an error when <A HREF="options.html#'cpoptions'">'cpoptions'</A> includes the '<A HREF="motion.html#E">E</A>'
flag.
*<A NAME="yy"></A><B>yy</B>*
["x]yy Yank <A HREF="intro.html#[count]">[count]</A> lines [into <A HREF="sponsor.html#register">register</A> x] |<A HREF="motion.html#linewise">linewise</A>|.
*<A NAME="Y"></A><B>Y</B>*
["x]Y <A HREF="#yank">yank</A> <A HREF="intro.html#[count]">[count]</A> lines [into <A HREF="sponsor.html#register">register</A> x] (synonym for
<A HREF="#yy">yy</A>, |<A HREF="motion.html#linewise">linewise</A>|). If you like "<A HREF="#Y">Y</A>" to work from the
cursor to the end of line (which is more logical,
but not Vi-compatible) use "<A HREF="map.html#:map">:map</A> <A HREF="#Y">Y</A> y$".
*<A NAME="v_y"></A><B>v_y</B>*
{Visual}["x]y Yank the highlighted text [into <A HREF="sponsor.html#register">register</A> x] (for
<A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
*<A NAME="v_Y"></A><B>v_Y</B>*
{Visual}["x]Y Yank the highlighted lines [into <A HREF="sponsor.html#register">register</A> x] (for
<A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
*<A NAME=":y"></A><B>:y</B>* *<A NAME=":yank"></A><B>:yank</B>* *<A NAME="E850"></A><B>E850</B>*
:[range]y[ank] [x] Yank <A HREF="cmdline.html#[range]">[range]</A> lines [into <A HREF="sponsor.html#register">register</A> x]. Yanking to the
"* or "<A HREF="motion.html#+">+</A> <A HREF="#registers">registers</A> is possible only when the
|<A HREF="various.html#+clipboard">+clipboard</A>| feature is included.
:[range]y[ank] [x] {count}
Yank {count} lines, starting with last line number
in <A HREF="cmdline.html#[range]">[range]</A> (default: current line |<A HREF="cmdline.html#cmdline-ranges">cmdline-ranges</A>|),
[into <A HREF="sponsor.html#register">register</A> x].
*<A NAME="p"></A><B>p</B>* *<A NAME="put"></A><B>put</B>* *<A NAME="E353"></A><B>E353</B>*
["x]p Put the text [from <A HREF="sponsor.html#register">register</A> x] after the cursor
<A HREF="intro.html#[count]">[count]</A> times. {Vi: no count}
*<A NAME="P"></A><B>P</B>*
["x]P Put the text [from <A HREF="sponsor.html#register">register</A> x] before the cursor
<A HREF="intro.html#[count]">[count]</A> times. {Vi: no count}
*<A NAME="<MiddleMouse>"></A><B><MiddleMouse></B>*
["x]<MiddleMouse> Put the text from a <A HREF="sponsor.html#register">register</A> before the cursor <A HREF="intro.html#[count]">[count]</A>
times. Uses the "* <A HREF="sponsor.html#register">register</A>, unless another is
specified.
Leaves the cursor at the end of the new text.
Using the mouse only works when <A HREF="options.html#'mouse'">'mouse'</A> contains '<A HREF="pattern.html#n">n</A>'
or '<A HREF="insert.html#a">a</A>'.
{not in Vi}
If you have a scrollwheel and often accidentally paste
text, you can use these mappings to disable the
pasting with the middle mouse button:
<B> :map <MiddleMouse> <Nop></B>
<B> :imap <MiddleMouse> <Nop></B>
You might want to disable the multi-click versions
too, see |<A HREF="term.html#double-click">double-click</A>|.
*<A NAME="gp"></A><B>gp</B>*
["x]gp Just like "<A HREF="#p">p</A>", but leave the cursor just after the new
text. {not in Vi}
*<A NAME="gP"></A><B>gP</B>*
["x]gP Just like "<A HREF="#P">P</A>", but leave the cursor just after the new
text. {not in Vi}
*<A NAME=":pu"></A><B>:pu</B>* *<A NAME=":put"></A><B>:put</B>*
:[line]pu[t] [x] Put the text [from <A HREF="sponsor.html#register">register</A> x] after [line] (default
current line). This always works |<A HREF="motion.html#linewise">linewise</A>|, thus
this command can be used to put a yanked block <A HREF="motion.html#as">as</A> new
lines.
The cursor is left on the first non-blank in the last
new line.
The <A HREF="sponsor.html#register">register</A> can also be '<A HREF="#=">=</A>' followed by an optional
<A HREF="eval.html#expression">expression</A>. The <A HREF="eval.html#expression">expression</A> continues until the end of
the command. You need to <A HREF="intro.html#escape">escape</A> the '|' and '"''
characters to prevent them from terminating the
command. Example:
<B> :put ='path' . \",/test\"</B>
If there is no <A HREF="eval.html#expression">expression</A> after '<A HREF="#=">=</A>', Vim uses the
previous <A HREF="eval.html#expression">expression</A>. You can see <A HREF="motion.html#it">it</A> with ":dis =".
:[line]pu[t]! [x] Put the text [from <A HREF="sponsor.html#register">register</A> x] before [line] (default
current line).
["x]]p or *<A NAME="]p"></A><B>]p</B>* *<A NAME="]<MiddleMouse>"></A><B>]<MiddleMouse></B>*
["x]]<MiddleMouse> Like "<A HREF="#p">p</A>", but adjust the indent to the current line.
Using the mouse only works when <A HREF="options.html#'mouse'">'mouse'</A> contains '<A HREF="pattern.html#n">n</A>'
or '<A HREF="insert.html#a">a</A>'. {not in Vi}
["x][P or *<A NAME="[P"></A><B>[P</B>*
["x]]P or *<A NAME="]P"></A><B>]P</B>*
["x][p or *<A NAME="[p"></A><B>[p</B>* *<A NAME="[<MiddleMouse>"></A><B>[<MiddleMouse></B>*
["x][<MiddleMouse> Like "<A HREF="#P">P</A>", but adjust the indent to the current line.
Using the mouse only works when <A HREF="options.html#'mouse'">'mouse'</A> contains '<A HREF="pattern.html#n">n</A>'
or '<A HREF="insert.html#a">a</A>'. {not in Vi}
You can use these commands to copy text from one place to another. Do this
by first getting the text into a <A HREF="sponsor.html#register">register</A> with a <A HREF="#yank">yank</A>, delete or change
command, then <A HREF="insert.html#inserting">inserting</A> the <A HREF="sponsor.html#register">register</A> contents with a put command. You can
also use these commands to move text from one file to another, because Vim
preserves all <A HREF="#registers">registers</A> when <A HREF="#changing">changing</A> <A HREF="windows.html#buffers">buffers</A> (the <A HREF="editing.html#CTRL-^">CTRL-^</A> command is a quick
way to toggle between two files).
*<A NAME="linewise-register"></A><B>linewise-register</B>* *<A NAME="characterwise-register"></A><B>characterwise-register</B>*
You can repeat the put commands with "<A HREF="repeat.html#.">.</A>" (except for <A HREF="#:put">:put</A>) and <A HREF="undo.html#undo">undo</A> them. If
the command that was used to get the text into the <A HREF="sponsor.html#register">register</A> was |<A HREF="motion.html#linewise">linewise</A>|,
Vim inserts the text below ("p") or above ("P") the line where the cursor is.
Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With
the "<A HREF="#:put">:put</A>" command, Vim always inserts the text in the next line. You can
exchange two characters with the command sequence "xp". You can exchange two
lines with the command sequence "ddp". You can exchange two words with the
command sequence "deep" (start with the cursor in the blank space before the
first <A HREF="motion.html#word">word</A>). You can use the "<A HREF="motion.html#']">']</A>" or "<A HREF="motion.html#`]">`]</A>" command after the put command to
move the cursor to the end of the inserted text, or use "<A HREF="motion.html#'[">'[</A>" or "<A HREF="motion.html#`[">`[</A>" to move
the cursor to the start.
*<A NAME="put-Visual-mode"></A><B>put-Visual-mode</B>* *<A NAME="v_p"></A><B>v_p</B>* *<A NAME="v_P"></A><B>v_P</B>*
When using a put command like |<A HREF="#p">p</A>| or |<A HREF="#P">P</A>| in <A HREF="visual.html#Visual">Visual</A> mode, Vim will try to
replace the selected text with the contents of the <A HREF="sponsor.html#register">register</A>. Whether this
works well depends on the type of selection and the type of the text in the
<A HREF="sponsor.html#register">register</A>. With blockwise selection <A HREF="motion.html#it">it</A> also depends on the size of the block
and whether the corners are on an existing character. (Implementation detail:
<A HREF="motion.html#it">it</A> actually works by first putting the <A HREF="sponsor.html#register">register</A> after the selection and then
<A HREF="#deleting">deleting</A> the selection.)
The previously selected text is put in the unnamed <A HREF="sponsor.html#register">register</A>. If you want to
put the same text into a <A HREF="visual.html#Visual">Visual</A> selection several times you need to use
another <A HREF="sponsor.html#register">register</A>. E.g., <A HREF="#yank">yank</A> the text to copy, Visually select the text to
replace and use "0p . You can repeat this <A HREF="motion.html#as">as</A> many times <A HREF="motion.html#as">as</A> you like, the
unnamed <A HREF="sponsor.html#register">register</A> will be changed each time.
*<A NAME="blockwise-register"></A><B>blockwise-register</B>*
If you use a blockwise <A HREF="visual.html#Visual">Visual</A> mode command to get the text into the <A HREF="sponsor.html#register">register</A>,
the block of text will be inserted before ("P") or after ("p") the cursor
column in the current and next lines. Vim makes the whole block of text start
in the same column. Thus the inserted text looks the same <A HREF="motion.html#as">as</A> when <A HREF="motion.html#it">it</A> was
yanked or deleted. Vim may replace some <A HREF="motion.html#<Tab>"><Tab></A> characters with spaces to make
this happen. However, if the width of the block is not a multiple of a <A HREF="motion.html#<Tab>"><Tab></A>
width and the text after the inserted block contains <Tab>s, that text may be
misaligned.
Note that after a <A HREF="motion.html#characterwise">characterwise</A> <A HREF="#yank">yank</A> command, Vim leaves the cursor on the
first yanked character that is closest to the start of the buffer. This means
that "yl" doesn't move the cursor, but "yh" moves the cursor one character
left.
Rationale: In <A HREF="intro.html#Vi">Vi</A> the "<A HREF="#y">y</A>" command followed by a backwards motion would
sometimes not move the cursor to the first yanked character,
because redisplaying was skipped. In Vim <A HREF="motion.html#it">it</A> always moves to
the first character, <A HREF="motion.html#as">as</A> specified by <A HREF="intro.html#Posix">Posix</A>.
With a <A HREF="motion.html#linewise">linewise</A> <A HREF="#yank">yank</A> command the cursor is put in the first line, but the
column is unmodified, thus <A HREF="motion.html#it">it</A> may not be on the first yanked character.
There are nine types of <A HREF="#registers">registers</A>: *<A NAME="registers"></A><B>registers</B>* *<A NAME="E354"></A><B>E354</B>*
1. The unnamed <A HREF="sponsor.html#register">register</A> ""
2. 10 numbered <A HREF="#registers">registers</A> "<A HREF="motion.html#0">0</A> to "9
3. The small delete <A HREF="sponsor.html#register">register</A> "<A HREF="motion.html#-">-</A>
4. 26 named <A HREF="#registers">registers</A> "a to "<A HREF="index.html#z">z</A> or "A to "Z
5. four read-only <A HREF="#registers">registers</A> "<A HREF="cmdline.html#:,">:,</A> "., "<A HREF="motion.html#%">%</A> and "<A HREF="pattern.html##">#</A>
6. the <A HREF="eval.html#expression">expression</A> <A HREF="sponsor.html#register">register</A> "<A HREF="#=">=</A>
7. The selection and drop <A HREF="#registers">registers</A> "*, "<A HREF="motion.html#+">+</A> and "<A HREF="#~">~</A>
8. The black hole <A HREF="sponsor.html#register">register</A> "<A HREF="motion.html#_">_</A>
9. Last search <A HREF="pattern.html#pattern">pattern</A> <A HREF="sponsor.html#register">register</A> "<A HREF="pattern.html#/">/</A>
1. Unnamed <A HREF="sponsor.html#register">register</A> "" *<A NAME="quote_quote"></A><B>quote_quote</B>* *<A NAME="quotequote"></A><B>quotequote</B>*
Vim fills this <A HREF="sponsor.html#register">register</A> with text deleted with the "<A HREF="#d">d</A>", "<A HREF="#c">c</A>", "<A HREF="#s">s</A>", "<A HREF="#x">x</A>" commands
or copied with the <A HREF="#yank">yank</A> "<A HREF="#y">y</A>" command, regardless of whether or not a specific
<A HREF="sponsor.html#register">register</A> was used (e.g. "xdd). This is like the unnamed <A HREF="sponsor.html#register">register</A> is pointing
to the last used <A HREF="sponsor.html#register">register</A>. Thus when appending using an <A HREF="#uppercase">uppercase</A> <A HREF="sponsor.html#register">register</A>
name, the unnamed <A HREF="sponsor.html#register">register</A> contains the same text <A HREF="motion.html#as">as</A> the named <A HREF="sponsor.html#register">register</A>.
An exception is the '<A HREF="motion.html#_">_</A>' <A HREF="sponsor.html#register">register</A>: "_dd does not store the deleted text in any
<A HREF="sponsor.html#register">register</A>.
Vim uses the contents of the unnamed <A HREF="sponsor.html#register">register</A> for any put command (p or <A HREF="#P">P</A>)
which does not specify a <A HREF="sponsor.html#register">register</A>. Additionally you can access <A HREF="motion.html#it">it</A> with the
name '"''. This means you have to type two double <A HREF="quotes.html#quotes">quotes</A>. Writing to the ""
<A HREF="sponsor.html#register">register</A> writes to <A HREF="sponsor.html#register">register</A> "0.
{Vi: <A HREF="sponsor.html#register">register</A> contents are lost when <A HREF="#changing">changing</A> files, no '"''}
2. Numbered <A HREF="#registers">registers</A> "<A HREF="motion.html#0">0</A> to "9 *<A NAME="quote_number"></A><B>quote_number</B>* *<A NAME="quote0"></A><B>quote0</B>* *<A NAME="quote1"></A><B>quote1</B>*
*<A NAME="quote2"></A><B>quote2</B>* *<A NAME="quote3"></A><B>quote3</B>* *<A NAME="quote4"></A><B>quote4</B>* *<A NAME="quote9"></A><B>quote9</B>*
Vim fills these <A HREF="#registers">registers</A> with text from <A HREF="#yank">yank</A> and delete commands.
Numbered <A HREF="sponsor.html#register">register</A> 0 contains the text from the most recent <A HREF="#yank">yank</A> command,
unless the command specified another <A HREF="sponsor.html#register">register</A> with ["x].
Numbered <A HREF="sponsor.html#register">register</A> 1 contains the text deleted by the most recent delete or
change command, unless the command specified another <A HREF="sponsor.html#register">register</A> or the text is
<A HREF="various.html#less">less</A> than one line (the small delete <A HREF="sponsor.html#register">register</A> is used then). An exception is
made for the delete <A HREF="motion.html#operator">operator</A> with these <A HREF="intro.html#movement">movement</A> commands: |<A HREF="motion.html#%">%</A>|, |<A HREF="motion.html#(">(</A>|, |<A HREF="motion.html#)">)</A>|, |<A HREF="motion.html#`">`</A>|,
|<A HREF="pattern.html#/">/</A>|, |<A HREF="pattern.html#?">?</A>|, |<A HREF="pattern.html#n">n</A>|, |<A HREF="pattern.html#N">N</A>|, |<A HREF="motion.html#{">{</A>| and |<A HREF="motion.html#}">}</A>|. Register "1 is always used then (this is <A HREF="intro.html#Vi">Vi</A>
compatible). The "<A HREF="motion.html#-">-</A> <A HREF="sponsor.html#register">register</A> is used <A HREF="motion.html#as">as</A> well if the delete is within a line.
With each successive deletion or change, Vim shifts the previous contents
of <A HREF="sponsor.html#register">register</A> 1 into <A HREF="sponsor.html#register">register</A> 2, 2 into 3, and so forth, losing the previous
contents of <A HREF="sponsor.html#register">register</A> 9.
{Vi: numbered <A HREF="sponsor.html#register">register</A> contents are lost when <A HREF="#changing">changing</A> files; <A HREF="sponsor.html#register">register</A> 0 does
not exist}
3. Small delete <A HREF="sponsor.html#register">register</A> "<A HREF="motion.html#-">-</A> *<A NAME="quote_-"></A><B>quote_-</B>* *<A NAME="quote-"></A><B>quote-</B>*
This <A HREF="sponsor.html#register">register</A> contains text from commands that delete <A HREF="various.html#less">less</A> than one line,
except when the command specifies a <A HREF="sponsor.html#register">register</A> with ["x].
{not in Vi}
4. Named <A HREF="#registers">registers</A> "a to "<A HREF="index.html#z">z</A> or "A to "Z *<A NAME="quote_alpha"></A><B>quote_alpha</B>* *<A NAME="quotea"></A><B>quotea</B>*
Vim fills these <A HREF="#registers">registers</A> only when you say so. Specify them <A HREF="motion.html#as">as</A> <A HREF="#lowercase">lowercase</A>
letters to replace their previous contents or <A HREF="motion.html#as">as</A> <A HREF="#uppercase">uppercase</A> letters to append
to their previous contents. When the '<A HREF="#>">></A>' flag is present in <A HREF="options.html#'cpoptions'">'cpoptions'</A> then
a line break is inserted before the appended text.
5. Read-only <A HREF="#registers">registers</A> "<A HREF="cmdline.html#:,">:,</A> "., "<A HREF="motion.html#%">%</A> and "<A HREF="pattern.html##">#</A>
These are '<A HREF="motion.html#%">%</A>', '<A HREF="pattern.html##">#</A>', '<A HREF="cmdline.html#:">:</A>' and '<A HREF="repeat.html#.">.</A>'. You can use them only with the "<A HREF="#p">p</A>", "<A HREF="#P">P</A>",
and "<A HREF="#:put">:put</A>" commands and with <A HREF="undo.html#CTRL-R">CTRL-R</A>. {not in Vi}
*<A NAME="quote_."></A><B>quote_.</B>* *<A NAME="quote."></A><B>quote.</B>* *<A NAME="E29"></A><B>E29</B>*
". Contains the last inserted text (the same <A HREF="motion.html#as">as</A> what is inserted
with the insert mode commands <A HREF="#CTRL-A">CTRL-A</A> and CTRL-@). Note: this
doesn't work with <A HREF="undo.html#CTRL-R">CTRL-R</A> on the command-line. It works a bit
differently, like <A HREF="insert.html#inserting">inserting</A> the text instead of putting <A HREF="motion.html#it">it</A>
('textwidth' and other <A HREF="options.html#options">options</A> affect what is inserted).
*<A NAME="quote_%"></A><B>quote_%</B>* *<A NAME="quote%"></A><B>quote%</B>*
"<A HREF="motion.html#%">%</A> Contains the name of the current file.
*<A NAME="quote_#"></A><B>quote_#</B>* *<A NAME="quote#"></A><B>quote#</B>*
"<A HREF="pattern.html##">#</A> Contains the name of the alternate file.
*<A NAME="quote_:"></A><B>quote_:</B>* *<A NAME="quote:"></A><B>quote:</B>* *<A NAME="E30"></A><B>E30</B>*
": Contains the most recent executed command-line. Example: Use
"<A HREF="repeat.html#@:">@:</A>" to repeat the previous command-line command.
The command-line is only stored in this <A HREF="sponsor.html#register">register</A> when at least
one character of <A HREF="motion.html#it">it</A> was typed. Thus <A HREF="motion.html#it">it</A> remains unchanged if
the command was completely from a <A HREF="map.html#mapping">mapping</A>.
{not available when compiled without the |<A HREF="various.html#+cmdline_hist">+cmdline_hist</A>|
feature}
6. Expression <A HREF="sponsor.html#register">register</A> "<A HREF="#=">=</A> *<A NAME="quote_="></A><B>quote_=</B>* *<A NAME="quote="></A><B>quote=</B>* *<A NAME="@="></A><B>@=</B>*
This is not really a <A HREF="sponsor.html#register">register</A> that stores text, but is a way to use an
<A HREF="eval.html#expression">expression</A> in commands which use a <A HREF="sponsor.html#register">register</A>. The <A HREF="eval.html#expression">expression</A> <A HREF="sponsor.html#register">register</A> is
read-only; you cannot put text into <A HREF="motion.html#it">it</A>. After the '<A HREF="#=">=</A>', the cursor moves to
the command-line, where you can enter any expression (see |<A HREF="eval.html#expression">expression</A>|). All
normal command-line editing commands are available, including a special
<A HREF="cmdline.html#history">history</A> for expressions. When you end the command-line by typing <A HREF="motion.html#<CR>"><CR></A>, Vim
computes the result of the <A HREF="eval.html#expression">expression</A>. If you end <A HREF="motion.html#it">it</A> with <A HREF="intro.html#<Esc>"><Esc></A>, Vim abandons
the <A HREF="eval.html#expression">expression</A>. If you <A HREF="diff.html#do">do</A> not enter an <A HREF="eval.html#expression">expression</A>, Vim uses the previous
<A HREF="eval.html#expression">expression</A> (like with the "<A HREF="pattern.html#/">/</A>" command).
The <A HREF="eval.html#expression">expression</A> must evaluate to a String. A <A HREF="eval.html#Number">Number</A> is always automatically
converted to a String. For the "<A HREF="#p">p</A>" and "<A HREF="#:put">:put</A>" command, if the result is a
<A HREF="eval.html#Float">Float</A> it's converted into a String. If the result is a <A HREF="eval.html#List">List</A> each element is
turned into a String and used <A HREF="motion.html#as">as</A> a line. A <A HREF="eval.html#Dictionary">Dictionary</A> or FuncRef results in
an error message (use <A HREF="eval.html#string()">string()</A> to convert).
If the "<A HREF="#=">=</A> <A HREF="sponsor.html#register">register</A> is used for the "<A HREF="#p">p</A>" command, the String is split up at <A HREF="motion.html#<NL>"><NL></A>
characters. If the String ends in a <A HREF="motion.html#<NL>"><NL></A>, <A HREF="motion.html#it">it</A> is regarded <A HREF="motion.html#as">as</A> a <A HREF="motion.html#linewise">linewise</A>
<A HREF="sponsor.html#register">register</A>. {not in Vi}
7. Selection and drop <A HREF="#registers">registers</A> "*, "<A HREF="motion.html#+">+</A> and "<A HREF="#~">~</A>
Use these <A HREF="#registers">registers</A> for storing and retrieving the selected text for the <A HREF="gui.html#GUI">GUI</A>.
See |<A HREF="gui.html#quotestar">quotestar</A>| and |<A HREF="gui_x11.html#quoteplus">quoteplus</A>|. When the <A HREF="gui.html#clipboard">clipboard</A> is not available or not
working, the unnamed <A HREF="sponsor.html#register">register</A> is used instead. For <A HREF="os_unix.html#Unix">Unix</A> systems the <A HREF="gui.html#clipboard">clipboard</A>
is only available when the |<A HREF="various.html#+xterm_clipboard">+xterm_clipboard</A>| feature is present. {not in Vi}
Note that there is only a distinction between "* and "<A HREF="motion.html#+">+</A> for <A HREF="options.html#X11">X11</A> systems. For
an explanation of the difference, see |<A HREF="gui_x11.html#x11-selection">x11-selection</A>|. Under <A HREF="os_win32.html#MS-Windows">MS-Windows</A>, use
of "* and "<A HREF="motion.html#+">+</A> is actually synonymous and refers to the |<A HREF="gui_w32.html#gui-clipboard">gui-clipboard</A>|.
*<A NAME="quote_~"></A><B>quote_~</B>* *<A NAME="quote~"></A><B>quote~</B>* *<A NAME="<Drop>"></A><B><Drop></B>*
The read-only "<A HREF="#~">~</A> <A HREF="sponsor.html#register">register</A> stores the dropped text from the last drag'n'drop
operation. When something has been dropped onto Vim, the "<A HREF="#~">~</A> <A HREF="sponsor.html#register">register</A> is
filled in and the <A HREF="#<Drop>"><Drop></A> pseudo key is sent for notification. You can remap
this key if you want; the default action (for all modes) is to insert the
contents of the "<A HREF="#~">~</A> <A HREF="sponsor.html#register">register</A> at the cursor position. {not in Vi}
{only available when compiled with the |<A HREF="various.html#+dnd">+dnd</A>| feature, currently only with the
<A HREF="gui_x11.html#GTK">GTK</A> GUI}
Note: The "<A HREF="#~">~</A> <A HREF="sponsor.html#register">register</A> is only used when dropping plain text onto Vim.
Drag'n'drop of URI lists is handled internally.
8. Black hole <A HREF="sponsor.html#register">register</A> "<A HREF="motion.html#_">_</A> *<A NAME="quote_"></A><B>quote_</B>*
When <A HREF="editing.html#writing">writing</A> to this <A HREF="sponsor.html#register">register</A>, nothing happens. This can be used to delete
text without affecting the normal <A HREF="#registers">registers</A>. When reading from this <A HREF="sponsor.html#register">register</A>,
nothing is returned. {not in Vi}
9. Last search <A HREF="pattern.html#pattern">pattern</A> <A HREF="sponsor.html#register">register</A> "<A HREF="pattern.html#/">/</A> *quote_/* *quote/*
Contains the most recent <A HREF="pattern.html#search-pattern">search-pattern</A>. This is used for "<A HREF="pattern.html#n">n</A>" and <A HREF="options.html#'hlsearch'">'hlsearch'</A>.
It is writable with "<A HREF="eval.html#:let">:let</A>", you can change <A HREF="motion.html#it">it</A> to have <A HREF="options.html#'hlsearch'">'hlsearch'</A> highlight
other matches without actually searching. You can't <A HREF="#yank">yank</A> or delete into this
<A HREF="sponsor.html#register">register</A>. The search direction is available in |<A HREF="eval.html#v:searchforward">v:searchforward</A>|.
Note that the valued is restored when returning from a function
|<A HREF="eval.html#function-search-undo">function-search-undo</A>|.
{not in Vi}
*<A NAME="@/"></A><B>@/</B>*
You can write to a <A HREF="sponsor.html#register">register</A> with a ":let" command |<A HREF="eval.html#:let-@">:let-@</A>|. Example:
<B> :let @/ = "the"</B>
If you use a put command without specifying a <A HREF="sponsor.html#register">register</A>, Vim uses the <A HREF="sponsor.html#register">register</A>
that was last filled (this is also the contents of the unnamed <A HREF="sponsor.html#register">register</A>). If
you are confused, use the ":dis" command to find out what Vim will put (this
command displays all named and numbered <A HREF="#registers">registers</A>; the unnamed <A HREF="sponsor.html#register">register</A> is
labelled '"'').
The next three commands always work on whole lines.
:[range]co[py] <A HREF="cmdline.html#{address}">{address}</A> *<A NAME=":co"></A><B>:co</B>* *<A NAME=":copy"></A><B>:copy</B>*
Copy the lines given by <A HREF="cmdline.html#[range]">[range]</A> to below the line
given by <A HREF="cmdline.html#{address}">{address}</A>.
*<A NAME=":t"></A><B>:t</B>*
<A HREF="#:t">:t</A> Synonym for copy.
:[range]m[ove] <A HREF="cmdline.html#{address}">{address}</A> *<A NAME=":m"></A><B>:m</B>* *<A NAME=":mo"></A><B>:mo</B>* *<A NAME=":move"></A><B>:move</B>* *<A NAME="E134"></A><B>E134</B>*
Move the lines given by <A HREF="cmdline.html#[range]">[range]</A> to below the line
given by <A HREF="cmdline.html#{address}">{address}</A>.
==============================================================================
6. Formatting text *<A NAME="formatting"></A><B>formatting</B>*
:[range]ce[nter] [width] *<A NAME=":ce"></A><B>:ce</B>* *<A NAME=":center"></A><B>:center</B>*
Center lines in <A HREF="cmdline.html#[range]">[range]</A> between [width] columns
(default <A HREF="options.html#'textwidth'">'textwidth'</A> or 80 when <A HREF="options.html#'textwidth'">'textwidth'</A> is 0).
{not in Vi}
Not available when |<A HREF="various.html#+ex_extra">+ex_extra</A>| feature was disabled at
compile time.
:[range]ri[ght] [width] *<A NAME=":ri"></A><B>:ri</B>* *<A NAME=":right"></A><B>:right</B>*
Right-align lines in <A HREF="cmdline.html#[range]">[range]</A> at [width] columns
(default <A HREF="options.html#'textwidth'">'textwidth'</A> or 80 when <A HREF="options.html#'textwidth'">'textwidth'</A> is 0).
{not in Vi}
Not available when |<A HREF="various.html#+ex_extra">+ex_extra</A>| feature was disabled at
compile time.
*<A NAME=":le"></A><B>:le</B>* *<A NAME=":left"></A><B>:left</B>*
:[range]le[ft] [indent]
Left-align lines in <A HREF="cmdline.html#[range]">[range]</A>. Sets the indent in the
lines to [indent] (default 0). {not in Vi}
Not available when |<A HREF="various.html#+ex_extra">+ex_extra</A>| feature was disabled at
compile time.
*<A NAME="gq"></A><B>gq</B>*
gq{motion} Format the lines that <A HREF="intro.html#{motion}">{motion}</A> moves over.
Formatting is done with one of three methods:
1. If <A HREF="options.html#'formatexpr'">'formatexpr'</A> is not empty the <A HREF="eval.html#expression">expression</A> is
evaluated. This can differ for each buffer.
2. If <A HREF="options.html#'formatprg'">'formatprg'</A> is not empty an external program
is used.
3. Otherwise <A HREF="#formatting">formatting</A> is done internally.
In the third <A HREF="#case">case</A> the <A HREF="options.html#'textwidth'">'textwidth'</A> option controls the
length of each formatted line (see below).
If the <A HREF="options.html#'textwidth'">'textwidth'</A> option is 0, the formatted line
length is the screen width (with a maximum width of
79).
The <A HREF="options.html#'formatoptions'">'formatoptions'</A> option controls the type of
<A HREF="#formatting">formatting</A> |<A HREF="#fo-table">fo-table</A>|.
The cursor is left on the first non-blank of the last
formatted line.
NOTE: The "<A HREF="intro.html#Q">Q</A>" command formerly performed this
function. If you still want to use "<A HREF="intro.html#Q">Q</A>" for
<A HREF="#formatting">formatting</A>, use this <A HREF="map.html#mapping">mapping</A>:
<B> :nnoremap Q gq</B>
<A HREF="#gqgq">gqgq</A> *<A NAME="gqgq"></A><B>gqgq</B>* *<A NAME="gqq"></A><B>gqq</B>*
<A HREF="#gqq">gqq</A> Format the current line. With a <A HREF="intro.html#count">count</A> format that
many lines. {not in Vi}
*<A NAME="v_gq"></A><B>v_gq</B>*
{Visual}gq Format the highlighted text. (for <A HREF="intro.html#{Visual}">{Visual}</A> see
|<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
*<A NAME="gw"></A><B>gw</B>*
gw{motion} Format the lines that <A HREF="intro.html#{motion}">{motion}</A> moves over. Similar to
|<A HREF="#gq">gq</A>| but puts the cursor back at the same position in
the text. However, <A HREF="options.html#'formatprg'">'formatprg'</A> and <A HREF="options.html#'formatexpr'">'formatexpr'</A> are
not used. {not in Vi}
<A HREF="#gwgw">gwgw</A> *<A NAME="gwgw"></A><B>gwgw</B>* *<A NAME="gww"></A><B>gww</B>*
<A HREF="#gww">gww</A> Format the current line <A HREF="motion.html#as">as</A> with "<A HREF="#gw">gw</A>". {not in Vi}
*<A NAME="v_gw"></A><B>v_gw</B>*
{Visual}gw Format the highlighted text <A HREF="motion.html#as">as</A> with "<A HREF="#gw">gw</A>". (for
<A HREF="intro.html#{Visual}">{Visual}</A> see |<A HREF="visual.html#Visual-mode">Visual-mode</A>|). {not in Vi}
Example: To format the current <A HREF="motion.html#paragraph">paragraph</A> use: *<A NAME="gqap"></A><B>gqap</B>*
<B> gqap</B>
The "<A HREF="#gq">gq</A>" command leaves the cursor in the line where the motion command takes
the cursor. This allows you to repeat <A HREF="#formatting">formatting</A> repeated with "<A HREF="repeat.html#.">.</A>". This
works well with "gqj" (format current and next line) and "gq}" (format until
end of <A HREF="motion.html#paragraph">paragraph</A>). Note: When <A HREF="options.html#'formatprg'">'formatprg'</A> is set, "<A HREF="#gq">gq</A>" leaves the cursor on
the first formatted line (as with using a <A HREF="#filter">filter</A> command).
If you want to format the current <A HREF="motion.html#paragraph">paragraph</A> and continue where you were, use:
<B> gwap</B>
If you always want to keep paragraphs formatted you may want to add the '<A HREF="insert.html#a">a</A>'
flag to <A HREF="options.html#'formatoptions'">'formatoptions'</A>. See |<A HREF="#auto-format">auto-format</A>|.
If the <A HREF="options.html#'autoindent'">'autoindent'</A> option is on, Vim uses the indent of the first line for
the following lines.
Formatting does not change empty lines (but <A HREF="motion.html#it">it</A> does change lines with only
white space!).
The <A HREF="options.html#'joinspaces'">'joinspaces'</A> option is used when lines are joined together.
You can set the <A HREF="options.html#'formatexpr'">'formatexpr'</A> option to an <A HREF="eval.html#expression">expression</A> or the <A HREF="options.html#'formatprg'">'formatprg'</A> option
to the name of an external program for Vim to use for text <A HREF="#formatting">formatting</A>. The
<A HREF="options.html#'textwidth'">'textwidth'</A> and other <A HREF="options.html#options">options</A> have no effect on <A HREF="#formatting">formatting</A> by an external
program.
*<A NAME="right-justify"></A><B>right-justify</B>*
There is no command in Vim to right justify text. You can <A HREF="diff.html#do">do</A> <A HREF="motion.html#it">it</A> with
an external command, like "par" (e.g.: "!}par" to format until the end of the
<A HREF="motion.html#paragraph">paragraph</A>) or set <A HREF="options.html#'formatprg'">'formatprg'</A> to "par".
*<A NAME="format-comments"></A><B>format-comments</B>*
An overview of comment <A HREF="#formatting">formatting</A> is in section |<A HREF="usr_30.html#30.6">30.6</A>| of the user manual.
Vim can automatically insert and format comments in a special way. Vim
recognizes a comment by a specific string at the start of the line (ignoring
white space). Three types of comments can be used:
- A comment string that repeats at the start of each line. An example is the
type of comment used in shell scripts, starting with "<A HREF="pattern.html##">#</A>".
- A comment string that occurs only in the first line, not in the following
lines. An example is this list with dashes.
- Three-piece comments that have a start string, an end string, and optional
lines in between. The strings for the start, middle and end are different.
An example is the C style comment:
/*
* this is a C comment
*/
The <A HREF="options.html#'comments'">'comments'</A> option is a comma-separated list of parts. Each part defines a
type of comment string. A part consists of:
{flags}:{string}
{string} is the literal text that must appear.
{flags}:
<A HREF="pattern.html#n">n</A> Nested comment. Nesting with mixed parts is allowed. If <A HREF="options.html#'comments'">'comments'</A>
is "n:),n:>" a line starting with "<A HREF="#>">></A> ) >" is a comment.
<A HREF="motion.html#b">b</A> Blank (<Space>, <A HREF="motion.html#<Tab>"><Tab></A> or <A HREF="intro.html#<EOL>"><EOL></A>) required after {string}.
<A HREF="motion.html#f">f</A> Only the first line has the comment string. Do not repeat comment on
the next line, but preserve indentation (e.g., a bullet-list).
<A HREF="#s">s</A> Start of three-piece comment
<A HREF="motion.html#m">m</A> Middle of a three-piece comment
<A HREF="motion.html#e">e</A> End of a three-piece comment
<A HREF="motion.html#l">l</A> Left align. Used together with '<A HREF="#s">s</A>' or '<A HREF="motion.html#e">e</A>', the leftmost character of
start or end will line up with the leftmost character from the middle.
This is the default and can be omitted. See below for more details.
<A HREF="#r">r</A> Right align. Same <A HREF="motion.html#as">as</A> above but rightmost instead of leftmost. See
below for more details.
<A HREF="insert.html#O">O</A> Don't consider this comment for the "<A HREF="insert.html#O">O</A>" command.
<A HREF="#x">x</A> Allows three-piece comments to be ended by just typing the last
character of the end-comment string <A HREF="motion.html#as">as</A> the first action on a new
line when the middle-comment string has been inserted automatically.
See below for more details.
{digits}
When together with '<A HREF="#s">s</A>' or '<A HREF="motion.html#e">e</A>': add {digit} amount of offset to an
automatically inserted middle or end comment leader. The offset begins
from a left alignment. See below for more details.
-{digits}
Like {digits} but reduce the indent. This only works when there is
some indent for the start or end part that can be removed.
When a string has none of the '<A HREF="motion.html#f">f</A>', '<A HREF="#s">s</A>', '<A HREF="motion.html#m">m</A>' or '<A HREF="motion.html#e">e</A>' flags, Vim assumes the
comment string repeats at the start of each line. The flags field may be
empty.
Any blank space in the text before and after the {string} is part of the
{string}, so <A HREF="diff.html#do">do</A> not include leading or trailing blanks unless the blanks are a
required part of the comment string.
When one comment leader is part of another, specify the part after the whole.
For example, to include both "<A HREF="motion.html#-">-</A>" and "->", use
<B> :set comments=f:->,f:-</B>
A three-piece comment must always be given <A HREF="motion.html#as">as</A> start,middle,end, with no other
parts in between. An example of a three-piece comment is
<B> sr:/*,mb:*,ex:*/</B>
for C-comments. To avoid recognizing "*ptr" <A HREF="motion.html#as">as</A> a comment, the middle string
includes the '<A HREF="motion.html#b">b</A>' flag. For three-piece comments, Vim checks the text after
the start and middle strings for the end string. If Vim finds the end string,
the comment does not continue on the next line. Three-piece comments must
have a middle string because otherwise Vim can't recognize the middle lines.
Notice the use of the "<A HREF="#x">x</A>" flag in the above three-piece comment definition.
When you hit Return in a C-comment, Vim will insert the middle comment leader
for the new line: " * ". To close this comment you just have to type "<A HREF="pattern.html#/">/</A>"
before typing anything else on the new line. This will replace the
middle-comment leader with the end-comment leader and apply any specified
alignment, leaving just " */". There is no need to hit BackSpace first.
When there is a match with a middle part, but there also is a maching end part
which is longer, the end part is used. This makes a C style comment work
without requiring the middle part to end with a space.
Here is an example of alignment flags at work to make a comment stand out
(kind of looks like a 1 too). Consider comment string:
<B> :set comments=sr:/***,m:**,ex-2:******/</B>
<B><FONT COLOR="PURPLE"> /*** </FONT></B>
<B><FONT COLOR="PURPLE"> **<--right aligned from "r" flag </FONT></B>
<B><FONT COLOR="PURPLE"> ** </FONT></B>
<B><FONT COLOR="PURPLE">offset 2 spaces for the "-2" flag--->** </FONT></B>
<B><FONT COLOR="PURPLE"> ******/ </FONT></B>
In this <A HREF="#case">case</A>, the first comment was typed, then return was pressed 4 times,
then "<A HREF="pattern.html#/">/</A>" was pressed to end the comment.
Here are some finer points of three part comments. There are three times when
alignment and offset flags are taken into consideration: opening a new line
after a start-comment, opening a new line before an end-comment, and
automatically ending a three-piece comment. The end alignment flag has a
backwards perspective; the result is that the same alignment flag used with
"<A HREF="#s">s</A>" and "<A HREF="motion.html#e">e</A>" will result in the same indent for the starting and ending pieces.
Only one alignment per comment part is meant to be used, but an offset number
will override the "<A HREF="#r">r</A>" and "<A HREF="motion.html#l">l</A>" flag.
Enabling <A HREF="options.html#'cindent'">'cindent'</A> will override the alignment flags in many cases.
Reindenting using a different method like |<A HREF="#gq">gq</A>| or |<A HREF="#=">=</A>| will not consult
alignment flags either. The same behaviour can be defined in those other
<A HREF="#formatting">formatting</A> <A HREF="options.html#options">options</A>. One consideration is that <A HREF="options.html#'cindent'">'cindent'</A> has additional <A HREF="options.html#options">options</A>
for context based indenting of comments but cannot replicate many three piece
indent alignments. However, <A HREF="options.html#'indentexpr'">'indentexpr'</A> has the ability to work better with
three piece comments.
Other examples:
<B> "b:*" Includes lines starting with "*", but not if the "*" is</B>
<B> followed by a non-blank. This avoids a pointer dereference</B>
<B> like "*str" to be recognized as a comment.</B>
<B> "n:>" Includes a line starting with ">", ">>", ">>>", etc.</B>
<B> "fb:-" Format a list that starts with "- ".</B>
By default, "b:#" is included. This means that a line that starts with
"#include" is not recognized <A HREF="motion.html#as">as</A> a comment line. But a line that starts with
"<A HREF="pattern.html##">#</A> define" is recognized. This is a compromise.
{not available when compiled without the |<A HREF="various.html#+comments">+comments</A>| feature}
*<A NAME="fo-table"></A><B>fo-table</B>*
You can use the <A HREF="options.html#'formatoptions'">'formatoptions'</A> option to influence how Vim formats text.
<A HREF="options.html#'formatoptions'">'formatoptions'</A> is a string that can contain any of the letters below. The
default setting is "tcq". You can separate the option letters with commas for
readability.
<B><FONT COLOR="PURPLE">letter meaning when present in 'formatoptions' </FONT></B>
t Auto-wrap text using textwidth
<A HREF="#c">c</A> Auto-wrap comments using textwidth, <A HREF="insert.html#inserting">inserting</A> the current comment
leader automatically.
<A HREF="#r">r</A> Automatically insert the current comment leader after hitting
<A HREF="intro.html#<Enter>"><Enter></A> in <A HREF="insert.html#Insert">Insert</A> mode.
<A HREF="insert.html#o">o</A> Automatically insert the current comment leader after hitting '<A HREF="insert.html#o">o</A>' or
'<A HREF="insert.html#O">O</A>' in <A HREF="intro.html#Normal">Normal</A> mode.
<A HREF="repeat.html#q">q</A> Allow <A HREF="#formatting">formatting</A> of comments with "<A HREF="#gq">gq</A>".
Note that <A HREF="#formatting">formatting</A> will not change blank lines or lines containing
only the comment leader. A new <A HREF="motion.html#paragraph">paragraph</A> starts after such a line,
or when the comment leader changes.
<A HREF="motion.html#w">w</A> Trailing white space indicates a <A HREF="motion.html#paragraph">paragraph</A> continues in the next line.
A line that ends in a non-white character ends a <A HREF="motion.html#paragraph">paragraph</A>.
a Automatic <A HREF="#formatting">formatting</A> of paragraphs. Every time text is inserted or
deleted the <A HREF="motion.html#paragraph">paragraph</A> will be reformatted. See |<A HREF="#auto-format">auto-format</A>|.
When the '<A HREF="#c">c</A>' flag is present this only happens for recognized
comments.
<A HREF="pattern.html#n">n</A> When <A HREF="#formatting">formatting</A> text, recognize numbered lists. This actually uses
the <A HREF="options.html#'formatlistpat'">'formatlistpat'</A> option, thus any kind of list can be used. The
indent of the text after the number is used for the next line. The
default is to find a number, optionally followed by '<A HREF="repeat.html#.">.</A>', '<A HREF="cmdline.html#:">:</A>', '<A HREF="motion.html#)">)</A>',
'<A HREF="index.html#]">]</A>' or '<A HREF="motion.html#}">}</A>'. Note that <A HREF="options.html#'autoindent'">'autoindent'</A> must be set too. Doesn't work
well together with "2".
Example:
<B> 1. the first item</B>
<B> wraps</B>
<B> 2. the second item</B>
2 When <A HREF="#formatting">formatting</A> text, use the indent of the second line of a <A HREF="motion.html#paragraph">paragraph</A>
for the rest of the <A HREF="motion.html#paragraph">paragraph</A>, instead of the indent of the first
line. This supports paragraphs in which the first line has a
different indent than the rest. Note that <A HREF="options.html#'autoindent'">'autoindent'</A> must be set
too. Example:
<B> first line of a paragraph</B>
<B> second line of the same paragraph</B>
<B> third line.</B>
<A HREF="visual.html#v">v</A> Vi-compatible auto-wrapping in insert mode: Only break a line at a
blank that you have entered during the current insert command. (Note:
this is not 100% <A HREF="intro.html#Vi">Vi</A> compatible. <A HREF="intro.html#Vi">Vi</A> has some "unexpected features" or
bugs in this area. It uses the screen column instead of the line
column.)
<A HREF="motion.html#b">b</A> Like '<A HREF="visual.html#v">v</A>', but only auto-wrap if you enter a blank at or before
the wrap margin. If the line was longer than <A HREF="options.html#'textwidth'">'textwidth'</A> when you
started the insert, or you <A HREF="diff.html#do">do</A> not enter a blank in the insert before
reaching <A HREF="options.html#'textwidth'">'textwidth'</A>, Vim does not perform auto-wrapping.
<A HREF="motion.html#l">l</A> Long lines are not broken in insert mode: When a line was longer than
<A HREF="options.html#'textwidth'">'textwidth'</A> when the insert command started, Vim does not
automatically format <A HREF="motion.html#it">it</A>.
<A HREF="motion.html#m">m</A> Also break at a <A HREF="mbyte.html#multi-byte">multi-byte</A> character above 255. This is useful for
Asian text where every character is a <A HREF="motion.html#word">word</A> on its own.
<A HREF="motion.html#M">M</A> When joining lines, don't insert a space before or after a <A HREF="mbyte.html#multi-byte">multi-byte</A>
character. Overrules the '<A HREF="motion.html#B">B</A>' flag.
<A HREF="motion.html#B">B</A> When joining lines, don't insert a space between two <A HREF="mbyte.html#multi-byte">multi-byte</A>
characters. Overruled by the '<A HREF="motion.html#M">M</A>' flag.
1 Don't break a line after a one-letter <A HREF="motion.html#word">word</A>. It's broken before <A HREF="motion.html#it">it</A>
instead (if possible).
With '<A HREF="motion.html#t">t</A>' and '<A HREF="#c">c</A>' you can specify when Vim performs auto-wrapping:
<B><FONT COLOR="PURPLE">value action </FONT></B>
"" no automatic <A HREF="#formatting">formatting</A> (you can use "<A HREF="#gq">gq</A>" for manual <A HREF="#formatting">formatting</A>)
"<A HREF="motion.html#t">t</A>" automatic <A HREF="#formatting">formatting</A> of text, but not comments
"<A HREF="#c">c</A>" automatic <A HREF="#formatting">formatting</A> for comments, but not text (good for C code)
"tc" automatic <A HREF="#formatting">formatting</A> for text and comments
Note that when <A HREF="options.html#'textwidth'">'textwidth'</A> is 0, Vim does no automatic <A HREF="#formatting">formatting</A> anyway (but
does insert comment leaders according to the <A HREF="options.html#'comments'">'comments'</A> option). An exception
is when the 'a' flag is present. |<A HREF="#auto-format">auto-format</A>|
Note that when <A HREF="options.html#'paste'">'paste'</A> is on, Vim does no <A HREF="#formatting">formatting</A> at all.
Note that <A HREF="options.html#'textwidth'">'textwidth'</A> can be non-zero even if Vim never performs auto-wrapping;
<A HREF="options.html#'textwidth'">'textwidth'</A> is still useful for <A HREF="#formatting">formatting</A> with "<A HREF="#gq">gq</A>".
If the <A HREF="options.html#'comments'">'comments'</A> option includes "/*", "*" and/or "*/", then Vim has some
built in stuff to treat these types of comments a bit more cleverly.
Opening a new line before or after "/*" or "*/" (with '<A HREF="#r">r</A>' or '<A HREF="insert.html#o">o</A>' present in
<A HREF="options.html#'formatoptions'">'formatoptions'</A>) gives the correct start of the line automatically. The same
happens with <A HREF="#formatting">formatting</A> and auto-wrapping. Opening a line after a line
starting with "/*" or "*" and containing "*/", will cause no comment leader to
be inserted, and the indent of the new line is taken from the line containing
the start of the comment.
E.g.:
<B><FONT COLOR="PURPLE"> /* </FONT></B>
<B><FONT COLOR="PURPLE"> * Your typical comment. </FONT></B>
<B><FONT COLOR="PURPLE"> */ </FONT></B>
The indent on this line is the same <A HREF="motion.html#as">as</A> the start of the above
comment.
All of this should be really cool, especially in conjunction with the new
<A HREF="autocmd.html#:autocmd">:autocmd</A> command to prepare different settings for different types of file.
Some examples:
for C code (only format comments):
<B> :set fo=croq</B>
for Mail/news (format all, don't start comment with "<A HREF="insert.html#o">o</A>" command):
<B> :set fo=tcrq</B>
Automatic <A HREF="#formatting">formatting</A> *<A NAME="auto-format"></A><B>auto-format</B>*
When the '<A HREF="insert.html#a">a</A>' flag is present in <A HREF="options.html#'formatoptions'">'formatoptions'</A> text is formatted
automatically when <A HREF="insert.html#inserting">inserting</A> text or <A HREF="#deleting">deleting</A> text. This works <A HREF="todo.html#nice">nice</A> for
editing text paragraphs. A few hints on how to use this:
- You need to properly define paragraphs. The simplest is paragraphs that are
separated by a blank line. When there is no separating blank line, consider
using the '<A HREF="motion.html#w">w</A>' flag and adding a space at the end of each line in the
paragraphs except the last one.
- You can set the <A HREF="options.html#'formatoptions'">'formatoptions'</A> based on the type of file |<A HREF="filetype.html#filetype">filetype</A>| or
specifically for one file with a |<A HREF="options.html#modeline">modeline</A>|.
- Set <A HREF="options.html#'formatoptions'">'formatoptions'</A> to "aw2tq" to make text with indents like this:
bla bla foobar bla
bla foobar bla foobar bla
bla bla foobar bla
bla foobar bla bla foobar
- Add the '<A HREF="#c">c</A>' flag to only <A HREF="#auto-format">auto-format</A> comments. Useful in source code.
- Set <A HREF="options.html#'textwidth'">'textwidth'</A> to the desired width. If <A HREF="motion.html#it">it</A> is zero then 79 is used, or the
width of the screen if this is smaller.
And a few warnings:
- When part of the text is not properly separated in paragraphs, making
changes in this text will cause <A HREF="motion.html#it">it</A> to be formatted anyway. Consider doing
<B> :set fo-=a</B>
- When using the '<A HREF="motion.html#w">w</A>' flag (trailing space means <A HREF="motion.html#paragraph">paragraph</A> continues) and
<A HREF="#deleting">deleting</A> the last line of a <A HREF="motion.html#paragraph">paragraph</A> with |<A HREF="#dd">dd</A>|, the <A HREF="motion.html#paragraph">paragraph</A> will be
joined with the next one.
- Changed text is saved for <A HREF="undo.html#undo">undo</A>. Formatting is also a change. Thus each
format action saves text for <A HREF="undo.html#undo">undo</A>. This may consume quite a lot of memory.
- Formatting a long <A HREF="motion.html#paragraph">paragraph</A> and/or with complicated indenting may be slow.
==============================================================================
7. Sorting text *<A NAME="sorting"></A><B>sorting</B>*
Vim has a <A HREF="#sorting">sorting</A> function and a <A HREF="#sorting">sorting</A> command. The <A HREF="#sorting">sorting</A> function can be
found here: |<A HREF="eval.html#sort()">sort()</A>|.
*<A NAME=":sor"></A><B>:sor</B>* *<A NAME=":sort"></A><B>:sort</B>*
:[range]sor[t][!] [i][u][r][n][x][o] [/{pattern}/]
Sort lines in <A HREF="cmdline.html#[range]">[range]</A>. When no range is given all
lines are sorted.
With [!] the order is reversed.
With [i] <A HREF="#case">case</A> is ignored.
With [n] <A HREF="#sorting">sorting</A> is done on the first decimal number
in the line (after or inside a {pattern} match).
One leading '<A HREF="motion.html#-">-</A>' is included in the number.
With [x] <A HREF="#sorting">sorting</A> is done on the first hexadecimal
number in the line (after or inside a {pattern}
match). A leading "0x" or "0X" is ignored.
One leading '<A HREF="motion.html#-">-</A>' is included in the number.
With [o] <A HREF="#sorting">sorting</A> is done on the first <A HREF="eval.html#octal">octal</A> number in
the line (after or inside a {pattern} match).
With [u] only keep the first of a sequence of
identical lines (ignoring <A HREF="#case">case</A> when [i] is used).
Without this flag, a sequence of identical lines
will be kept in their original order.
Note that leading and trailing white space may cause
lines to be different.
When /{pattern}/ is specified and there is no [r] flag
the text matched with {pattern} is skipped, so that
you sort on what comes after the match.
Instead of the slash any non-letter can be used.
For example, to sort on the second comma-separated
field:
<B> :sort /[^,]*,/</B>
To sort on the text at virtual column 10 (thus
ignoring the difference between tabs and spaces):
<B> :sort /.*\%10v/</B>
To sort on the first number in the line, no matter
what is in front of <A HREF="motion.html#it">it</A>:
<B> :sort /.\{-}\ze\d/</B>
(Explanation: ".\{-}" matches any text, "\ze" sets the
end of the match and \d matches a digit.)
With [r] <A HREF="#sorting">sorting</A> is done on the matching {pattern}
instead of skipping past <A HREF="motion.html#it">it</A> <A HREF="motion.html#as">as</A> described above.
For example, to sort on only the first three letters
of each line:
<B> :sort /\a\a\a/ r</B>
If a {pattern} is used, any lines which don't have a
match for {pattern} are kept in their current order,
but separate from the lines which <A HREF="diff.html#do">do</A> match {pattern}.
If you sorted in reverse, they will be in reverse
order after the sorted lines, otherwise they will be
in their original order, right before the sorted
lines.
If {pattern} is empty (e.g. <A HREF="version7.html#//">//</A> is specified), the
last search <A HREF="pattern.html#pattern">pattern</A> is used. This allows trying out
a <A HREF="pattern.html#pattern">pattern</A> first.
Note that using "<A HREF="#:sort">:sort</A>" with "<A HREF="repeat.html#:global">:global</A>" doesn't sort the matching lines, it's
quite useless.
The details about <A HREF="#sorting">sorting</A> depend on the library function used. There is no
guarantee that <A HREF="#sorting">sorting</A> is "stable" or obeys the current <A HREF="mbyte.html#locale">locale</A>. You will have
to try <A HREF="motion.html#it">it</A> out.
The <A HREF="#sorting">sorting</A> can be interrupted, but if you interrupt <A HREF="motion.html#it">it</A> too late in the
process you may end up with duplicated lines. This also depends on the system
library function used.
<A HREF="#top">top</A> - <A HREF="index.html">main help file</A>
</PRE>
</BODY>
</HTML>
|