/usr/share/doc/fish/commands.html is in fish-common 2.4.0-1.
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 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 | <!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<title>fish: Commands</title>
<link href="user_doc.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top" class="qindex"><!-- do not close this div here, it is closed by doxygen! -->
<a href="http://fishshell.com/"><code>fish</code> shell</a>
|
<a href="index.html">Documentation</a>
|
<a href="tutorial.html">Tutorial</a>
|
<a href="design.html">Design</a>
|
<a href="commands.html">Commands</a>
|
<a href="faq.html">FAQ</a>
|
<a href="license.html">License</a>
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Commands </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock">
<div class="fish_left_bar">
<div class="logo"></div>
<div class="menu commands_menu">
<ul>
<li><a href="#abbr">abbr</a></li>
<li><a href="#alias">alias</a></li>
<li><a href="#and">and</a></li>
<li><a href="#begin">begin</a></li>
<li><a href="#bg">bg</a></li>
<li><a href="#bind">bind</a></li>
<li><a href="#block">block</a></li>
<li><a href="#break">break</a></li>
<li><a href="#breakpoint">breakpoint</a></li>
<li><a href="#builtin">builtin</a></li>
<li><a href="#case">case</a></li>
<li><a href="#cd">cd</a></li>
<li><a href="#command">command</a></li>
<li><a href="#commandline">commandline</a></li>
<li><a href="#complete">complete</a></li>
<li><a href="#contains">contains</a></li>
<li><a href="#continue">continue</a></li>
<li><a href="#count">count</a></li>
<li><a href="#dirh">dirh</a></li>
<li><a href="#dirs">dirs</a></li>
<li><a href="#echo">echo</a></li>
<li><a href="#else">else</a></li>
<li><a href="#emit">emit</a></li>
<li><a href="#end">end</a></li>
<li><a href="#eval">eval</a></li>
<li><a href="#exec">exec</a></li>
<li><a href="#exit">exit</a></li>
<li><a href="#false">false</a></li>
<li><a href="#fg">fg</a></li>
<li><a href="#fish">fish</a></li>
<li><a href="#fish_config">fish_config</a></li>
<li><a href="#fish_indent">fish_indent</a></li>
<li><a href="#fish_key_reader">fish_key_reader</a></li>
<li><a href="#fish_mode_prompt">fish_mode_prompt</a></li>
<li><a href="#fish_prompt">fish_prompt</a></li>
<li><a href="#fish_right_prompt">fish_right_prompt</a></li>
<li><a href="#fish_update_completions">fish_update_completions</a></li>
<li><a href="#fish_vi_mode">fish_vi_mode</a></li>
<li><a href="#for">for</a></li>
<li><a href="#funced">funced</a></li>
<li><a href="#funcsave">funcsave</a></li>
<li><a href="#function">function</a></li>
<li><a href="#functions">functions</a></li>
<li><a href="#help">help</a></li>
<li><a href="#history">history</a></li>
<li><a href="#if">if</a></li>
<li><a href="#isatty">isatty</a></li>
<li><a href="#jobs">jobs</a></li>
<li><a href="#math">math</a></li>
<li><a href="#nextd">nextd</a></li>
<li><a href="#not">not</a></li>
<li><a href="#open">open</a></li>
<li><a href="#or">or</a></li>
<li><a href="#popd">popd</a></li>
<li><a href="#prevd">prevd</a></li>
<li><a href="#printf">printf</a></li>
<li><a href="#prompt_pwd">prompt_pwd</a></li>
<li><a href="#psub">psub</a></li>
<li><a href="#pushd">pushd</a></li>
<li><a href="#pwd">pwd</a></li>
<li><a href="#random">random</a></li>
<li><a href="#read">read</a></li>
<li><a href="#realpath">realpath</a></li>
<li><a href="#return">return</a></li>
<li><a href="#set">set</a></li>
<li><a href="#set_color">set_color</a></li>
<li><a href="#source">source</a></li>
<li><a href="#status">status</a></li>
<li><a href="#string">string</a></li>
<li><a href="#suspend">suspend</a></li>
<li><a href="#switch">switch</a></li>
<li><a href="#test">test</a></li>
<li><a href="#trap">trap</a></li>
<li><a href="#true">true</a></li>
<li><a href="#type">type</a></li>
<li><a href="#ulimit">ulimit</a></li>
<li><a href="#umask">umask</a></li>
<li><a href="#vared">vared</a></li>
<li><a href="#while">while</a></li>
</ul>
</div>
</div>
<div class="commands fish_right_bar">
<h1 class="interior_title">Command reference</h1>
<p> <code>fish</code> ships with a large number of builtin commands, shellscript functions and external commands. These are all described below.</p>
<p>Almost all fish commands respond to the <code>-h</code> or <code>--help</code> options to display their relevant help, also accessible using the <code>help</code> and <code>man</code> commands, like so:</p>
<pre class="fish">
<span class="command">echo</span> <span class="argument">-h</span>
<span class="command">echo</span> <span class="argument">--help</span>
<span class="comment"># Prints help to the terminal window</span>
<span class="binary">man</span> <span class="argument">echo</span>
<span class="comment"># Displays the man page in the system pager</span>
<span class="comment"># (normally 'less', 'more' or 'most').</span>
<span class="command">help</span> <span class="argument">echo</span>
<span class="comment"># Open a web browser to show the relevant documentation</span>
</pre><hr/>
<h1><a class="anchor" id="abbr"></a>
abbr - manage fish abbreviations</h1>
<h2><a class="anchor" id="abbr-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">abbr</span> <span class="argument">--add</span> <span class="argument">word</span> <span class="argument">phrase...</span>
<span class="command">abbr</span> <span class="argument">--show</span>
<span class="command">abbr</span> <span class="argument">--list</span>
<span class="command">abbr</span> <span class="argument">--erase</span> <span class="argument">word</span>
</pre><h2><a class="anchor" id="abbr-description"></a>
Description</h2>
<p><code>abbr</code> manipulates the list of abbreviations that fish will expand.</p>
<p>Abbreviations are user-defined character sequences or words that are replaced with longer phrases after they are entered. For example, a frequently-run command such as <code>git checkout</code> can be abbreviated to <code>gco</code>. After entering <code>gco</code> and pressing <span class="key"><b>Space</b></span> or <span class="key"><b>Enter</b></span>, the full text <code>git checkout</code> will appear in the command line.</p>
<p>Abbreviations are stored in a variable named <code>fish_user_abbreviations</code>. This is automatically created as a universal variable the first time an abbreviation is created. If you want your abbreviations to be private to a particular fish session you can put the following in your *~/.config/fish/config.fish* file before you define your first abbrevation:</p>
<pre class="fish">
<span class="command">if</span> <span class="argument">status</span> <span class="argument">--is-interactive</span>
<span class="command">set</span> <span class="argument">-g</span> <span class="argument">fish_user_abbreviations</span>
<span class="command">abbr</span> <span class="argument">--add</span> <span class="argument">first</span> <span class="string">'echo my first abbreviation'</span>
<span class="command">abbr</span> <span class="argument">--add</span> <span class="argument">second</span> <span class="string">'echo my second abbreviation'</span>
<span class="comment"># etcetera</span>
<span class="command">end</span>
</pre><p>You can create abbreviations directly on the command line and they will be saved automatically and made visible to other fish sessions if <code>fish_user_abbreviations</code> is a universal variable. If you keep the variable as universal, <code>abbr --add</code> statements in <a href="tutorial.html#tut_startup">config.fish</a> will do nothing but slow down startup slightly.</p>
<h2><a class="anchor" id="abbr-options"></a>
Options</h2>
<p>The following parameters are available:</p>
<ul>
<li><code>-a WORD PHRASE</code> or <code>--add WORD PHRASE</code> Adds a new abbreviation, causing WORD to be expanded to PHRASE.</li>
<li><code>-s</code> or <code>--show</code> Show all abbreviated words and their expanded phrases in a manner suitable for export and import.</li>
<li><code>-l</code> or <code>--list</code> Lists all abbreviated words.</li>
<li><code>-e WORD</code> or <code>--erase WORD</code> Erase the abbreviation WORD.</li>
</ul>
<p>Note: fish version 2.1 supported <code>-a WORD=PHRASE</code>. This syntax is now deprecated but will still be converted.</p>
<h2><a class="anchor" id="abbr-example"></a>
Examples</h2>
<pre class="fish">
<span class="command">abbr</span> <span class="argument">-a</span> <span class="argument">gco</span> <span class="argument">git</span> <span class="argument">checkout</span>
</pre><p>Add a new abbreviation where <code>gco</code> will be replaced with <code>git checkout</code>.</p>
<pre class="fish">
<span class="command">abbr</span> <span class="argument">-e</span> <span class="argument">gco</span>
</pre><p>Erase the <code>gco</code> abbreviation.</p>
<pre class="fish">
<span class="binary">ssh</span> <span class="argument">another_host</span> <span class="argument">abbr</span> <span class="argument">-s</span> <span class="redirect">|</span> <span class="command">source</span>
</pre><p>Import the abbreviations defined on another_host over SSH.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="alias"></a>
alias - create a function</h1>
<h2><a class="anchor" id="alias-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">alias</span> <span class="argument">NAME</span> <span class="argument">DEFINITION</span>
<span class="command">alias</span> <span class="argument">NAME=DEFINITION</span>
</pre><h2><a class="anchor" id="alias-description"></a>
Description</h2>
<p><code>alias</code> is a simple wrapper for the <code>function</code> builtin. It exists for backwards compatibility with Posix shells. For other uses, it is recommended to define a <a href="#function">function</a>.</p>
<p><code>fish</code> does not keep track of which functions have been defined using <code>alias</code>. They must be erased using <code>functions -e</code>.</p>
<ul>
<li><code>NAME</code> is the name of the alias</li>
<li><code>DEFINITION</code> is the actual command to execute. The string <code>$argv</code> will be appended.</li>
</ul>
<p>You cannot create an alias to a function with the same name.</p>
<p>Note that spaces need to be escaped in the call to alias just like in the commandline <em>even inside the quotes</em>.</p>
<h2><a class="anchor" id="alias-example"></a>
Example</h2>
<p>The following code will create <code>rmi</code>, which runs <code>rm</code> with additional arguments on every invocation.</p>
<pre class="fish">
<span class="command">alias</span> <span class="argument">rmi</span> <span class="string">"rm -i"</span>
<span class="comment"># This is equivalent to entering the following function:</span>
<span class="command">function</span> <span class="argument">rmi</span>
<span class="binary">rm</span> <span class="argument">-i</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
<span class="comment"># This needs to have the spaces escaped or "Chrome.app..." will be seen as an argument to "/Applications/Google":</span>
<span class="command">alias</span> <span class="argument">chrome=</span><span class="string">'/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana'</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="and"></a>
and - conditionally execute a command</h1>
<h2><a class="anchor" id="and-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="argument">COMMAND1</span><span class="redirect">;</span> <span class="command">and</span> <span class="argument">COMMAND2</span>
</pre><h2><a class="anchor" id="and-description"></a>
Description</h2>
<p><code>and</code> is used to execute a command if the current exit status (as set by the previous command) is 0.</p>
<p><code>and</code> statements may be used as part of the condition in an <a href="#if"><code>if</code></a> or <a href="#while"><code>while</code></a> block. See the documentation for <a href="#if"><code>if</code></a> and <a href="#while"><code>while</code></a> for examples.</p>
<p><code>and</code> does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.</p>
<h2><a class="anchor" id="and-example"></a>
Example</h2>
<p>The following code runs the <code>make</code> command to build a program. If the build succeeds, <code>make</code>'s exit status is 0, and the program is installed. If either step fails, the exit status is 1, and <code>make clean</code> is run, which removes the files created by the build process.</p>
<pre class="fish">
<span class="binary">make</span><span class="redirect">;</span> <span class="command">and</span> <span class="binary">make</span> <span class="argument">install</span><span class="redirect">;</span> <span class="command">or</span> <span class="binary">make</span> <span class="argument">clean</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="begin"></a>
begin - start a new block of code</h1>
<h2><a class="anchor" id="begin-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">begin</span><span class="redirect">;</span> <span class="argument">[COMMANDS...;]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="begin-description"></a>
Description</h2>
<p><code>begin</code> is used to create a new block of code.</p>
<p>The block is unconditionally executed. <code>begin; ...; end</code> is equivalent to <code>if true; ...; end</code>.</p>
<p><code>begin</code> is used to group a number of commands into a block. This allows the introduction of a new variable scope, redirection of the input or output of a set of commands as a group, or to specify precedence when using the conditional commands like <code>and</code>.</p>
<p><code>begin</code> does not change the current exit status.</p>
<h2><a class="anchor" id="begin-example"></a>
Example</h2>
<p>The following code sets a number of variables inside of a block scope. Since the variables are set inside the block and have local scope, they will be automatically deleted when the block ends.</p>
<pre class="fish">
<span class="command">begin</span>
<span class="command">set</span> <span class="argument">-l</span> <span class="argument">PIRATE</span> <span class="argument">Yarrr</span>
<span class="argument">...</span>
<span class="command">end</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>PIRATE</span>
<span class="comment"># This will not output anything, since the PIRATE variable</span>
<span class="comment"># went out of scope at the end of the block</span>
</pre><p>In the following code, all output is redirected to the file out.html.</p>
<pre class="fish">
<span class="command">begin</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>xml_header</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>html_header</span>
<span class="command">if</span> <span class="command">test</span> <span class="argument">-e</span> <span class="variable"><span class="operator">$</span>file</span>
<span class="argument">...</span>
<span class="command">end</span>
<span class="argument">...</span>
<span class="command">end</span> <span class="redirect">> out.html</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="bg"></a>
bg - send jobs to background</h1>
<h2><a class="anchor" id="bg-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">bg</span> <span class="argument">[PID...]</span>
</pre><h2><a class="anchor" id="bg-description"></a>
Description</h2>
<p><code>bg</code> sends <a href="index.html#syntax-job-control">jobs</a> to the background, resuming them if they are stopped. A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background.</p>
<p>The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>.</p>
<h2><a class="anchor" id="bg-example"></a>
Example</h2>
<p><code>bg %1</code> will put the job with job ID 1 in the background.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="bind"></a>
bind - handle fish key bindings</h1>
<h2><a class="anchor" id="bind-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">bind</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-M</span> <span class="redirect">|</span> <span class="argument">--mode</span><span class="operator">)</span> <span class="argument">MODE]</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-m</span> <span class="redirect">|</span> <span class="argument">--sets-mode</span><span class="operator">)</span> <span class="argument">NEW_MODE]</span>
<span class="argument">[</span><span class="operator">(</span><span class="argument">-k</span> <span class="redirect">|</span> <span class="argument">--key</span><span class="operator">)</span>] <span class="argument">SEQUENCE</span> <span class="argument">COMMAND</span> <span class="argument">[COMMAND...]</span>
<span class="command">bind</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-M</span> <span class="redirect">|</span> <span class="argument">--mode</span><span class="operator">)</span> <span class="argument">MODE]</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-k</span> <span class="redirect">|</span> <span class="argument">--key</span><span class="operator">)</span>] <span class="argument">SEQUENCE</span>
<span class="command">bind</span> <span class="operator">(</span><span class="argument">-K</span> <span class="redirect">|</span> <span class="argument">--key-names</span><span class="operator">)</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-a</span> <span class="redirect">|</span> <span class="argument">--all</span><span class="operator">)</span>]
<span class="command">bind</span> <span class="operator">(</span><span class="argument">-f</span> <span class="redirect">|</span> <span class="argument">--function-names</span><span class="operator">)</span>
<span class="command">bind</span> <span class="operator">(</span><span class="argument">-e</span> <span class="redirect">|</span> <span class="argument">--erase</span><span class="operator">)</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-M</span> <span class="redirect">|</span> <span class="argument">--mode</span><span class="operator">)</span> <span class="argument">MODE]</span>
<span class="operator">(</span><span class="argument">-a</span> <span class="redirect">|</span> <span class="argument">--all</span> <span class="redirect">|</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-k</span> <span class="redirect">|</span> <span class="argument">--key</span><span class="operator">)</span>] <span class="argument">SEQUENCE</span> <span class="argument">[SEQUENCE...]</span><span class="operator">)</span>
</pre><h2><a class="anchor" id="bind-description"></a>
Description</h2>
<p><code>bind</code> adds a binding for the specified key sequence to the specified command.</p>
<p>SEQUENCE is the character sequence to bind to. These should be written as <a href="index.html#escapes">fish escape sequences</a>. For example, because pressing the Alt key and another character sends that character prefixed with an escape character, Alt-based key bindings can be written using the <code>\e</code> escape. For example, <span class="key"><em>Alt</em><span>-</span><b>w</b></span> can be written as <code>\ew</code>. The control character can be written in much the same way using the <code>\c</code> escape, for example <span class="key"><em>Control</em><span>-</span><b>X</b></span> (^X) can be written as <code>\cx</code>. Note that Alt-based key bindings are case sensitive and Control-based key bindings are not. This is a constraint of text-based terminals, not <code>fish</code>.</p>
<p>The default key binding can be set by specifying a <code>SEQUENCE</code> of the empty string (that is, <code>''</code> ). It will be used whenever no other binding matches. For most key bindings, it makes sense to use the <code>self-insert</code> function (i.e. <code>bind '' self-insert</code>) as the default keybinding. This will insert any keystrokes not specifically bound to into the editor. Non- printable characters are ignored by the editor, so this will not result in control sequences being printable.</p>
<p>If the <code>-k</code> switch is used, the name of the key (such as 'down', 'up' or 'backspace') is used instead of a sequence. The names used are the same as the corresponding curses variables, but without the 'key_' prefix. (See <code>terminfo(5)</code> for more information, or use <code>bind --key-names</code> for a list of all available named keys.)</p>
<p><code>COMMAND</code> can be any fish command, but it can also be one of a set of special input functions. These include functions for moving the cursor, operating on the kill-ring, performing tab completion, etc. Use <code>bind --function-names</code> for a complete list of these input functions.</p>
<p>When <code>COMMAND</code> is a shellscript command, it is a good practice to put the actual code into a <a href="#function">function</a> and simply bind to the function name. This way it becomes significantly easier to test the function while editing, and the result is usually more readable as well.</p>
<p>If such a script produces output, the script needs to finish by calling <code>commandline -f repaint</code> in order to tell fish that a repaint is in order.</p>
<p>When multiple <code>COMMAND</code>s are provided, they are all run in the specified order when the key is pressed.</p>
<p>If no <code>SEQUENCE</code> is provided, all bindings (or just the bindings in the specified <code>MODE</code>) are printed. If <code>SEQUENCE</code> is provided without <code>COMMAND</code>, just the binding matching that sequence is printed.</p>
<p>Key bindings are not saved between sessions by default. <b>Bare <code>bind</code> statements in <a href="index.html#initialization">config.fish</a> won't have any effect because it is sourced before the default keybindings are setup.</b> To save custom keybindings, put the <code>bind</code> statements into a function called <code>fish_user_key_bindings</code>, which will be <a href="tutorial.html#tut_autoload">autoloaded</a>.</p>
<p>Key bindings may use "modes", which mimics Vi's modal input behavior. The default mode is "default", and every bind applies to a single mode. The mode can be viewed/changed with the <code>$fish_bind_mode</code> variable.</p>
<p>The following parameters are available:</p>
<ul>
<li><code>-k</code> or <code>--key</code> Specify a key name, such as 'left' or 'backspace' instead of a character sequence</li>
<li><code>-K</code> or <code>--key-names</code> Display a list of available key names. Specifying <code>-a</code> or <code>--all</code> includes keys that don't have a known mapping</li>
<li><code>-f</code> or <code>--function-names</code> Display a list of available input functions</li>
<li><code>-M MODE</code> or <code>--mode MODE</code> Specify a bind mode that the bind is used in. Defaults to "default"</li>
<li><code>-m NEW_MODE</code> or <code>--sets-mode NEW_MODE</code> Change the current mode to <code>NEW_MODE</code> after this binding is executed</li>
<li><code>-e</code> or <code>--erase</code> Erase the binding with the given sequence and mode instead of defining a new one. Multiple sequences can be specified with this flag. Specifying <code>-a</code> or <code>--all</code> with <code>-M</code> or <code>--mode</code> erases all binds in the given mode regardless of sequence. Specifying <code>-a</code> or <code>--all</code> without <code>-M</code> or <code>--mode</code> erases all binds in all modes regardless of sequence.</li>
<li><code>-a</code> or <code>--all</code> See <code>--erase</code> and <code>--key-names</code></li>
</ul>
<p>The following special input functions are available:</p>
<ul>
<li><code>accept-autosuggestion</code>, accept the current autosuggestion completely</li>
<li><code>backward-char</code>, moves one character to the left</li>
<li><code>backward-bigword</code>, move one whitespace-delimited word to the left</li>
<li><code>backward-delete-char</code>, deletes one character of input to the left of the cursor</li>
<li><code>backward-kill-bigword</code>, move the whitespace-delimited word to the left of the cursor to the killring</li>
<li><code>backward-kill-line</code>, move everything from the beginning of the line to the cursor to the killring</li>
<li><code>backward-kill-path-component</code>, move one path component to the left of the cursor (everything from the last "/" or whitespace exclusive) to the killring</li>
<li><code>backward-kill-word</code>, move the word to the left of the cursor to the killring</li>
<li><code>backward-word</code>, move one word to the left</li>
<li><code>beginning-of-history</code>, move to the beginning of the history</li>
<li><code>beginning-of-line</code>, move to the beginning of the line</li>
<li><code>begin-selection</code>, start selecting text</li>
<li><code>capitalize-word</code>, make the current word begin with a capital letter</li>
<li><code>complete</code>, guess the remainder of the current token</li>
<li><code>complete-and-search</code>, invoke the searchable pager on completion options</li>
<li><code>delete-char</code>, delete one character to the right of the cursor</li>
<li><code>downcase-word</code>, make the current word lowercase</li>
<li><code>end-of-history</code>, move to the end of the history</li>
<li><code>end-of-line</code>, move to the end of the line</li>
<li><code>end-selection</code>, end selecting text</li>
<li><code>forward-bigword</code>, move one whitespace-delimited word to the right</li>
<li><code>forward-char</code>, move one character to the right</li>
<li><code>forward-word</code>, move one word to the right</li>
<li><code>history-search-backward</code>, search the history for the previous match</li>
<li><code>history-search-forward</code>, search the history for the next match</li>
<li><code>kill-bigword</code>, move the next whitespace-delimited word to the killring</li>
<li><code>kill-line</code>, move everything from the cursor to the end of the line to the killring</li>
<li><code>kill-selection</code>, move the selected text to the killring</li>
<li><code>kill-whole-line</code>, move the line to the killring</li>
<li><code>kill-word</code>, move the next word to the killring</li>
<li><code>suppress-autosuggestion</code>, remove the current autosuggestion</li>
<li><code>swap-selection-start-stop</code>, go to the other end of the highlighted text without changing the selection</li>
<li><code>transpose-chars</code>, transpose two characters to the left of the cursor</li>
<li><code>transpose-words</code>, transpose two words to the left of the cursor</li>
<li><code>upcase-word</code>, make the current word uppercase</li>
<li><code>yank</code>, insert the latest entry of the killring into the buffer</li>
<li><code>yank-pop</code>, rotate to the previous entry of the killring</li>
</ul>
<h2><a class="anchor" id="bind-example"></a>
Examples</h2>
<pre class="fish">
<span class="command">bind</span> <span>\</span>cd <span class="string">'exit'</span>
</pre><p>Causes <code>fish</code> to exit when <span class="key"><em>Control</em><span>-</span><b>D</b></span> is pressed.</p>
<pre class="fish">
<span class="command">bind</span> <span class="argument">-k</span> <span class="argument">ppage</span> <span class="argument">history-search-backward</span>
</pre><p>Performs a history search when the <span class="key"><b>Page Up</b></span> key is pressed.</p>
<pre class="fish">
<span class="command">set</span> <span class="argument">-g</span> <span class="argument">fish_key_bindings</span> <span class="argument">fish_vi_key_bindings</span>
<span class="command">bind</span> <span class="argument">-M</span> <span class="argument">insert</span> <span>\</span>cc <span class="argument">kill-whole-line</span> <span class="argument">force-repaint</span>
</pre><p>Turns on Vi key bindings and rebinds <span class="key"><em>Control</em><span>-</span><b>C</b></span> to clear the input line.</p>
<h2><a class="anchor" id="special-case-escape"></a>
Special Case: The escape Character</h2>
<p>The escape key can be used standalone, for example, to switch from insertion mode to normal mode when using Vi keybindings. Escape may also be used as a "meta" key, to indicate the start of an escape sequence, such as function or arrow keys. Custom bindings can also be defined that begin with an escape character.</p>
<p>fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape. The waiting period is set to 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the <code>fish_escape_delay_ms</code> variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session.</p>
<p>Note: fish 2.2.0 and earlier used a default of 10 milliseconds, and provided no way to configure it. That effectively made it impossible to use escape as a meta key.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="block"></a>
block - temporarily block delivery of events</h1>
<h2><a class="anchor" id="block-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">block</span> <span class="argument">[OPTIONS...]</span>
</pre><h2><a class="anchor" id="block-description"></a>
Description</h2>
<p><code>block</code> prevents events triggered by <code>fish</code> or the <a href="commands.html#emit"><code>emit</code></a> command from being delivered and acted upon while the block is in place.</p>
<p>In functions, <code>block</code> can be useful while performing work that should not be interrupted by the shell.</p>
<p>The block can be removed. Any events which triggered while the block was in place will then be delivered.</p>
<p>Event blocks should not be confused with code blocks, which are created with <code>begin</code>, <code>if</code>, <code>while</code> or <code>for</code></p>
<p>The following parameters are available:</p>
<ul>
<li><code>-l</code> or <code>--local</code> Release the block automatically at the end of the current innermost code block scope</li>
<li><code>-g</code> or <code>--global</code> Never automatically release the lock</li>
<li><code>-e</code> or <code>--erase</code> Release global block</li>
</ul>
<h2><a class="anchor" id="block-example"></a>
Example</h2>
<pre class="fish">
<span class="comment"># Create a function that listens for events</span>
<span class="command">function</span> <span class="argument">--on-event</span> <span class="argument">foo</span> <span class="argument">foo</span><span class="redirect">;</span> <span class="command">echo</span> <span class="string">'foo fired'</span><span class="redirect">;</span> <span class="command">end</span>
<span class="comment"># Block the delivery of events</span>
<span class="command">block</span> <span class="argument">-g</span>
<span class="command">emit</span> <span class="argument">foo</span>
<span class="comment"># No output will be produced</span>
<span class="command">block</span> <span class="argument">-e</span>
<span class="comment"># 'foo fired' will now be printed</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="break"></a>
break - stop the current inner loop</h1>
<h2><a class="anchor" id="break-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="argument">LOOP_CONSTRUCT</span><span class="redirect">;</span> <span class="argument">[COMMANDS...]</span> <span class="command">break</span><span class="redirect">;</span> <span class="argument">[COMMANDS...]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="break-description"></a>
Description</h2>
<p><code>break</code> halts a currently running loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.</p>
<p>There are no parameters for <code>break</code>.</p>
<h2><a class="anchor" id="break-example"></a>
Example</h2>
<p>The following code searches all .c files for "smurf", and halts at the first occurrence.</p>
<pre class="fish">
<span class="command">for</span> <span class="argument">i</span> <span class="command">in</span> <span class="file">*.c</span>
<span class="command">if</span> <span class="binary">grep</span> <span class="argument">smurf</span> <span class="variable"><span class="operator">$</span>i</span>
<span class="command">echo</span> <span class="argument">Smurfs</span> <span class="argument">are</span> <span class="argument">present</span> <span class="argument">in</span> <span class="variable"><span class="operator">$</span>i</span>
<span class="command">break</span>
<span class="command">end</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="breakpoint"></a>
breakpoint - Launch debug mode</h1>
<h2><a class="anchor" id="breakpoint-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">breakpoint</span>
</pre><h2><a class="anchor" id="breakpoint-description"></a>
Description</h2>
<p><code>breakpoint</code> is used to halt a running script and launch an interactive debugging prompt.</p>
<p>For more details, see <a href="index.html#debugging">Debugging fish scripts</a> in the <code>fish</code> manual.</p>
<p>There are no parameters for <code>breakpoint</code>.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="builtin"></a>
builtin - run a builtin command</h1>
<h2><a class="anchor" id="builtin-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">builtin</span> <span class="argument">BUILTINNAME</span> <span class="argument">[OPTIONS...]</span>
</pre><h2><a class="anchor" id="builtin-description"></a>
Description</h2>
<p><code>builtin</code> forces the shell to use a builtin command, rather than a function or program.</p>
<p>The following parameters are available:</p>
<ul>
<li><code>-n</code> or <code>--names</code> List the names of all defined builtins</li>
</ul>
<h2><a class="anchor" id="builtin-example"></a>
Example</h2>
<pre class="fish">
<span class="command">builtin</span> <span class="command">jobs</span>
<span class="comment"># executes the jobs builtin, even if a function named jobs exists</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="case"></a>
case - conditionally execute a block of commands</h1>
<h2><a class="anchor" id="case-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">switch</span> <span class="argument">VALUE</span><span class="redirect">;</span> <span class="argument">[</span><span class="command">case</span> <span class="argument">[WILDCARD...]</span><span class="redirect">;</span> <span class="argument">[COMMANDS...]</span><span class="redirect">;</span> <span class="argument">...]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="case-description"></a>
Description</h2>
<p><code>switch</code> performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. <code>case</code> is used together with the <code>switch</code> statement in order to determine which block should be executed.</p>
<p>Each <code>case</code> command is given one or more parameters. The first <code>case</code> command with a parameter that matches the string specified in the switch command will be evaluated. <code>case</code> parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.</p>
<p>Note that fish does not fall through on case statements. Only the first matching case is executed.</p>
<p>Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.</p>
<h2><a class="anchor" id="case-example"></a>
Example</h2>
<p>If the variable $animal contains the name of an animal, the following code would attempt to classify it:</p>
<pre class="fish">
<span class="command">switch</span> <span class="variable"><span class="operator">$</span>animal</span>
<span class="command">case</span> <span class="argument">cat</span>
<span class="command">echo</span> <span class="argument">evil</span>
<span class="command">case</span> <span class="argument">wolf</span> <span class="argument">dog</span> <span class="argument">human</span> <span class="argument">moose</span> <span class="argument">dolphin</span> <span class="argument">whale</span>
<span class="command">echo</span> <span class="argument">mammal</span>
<span class="command">case</span> <span class="argument">duck</span> <span class="argument">goose</span> <span class="argument">albatross</span>
<span class="command">echo</span> <span class="argument">bird</span>
<span class="command">case</span> <span class="argument">shark</span> <span class="argument">trout</span> <span class="argument">stingray</span>
<span class="command">echo</span> <span class="argument">fish</span>
<span class="comment"># Note that the next case has a wildcard which is quoted</span>
<span class="command">case</span> <span class="string">'*'</span>
<span class="command">echo</span> <span class="argument">I</span> <span class="argument">have</span> <span class="argument">no</span> <span class="argument">idea</span> <span class="argument">what</span> <span class="argument">a</span> <span class="variable"><span class="operator">$</span>animal</span> <span class="argument">is</span>
<span class="command">end</span>
</pre><p>If the above code was run with <code>$animal</code> set to <code>whale</code>, the output would be <code>mammal</code>.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="cd"></a>
cd - change directory</h1>
<h2><a class="anchor" id="cd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">cd</span> <span class="argument">[DIRECTORY]</span>
</pre><h2><a class="anchor" id="cd-description"></a>
Description</h2>
<p><code>cd</code> changes the current working directory.</p>
<p>If <code>DIRECTORY</code> is supplied, it will become the new directory. If no parameter is given, the contents of the <code>HOME</code> environment variable will be used.</p>
<p>If <code>DIRECTORY</code> is a relative path, the paths found in the <code>CDPATH</code> environment variable array will be tried as prefixes for the specified path.</p>
<p>Note that the shell will attempt to change directory without requiring <code>cd</code> if the name of a directory is provided (starting with <code>.</code>, <code>/</code> or <code>~</code>, or ending with <code>/</code>).</p>
<p>Fish also ships a wrapper function around the builtin <code>cd</code> that understands <code>cd -</code> as changing to the previous directory. See also <a href="commands.html#prevd"><code>prevd</code></a>. This wrapper function maintains a history of the 25 most recently visited directories in the <code>$dirprev</code> and <code>$dirnext</code> global variables.</p>
<h2><a class="anchor" id="cd-example"></a>
Examples</h2>
<pre class="fish">
<span class="command">cd</span>
<span class="comment"># changes the working directory to your home directory.</span>
<span class="command">cd</span> <span class="path">/usr/src/fish-shell</span>
<span class="comment"># changes the working directory to /usr/src/fish-shell</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="command"></a>
command - run a program</h1>
<h2><a class="anchor" id="command-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">command</span> <span class="argument">[OPTIONS]</span> <span class="argument">COMMANDNAME</span> <span class="argument">[ARGS...]</span>
</pre><h2><a class="anchor" id="command-description"></a>
Description</h2>
<p><code>command</code> forces the shell to execute the program <code>COMMANDNAME</code> and ignore any functions or builtins with the same name.</p>
<p>The following options are available:</p>
<ul>
<li><code>-s</code> or <code>--search</code> returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <code>$PATH</code>.</li>
</ul>
<p>With the <code>-s</code> option, <code>command</code> treats every argument as a separate command to look up and sets the exit status to 0 if any of the specified commands were found, or 1 if no commands could be found.</p>
<p>For basic compatibility with POSIX <code>command</code>, the <code>-v</code> flag is recognized as an alias for <code>-s</code>.</p>
<h2><a class="anchor" id="command-example"></a>
Examples</h2>
<p><code>command ls</code> causes fish to execute the <code>ls</code> program, even if an <code>ls</code> function exists.</p>
<p><code>command -s ls</code> returns the path to the <code>ls</code> program.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="commandline"></a>
commandline - set or get the current command line buffer</h1>
<h2><a class="anchor" id="commandline-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">commandline</span> <span class="argument">[OPTIONS]</span> <span class="argument">[CMD]</span>
</pre><h2><a class="anchor" id="commandline-description"></a>
Description</h2>
<p><code>commandline</code> can be used to set or get the current contents of the command line buffer.</p>
<p>With no parameters, <code>commandline</code> returns the current value of the command line.</p>
<p>With <code>CMD</code> specified, the command line buffer is erased and replaced with the contents of <code>CMD</code>.</p>
<p>The following options are available:</p>
<ul>
<li><code>-C</code> or <code>--cursor</code> set or get the current cursor position, not the contents of the buffer. If no argument is given, the current cursor position is printed, otherwise the argument is interpreted as the new cursor position.</li>
<li><code>-f</code> or <code>--function</code> inject readline functions into the reader. This option cannot be combined with any other option. It will cause any additional arguments to be interpreted as readline functions, and these functions will be injected into the reader, so that they will be returned to the reader before any additional actual key presses are read.</li>
</ul>
<p>The following options change the way <code>commandline</code> updates the command line buffer:</p>
<ul>
<li><code>-a</code> or <code>--append</code> do not remove the current commandline, append the specified string at the end of it</li>
<li><code>-i</code> or <code>--insert</code> do not remove the current commandline, insert the specified string at the current cursor position</li>
<li><code>-r</code> or <code>--replace</code> remove the current commandline and replace it with the specified string (default)</li>
</ul>
<p>The following options change what part of the commandline is printed or updated:</p>
<ul>
<li><code>-b</code> or <code>--current-buffer</code> select the entire buffer (default)</li>
<li><code>-j</code> or <code>--current-job</code> select the current job</li>
<li><code>-p</code> or <code>--current-process</code> select the current process</li>
<li><code>-t</code> or <code>--current-token</code> select the current token.</li>
</ul>
<p>The following options change the way <code>commandline</code> prints the current commandline buffer:</p>
<ul>
<li><code>-c</code> or <code>--cut-at-cursor</code> only print selection up until the current cursor position</li>
<li><code>-o</code> or <code>--tokenize</code> tokenize the selection and print one string-type token per line</li>
</ul>
<p>If <code>commandline</code> is called during a call to complete a given string using <code>complete -C STRING</code>, <code>commandline</code> will consider the specified string to be the current contents of the command line.</p>
<p>The following options output metadata about the commandline state:</p>
<ul>
<li><code>-L</code> or <code>--line</code> print the line that the cursor is on, with the topmost line starting at 1</li>
<li><code>-S</code> or <code>--search-mode</code> evaluates to true if the commandline is performing a history search</li>
<li><code>-P</code> or <code>--paging-mode</code> evaluates to true if the commandline is showing pager contents, such as tab completions</li>
</ul>
<h2><a class="anchor" id="commandline-example"></a>
Example</h2>
<p><code>commandline -j $history[3]</code> replaces the job under the cursor with the third item from the command line history.</p>
<p>If the commandline contains </p>
<pre class="fish">
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>fl</span><span class="cursor">o</span><span class="argument">under</span> <span class="redirect">>&2</span> <span class="redirect">|</span> <span class="binary">less</span><span class="redirect">;</span> <span class="command">and</span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>catfish</span>
</pre><p>(with the cursor on the "o" of "flounder")</p>
<p>Then the following invocations behave like this: </p>
<pre class="fish">
<span class="prompt">></span> <span class="command">commandline</span> <span class="argument">-t</span>
<span class="variable"><span class="operator">$</span>flounder</span>
<span class="prompt">></span> <span class="command">commandline</span> <span class="argument">-ct</span>
<span class="variable"><span class="operator">$</span>fl</span>
<span class="prompt">></span> <span class="command">commandline</span> <span class="argument">-b</span> <span class="comment">## or just commandline</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>flounder</span> <span class="redirect">>&2</span> <span class="redirect">|</span> <span class="binary">less</span><span class="redirect">;</span> <span class="command">and</span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>catfish</span>
<span class="prompt">></span> <span class="command">commandline</span> <span class="argument">-p</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>flounder</span> <span class="redirect">>&2</span>
<span class="prompt">></span> <span class="command">commandline</span> <span class="argument">-j</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>flounder</span> <span class="redirect">>&2</span> <span class="redirect">|</span> <span class="binary">less</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="complete"></a>
complete - edit command specific tab-completions</h1>
<h2><a class="anchor" id="complete-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">complete</span> <span class="operator">(</span> <span class="argument">-c</span> <span class="redirect">|</span> <span class="argument">--command</span> <span class="redirect">|</span> <span class="argument">-p</span> <span class="redirect">|</span> <span class="argument">--path</span> <span class="operator">)</span> <span class="argument">COMMAND</span>
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-c</span> <span class="redirect">|</span> <span class="argument">--command</span> <span class="redirect">|</span> <span class="argument">-p</span> <span class="redirect">|</span> <span class="argument">--path</span> <span class="operator">)</span> <span class="argument">COMMAND]</span>...
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-e</span> <span class="redirect">|</span> <span class="argument">--erase</span> <span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-s</span> <span class="redirect">|</span> <span class="argument">--short-option</span> <span class="operator">)</span> <span class="argument">SHORT_OPTION]</span>...
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-l</span> <span class="redirect">|</span> <span class="argument">--long-option</span> <span class="redirect">|</span> <span class="argument">-o</span> <span class="redirect">|</span> <span class="argument">--old-option</span> <span class="operator">)</span> <span class="argument">LONG_OPTION]</span>...
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-a</span> <span class="redirect">|</span> <span class="argument">--arguments</span> <span class="operator">)</span> <span class="argument">OPTION_ARGUMENTS]</span>
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-f</span> <span class="redirect">|</span> <span class="argument">--no-files</span> <span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-r</span> <span class="redirect">|</span> <span class="argument">--require-parameter</span> <span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-x</span> <span class="redirect">|</span> <span class="argument">--exclusive</span> <span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-w</span> <span class="redirect">|</span> <span class="argument">--wraps</span> <span class="operator">)</span> <span class="argument">WRAPPED_COMMAND]</span>...
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-n</span> <span class="redirect">|</span> <span class="argument">--condition</span> <span class="operator">)</span> <span class="argument">CONDITION]</span>
<span class="argument">[</span><span class="operator">(</span> <span class="argument">-d</span> <span class="redirect">|</span> <span class="argument">--description</span> <span class="operator">)</span> <span class="argument">DESCRIPTION]</span>
<span class="command">complete</span> <span class="operator">(</span> <span class="argument">-C</span><span class="argument">[STRING]</span> <span class="redirect">|</span> <span class="argument">--do-complete</span>[=STRING] <span class="operator">)</span>
</pre><h2><a class="anchor" id="complete-description"></a>
Description</h2>
<p>For an introduction to specifying completions, see <a href="index.html#completion-own">Writing your own completions</a> in the fish manual.</p>
<ul>
<li><code>COMMAND</code> is the name of the command for which to add a completion.</li>
<li><code>SHORT_OPTION</code> is a one character option for the command.</li>
<li><code>LONG_OPTION</code> is a multi character option for the command.</li>
<li><code>OPTION_ARGUMENTS</code> is parameter containing a space-separated list of possible option-arguments, which may contain command substitutions.</li>
<li><code>DESCRIPTION</code> is a description of what the option and/or option arguments do.</li>
<li><code>-c COMMAND</code> or <code>--command COMMAND</code> specifies that <code>COMMAND</code> is the name of the command.</li>
<li><code>-p COMMAND</code> or <code>--path COMMAND</code> specifies that <code>COMMAND</code> is the absolute path of the program (optionally containing wildcards).</li>
<li><code>-e</code> or <code>--erase</code> deletes the specified completion.</li>
<li><code>-s SHORT_OPTION</code> or <code>--short-option=SHORT_OPTION</code> adds a short option to the completions list.</li>
<li><code>-l LONG_OPTION</code> or <code>--long-option=LONG_OPTION</code> adds a GNU style long option to the completions list.</li>
<li><code>-o LONG_OPTION</code> or <code>--old-option=LONG_OPTION</code> adds an old style long option to the completions list (See below for details).</li>
<li><code>-a OPTION_ARGUMENTS</code> or <code>--arguments=OPTION_ARGUMENTS</code> adds the specified option arguments to the completions list.</li>
<li><code>-f</code> or <code>--no-files</code> specifies that the options specified by this completion may not be followed by a filename.</li>
<li><code>-r</code> or <code>--require-parameter</code> specifies that the options specified by this completion always must have an option argument, i.e. may not be followed by another option.</li>
<li><code>-x</code> or <code>--exclusive</code> implies both <code>-r</code> and <code>-f</code>.</li>
<li><code>-w WRAPPED_COMMAND</code> or <code>--wraps=WRAPPED_COMMAND</code> causes the specified command to inherit completions from the wrapped command (See below for details).</li>
<li><code>-n</code> or <code>--condition</code> specifies a shell command that must return 0 if the completion is to be used. This makes it possible to specify completions that should only be used in some cases.</li>
<li><code>-CSTRING</code> or <code>--do-complete=STRING</code> makes complete try to find all possible completions for the specified string.</li>
<li><code>-C</code> or <code>--do-complete</code> with no argument makes complete try to find all possible completions for the current command line buffer. If the shell is not in interactive mode, an error is returned.</li>
</ul>
<p>Command specific tab-completions in <code>fish</code> are based on the notion of options and arguments. An option is a parameter which begins with a hyphen, such as '<code>-h</code>', '<code>-help</code>' or '<code>--help</code>'. Arguments are parameters that do not begin with a hyphen. Fish recognizes three styles of options, the same styles as the GNU version of the getopt library. These styles are:</p>
<ul>
<li>Short options, like '<code>-a</code>'. Short options are a single character long, are preceded by a single hyphen and may be grouped together (like '<code>-la</code>', which is equivalent to '<code>-l -a</code>'). Option arguments may be specified in the following parameter ('<code>-w 32</code>') or by appending the option with the value ('<code>-w32</code>').</li>
<li>Old style long options, like '<code>-Wall</code>'. Old style long options can be more than one character long, are preceded by a single hyphen and may not be grouped together. Option arguments are specified in the following parameter ('<code>-ao null</code>').</li>
<li>GNU style long options, like '<code>--colors</code>'. GNU style long options can be more than one character long, are preceded by two hyphens, and may not be grouped together. Option arguments may be specified in the following parameter ('<code>--quoting-style shell</code>') or by appending the option with a '<code>=</code>' and the value ('<code>--quoting-style=shell</code>'). GNU style long options may be abbreviated so long as the abbreviation is unique ('<code>--h</code>') is equivalent to '<code>--help</code>' if help is the only long option beginning with an 'h').</li>
</ul>
<p>The options for specifying command name and command path may be used multiple times to define the same completions for multiple commands.</p>
<p>The options for specifying command switches and wrapped commands may be used multiple times to define multiple completions for the command(s) in a single call.</p>
<p>Invoking <code>complete</code> multiple times for the same command adds the new definitions on top of any existing completions defined for the command.</p>
<p>When <code>-a</code> or <code>--arguments</code> is specified in conjunction with long, short, or old style options, the specified arguments are only used as completions when attempting to complete an argument for any of the specified options. If <code>-a</code> or <code>--arguments</code> is specified without any long, short, or old style options, the specified arguments are used when completing any argument to the command (except when completing an option argument that was specified with <code>-r</code> or <code>--require-parameter</code>).</p>
<p>Command substitutions found in <code>OPTION_ARGUMENTS</code> are not expected to return a space-separated list of arguments. Instead they must return a newline-separated list of arguments, and each argument may optionally have a tab character followed by the argument description. Any description provided in this way overrides a description given with <code>-d</code> or <code>--description</code>.</p>
<p>The <code>-w</code> or <code>--wraps</code> options causes the specified command to inherit completions from another command. The inheriting command is said to "wrap" the inherited command. The wrapping command may have its own completions in addition to inherited ones. A command may wrap multiple commands, and wrapping is transitive: if A wraps B, and B wraps C, then A automatically inherits all of C's completions. Wrapping can be removed using the <code>-e</code> or <code>--erase</code> options. Note that wrapping only works for completions specified with <code>-c</code> or <code>--command</code> and are ignored when specifying completions with <code>-p</code> or <code>--path</code>.</p>
<p>When erasing completions, it is possible to either erase all completions for a specific command by specifying <code>complete -c COMMAND -e</code>, or by specifying a specific completion option to delete by specifying either a long, short or old style option.</p>
<h2><a class="anchor" id="complete-example"></a>
Example</h2>
<p>The short style option <code>-o</code> for the <code>gcc</code> command requires that a file follows it. This can be done using writing:</p>
<pre class="fish">
<span class="command">complete</span> <span class="argument">-c</span> <span class="argument">gcc</span> <span class="argument">-s</span> <span class="argument">o</span> <span class="argument">-r</span>
</pre><p>The short style option <code>-d</code> for the <code>grep</code> command requires that one of the strings '<code>read</code>', '<code>skip</code>' or '<code>recurse</code>' is used. This can be specified writing:</p>
<pre class="fish">
<span class="command">complete</span> <span class="argument">-c</span> <span class="argument">grep</span> <span class="argument">-s</span> <span class="argument">d</span> <span class="argument">-x</span> <span class="argument">-a</span> <span class="string">"read skip recurse"</span>
</pre><p>The <code>su</code> command takes any username as an argument. Usernames are given as the first colon-separated field in the file /etc/passwd. This can be specified as:</p>
<pre class="fish">
<span class="command">complete</span> <span class="argument">-x</span> <span class="argument">-c</span> <span class="argument">su</span> <span class="argument">-d</span> <span class="string">"Username"</span> <span class="argument">-a</span> <span class="string">"<span class="operator">(</span>cat /etc/passwd | cut -d : -f 1<span class="operator">)</span>"</span>
</pre><p>The <code>rpm</code> command has several different modes. If the <code>-e</code> or <code>--erase</code> flag has been specified, <code>rpm</code> should delete one or more packages, in which case several switches related to deleting packages are valid, like the <code>nodeps</code> switch.</p>
<p>This can be written as:</p>
<pre class="fish">
<span class="command">complete</span> <span class="argument">-c</span> <span class="argument">rpm</span> <span class="argument">-n</span> <span class="string">"__fish_contains_opt -s e erase"</span> <span class="argument">-d</span> <span class="argument">nodeps</span> <span class="string">"Don't check dependencies"</span>
</pre><p>where <code>__fish_contains_opt</code> is a function that checks the command line buffer for the presence of a specified set of options.</p>
<p>To implement an alias, use the <code>-w</code> or <code>--wraps</code> option:</p>
<pre class="fish">
<span class="command">complete</span> <span class="argument">-c</span> <span class="argument">hub</span> <span class="argument">-w</span> <span class="argument">git</span>
</pre><p>Now hub inherits all of the completions from git. Note this can also be specified in a function declaration.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="contains"></a>
contains - test if a word is present in a list</h1>
<h2><a class="anchor" id="contains-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">contains</span> <span class="argument">[OPTIONS]</span> <span class="argument">KEY</span> <span class="argument">[VALUES...]</span>
</pre><h2><a class="anchor" id="contains-description"></a>
Description</h2>
<p><code>contains</code> tests whether the set <code>VALUES</code> contains the string <code>KEY</code>. If so, <code>contains</code> exits with status 0; if not, it exits with status 1.</p>
<p>The following options are available:</p>
<ul>
<li><code>-i</code> or <code>--index</code> print the word index</li>
</ul>
<p>Note that, like GNU tools, <code>contains</code> interprets all arguments starting with a <code>-</code> as options to contains, until it reaches an argument that is <code>--</code> (two dashes). See the examples below.</p>
<h2><a class="anchor" id="contains-example"></a>
Example</h2>
<pre class="fish">
<span class="command">for</span> <span class="argument">i</span> <span class="command">in</span> <span class="path">~/bin</span> <span class="path">/usr/local/bin</span>
<span class="command">if</span> <span class="command">not</span> <span class="command">contains</span> <span class="variable"><span class="operator">$</span>i</span> <span class="variable"><span class="operator">$</span>PATH</span>
<span class="command">set</span> <span class="argument">PATH</span> <span class="variable"><span class="operator">$</span>PATH</span> <span class="variable"><span class="operator">$</span>i</span>
<span class="command">end</span>
<span class="command">end</span>
</pre><p>The above code tests if <code>~/bin</code> and <code>/usr/local/bin</code> are in the path and adds them if not.</p>
<pre class="fish">
<span class="command">function</span> <span class="argument">hasargs</span>
<span class="command">if</span> <span class="command">contains</span> <span class="argument">--</span> <span class="argument">-q</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">echo</span> <span class="string">'$argv contains a -q option'</span>
<span class="command">end</span>
<span class="command">end</span>
</pre><p>The above code checks for <code>-q</code> in the argument list, using the <code>--</code> argument to demarcate options to <code>contains</code> from the key to search for.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="continue"></a>
continue - skip the remainder of the current iteration of the current inner loop</h1>
<h2><a class="anchor" id="continue-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="argument">LOOP_CONSTRUCT</span><span class="redirect">;</span> <span class="argument">[COMMANDS...;]</span> <span class="command">continue</span><span class="redirect">;</span> <span class="argument">[COMMANDS...;]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="continue-description"></a>
Description</h2>
<p><code>continue</code> skips the remainder of the current iteration of the current inner loop, such as a <a href="#for">for</a> loop or a <a href="#while">while</a> loop. It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement.</p>
<h2><a class="anchor" id="continue-example"></a>
Example</h2>
<p>The following code removes all tmp files that do not contain the word smurf.</p>
<pre class="fish">
<span class="command">for</span> <span class="argument">i</span> <span class="command">in</span> <span class="file">*.tmp</span>
<span class="command">if</span> <span class="binary">grep</span> <span class="argument">smurf</span> <span class="variable"><span class="operator">$</span>i</span>
<span class="command">continue</span>
<span class="command">end</span>
<span class="binary">rm</span> <span class="variable"><span class="operator">$</span>i</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="count"></a>
count - count the number of elements of an array</h1>
<h2><a class="anchor" id="count-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">count</span> <span class="variable"><span class="operator">$</span>VARIABLE</span>
</pre><h2><a class="anchor" id="count-description"></a>
Description</h2>
<p><code>count</code> prints the number of arguments that were passed to it. This is usually used to find out how many elements an environment variable array contains.</p>
<p><code>count</code> does not accept any options, including <code>-h</code> or <code>--help</code>.</p>
<p><code>count</code> exits with a non-zero exit status if no arguments were passed to it, and with zero if at least one argument was passed.</p>
<h2><a class="anchor" id="count-example"></a>
Example</h2>
<pre class="fish">
<span class="command">count</span> <span class="variable"><span class="operator">$</span>PATH</span>
<span class="comment"># Returns the number of directories in the users PATH variable.</span>
<span class="command">count</span> <span class="file">*.txt</span>
<span class="comment"># Returns the number of files in the current working directory ending with the suffix '.txt'.</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="dirh"></a>
dirh - print directory history</h1>
<h2><a class="anchor" id="dirh-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">dirh</span>
</pre><h2><a class="anchor" id="dirh-description"></a>
Description</h2>
<p><code>dirh</code> prints the current directory history. The current position in the history is highlighted using the color defined in the <code>fish_color_history_current</code> environment variable.</p>
<p><code>dirh</code> does not accept any parameters.</p>
<p>Note that the <code>cd</code> command limits directory history to the 25 most recently visited directories. The history is stored in the <code>$dirprev</code> and <code>$dirnext</code> variables.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="dirs"></a>
dirs - print directory stack</h1>
<h2><a class="anchor" id="dirs-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">dirs</span>
<span class="command">dirs</span> <span class="argument">-c</span>
</pre><h2><a class="anchor" id="dirs-description"></a>
Description</h2>
<p><code>dirs</code> prints the current directory stack, as created by the <a href="#pushd"><code>pushd</code></a> command.</p>
<p>With "-c", it clears the directory stack instead.</p>
<p><code>dirs</code> does not accept any parameters.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="echo"></a>
echo - display a line of text</h1>
<h2><a class="anchor" id="echo-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">echo</span> <span class="argument">[OPTIONS]</span> <span class="argument">[STRING]</span>
</pre><h2><a class="anchor" id="echo-description"></a>
Description</h2>
<p><code>echo</code> displays a string of text.</p>
<p>The following options are available:</p>
<ul>
<li><code>-n</code>, Do not output a newline</li>
<li><code>-s</code>, Do not separate arguments with spaces</li>
<li><code>-E</code>, Disable interpretation of backslash escapes (default)</li>
<li><code>-e</code>, Enable interpretation of backslash escapes</li>
</ul>
<h2><a class="anchor" id="echo-escapes"></a>
Escape Sequences</h2>
<p>If <code>-e</code> is used, the following sequences are recognized:</p>
<ul>
<li><code>\</code> backslash</li>
<li><code>\a</code> alert (BEL)</li>
<li><code>\b</code> backspace</li>
<li><code>\c</code> produce no further output</li>
<li><code>\e</code> escape</li>
<li><code>\f</code> form feed</li>
<li><code>\n</code> new line</li>
<li><code>\r</code> carriage return</li>
<li><code>\t</code> horizontal tab</li>
<li><code>\v</code> vertical tab</li>
<li><code>\0NNN</code> byte with octal value NNN (1 to 3 digits)</li>
<li><code>\xHH</code> byte with hexadecimal value HH (1 to 2 digits)</li>
</ul>
<h2><a class="anchor" id="echo-example"></a>
Example</h2>
<pre class="fish">
<span class="command">echo</span> <span class="string">'Hello World'</span>
</pre><p>Print hello world to stdout</p>
<pre class="fish">
<span class="command">echo</span> <span class="argument">-e</span> <span class="string">'Top<span>\</span>nBottom'</span>
</pre><p>Print Top and Bottom on separate lines, using an escape sequence</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="else"></a>
else - execute command if a condition is not met</h1>
<h2><a class="anchor" id="else-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">if</span> <span class="argument">CONDITION</span><span class="redirect">;</span> <span class="argument">COMMANDS_TRUE...</span><span class="redirect">;</span> <span class="argument">[<span class="command">else</span><span class="redirect">;</span> <span class="argument">COMMANDS_FALSE...</span>;]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="else-description"></a>
Description</h2>
<p><code>if</code> will execute the command <code>CONDITION</code>. If the condition's exit status is 0, the commands <code>COMMANDS_TRUE</code> will execute. If it is not 0 and <code>else</code> is given, <code>COMMANDS_FALSE</code> will be executed.</p>
<h2><a class="anchor" id="else-example"></a>
Example</h2>
<p>The following code tests whether a file <code>foo.txt</code> exists as a regular file.</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="argument">-f</span> <span class="file">foo.txt</span>
<span class="command">echo</span> <span class="argument">foo.txt</span> <span class="argument">exists</span>
<span class="command">else</span>
<span class="command">echo</span> <span class="argument">foo.txt</span> <span class="argument">does</span> <span class="argument">not</span> <span class="argument">exist</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="emit"></a>
emit - Emit a generic event</h1>
<h2><a class="anchor" id="emit-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">emit</span> <span class="argument">EVENT_NAME</span> <span class="argument">[ARGUMENTS...]</span>
</pre><h2><a class="anchor" id="emit-description"></a>
Description</h2>
<p><code>emit</code> emits, or fires, an event. Events are delivered to, or caught by, special functions called event handlers. The arguments are passed to the event handlers as function arguments.</p>
<h2><a class="anchor" id="emit-example"></a>
Example</h2>
<p>The following code first defines an event handler for the generic event named 'test_event', and then emits an event of that type.</p>
<pre class="fish">
<span class="command">function</span> <span class="argument">event_test</span> <span class="argument">--on-event</span> <span class="argument">test_event</span>
<span class="command">echo</span> <span class="argument">event</span> <span class="argument">test:</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
<span class="command">emit</span> <span class="argument">test_event</span> <span class="argument">something</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="end"></a>
end - end a block of commands.</h1>
<h2><a class="anchor" id="end-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">begin</span><span class="redirect">;</span> <span class="argument">[COMMANDS...]</span> <span class="command">end</span>
<span class="command">if</span> <span class="argument">CONDITION</span><span class="redirect">;</span> <span class="argument">COMMANDS_TRUE...</span><span class="redirect">;</span> <span class="argument">[<span class="command">else</span><span class="redirect">;</span> <span class="argument">COMMANDS_FALSE...</span>;]</span> <span class="command">end</span>
<span class="command">while</span> <span class="argument">CONDITION</span><span class="redirect">;</span> <span class="argument">COMMANDS...</span><span class="redirect">;</span> <span class="command">end</span>
<span class="command">for</span> <span class="argument">VARNAME</span> <span class="command">in</span> <span class="argument">[VALUES...]</span><span class="redirect">;</span> <span class="argument">COMMANDS...</span><span class="redirect">;</span> <span class="command">end</span>
<span class="command">switch</span> <span class="argument">VALUE</span><span class="redirect">;</span> <span class="argument">[</span><span class="command">case</span> <span class="argument">[WILDCARD...]</span><span class="redirect">;</span> <span class="argument">[COMMANDS...]</span><span class="redirect">;</span> <span class="argument">...]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="end-description"></a>
Description</h2>
<p><code>end</code> ends a block of commands.</p>
<p>For more information, read the documentation for the block constructs, such as <code>if</code>, <code>for</code> and <code>while</code>.</p>
<p>The <code>end</code> command does not change the current exit status.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="eval"></a>
eval - evaluate the specified commands</h1>
<h2><a class="anchor" id="eval-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">eval</span> <span class="argument">[COMMANDS...]</span>
</pre><h2><a class="anchor" id="eval-description"></a>
Description</h2>
<p><code>eval</code> evaluates the specified parameters as a command. If more than one parameter is specified, all parameters will be joined using a space character as a separator.</p>
<h2><a class="anchor" id="eval-example"></a>
Example</h2>
<p>The following code will call the ls command. Note that <code>fish</code> does not support the use of shell variables as direct commands; <code>eval</code> can be used to work around this.</p>
<pre class="fish">
<span class="command">set</span> <span class="argument">cmd</span> <span class="argument">ls</span>
<span class="command">eval</span> <span class="variable"><span class="operator">$</span>cmd</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="exec"></a>
exec - execute command in current process</h1>
<h2><a class="anchor" id="exec-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">exec</span> <span class="argument">COMMAND</span> <span class="argument">[OPTIONS...]</span>
</pre><h2><a class="anchor" id="exec-description"></a>
Description</h2>
<p><code>exec</code> replaces the currently running shell with a new command. On successful completion, <code>exec</code> never returns. <code>exec</code> cannot be used inside a pipeline.</p>
<h2><a class="anchor" id="exec-example"></a>
Example</h2>
<p><code>exec emacs</code> starts up the emacs text editor, and exits <code>fish</code>. When emacs exits, the session will terminate.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="exit"></a>
exit - exit the shell</h1>
<h2><a class="anchor" id="exit-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">exit</span> <span class="argument">[STATUS]</span>
</pre><h2><a class="anchor" id="exit-description"></a>
Description</h2>
<p><code>exit</code> causes fish to exit. If <code>STATUS</code> is supplied, it will be converted to an integer and used as the exit code. Otherwise, the exit code will be that of the last command executed.</p>
<p>If exit is called while sourcing a file (using the <a href="#source">source</a> builtin) the rest of the file will be skipped, but the shell itself will not exit.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="false"></a>
false - return an unsuccessful result</h1>
<h2><a class="anchor" id="false-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">false</span>
</pre><h2><a class="anchor" id="false-description"></a>
Description</h2>
<p><code>false</code> sets the exit status to 1.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fg"></a>
fg - bring job to foreground</h1>
<h2><a class="anchor" id="fg-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">fg</span> <span class="argument">[PID]</span>
</pre><h2><a class="anchor" id="fg-description"></a>
Description</h2>
<p><code>fg</code> brings the specified <a href="index.html#syntax-job-control">job</a> to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.</p>
<p>The PID of the desired process is usually found by using <a href="index.html#expand-process">process expansion</a>. Fish is capable of expanding far more than just the numeric PID, including referencing itself and finding PIDs by name.</p>
<h2><a class="anchor" id="fg-example"></a>
Example</h2>
<p><code>fg %1</code> will put the job with job ID 1 in the foreground.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish"></a>
fish - the friendly interactive shell</h1>
<h2><a class="anchor" id="fish-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">fish</span> <span class="argument">[OPTIONS]</span> <span class="argument">[</span><span class="argument">-c</span> <span class="argument">command]</span> <span class="argument">[FILE</span> <span class="argument">[ARGUMENTS...]]</span>
</pre><h2><a class="anchor" id="fish-description"></a>
Description</h2>
<p><code>fish</code> is a command-line shell written mainly with interactive use in mind. The full manual is available <a href="index.html">in HTML</a> by using the <a href="#help">help</a> command from inside fish.</p>
<p>The following options are available:</p>
<ul>
<li><code>-c</code> or <code>--command=COMMANDS</code> evaluate the specified commands instead of reading from the commandline</li>
<li><code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> specify the verbosity level of fish. A higher number means higher verbosity. The default level is 1.</li>
<li><code>-i</code> or <code>--interactive</code> specify that fish is to run in interactive mode</li>
<li><code>-l</code> or <code>--login</code> specify that fish is to run as a login shell</li>
<li><code>-n</code> or <code>--no-execute</code> do not execute any commands, only perform syntax checking</li>
<li><code>-p</code> or <code>--profile=PROFILE_FILE</code> when fish exits, output timing information on all executed commands to the specified file</li>
<li><code>-v</code> or <code>--version</code> display version and exit</li>
<li><code>-D</code> or <code>--debug-stack-frames=DEBUG_LEVEL</code> specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.</li>
</ul>
<p>The fish exit status is generally the exit status of the last foreground command. If fish is exiting because of a parse error, the exit status is 127.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_config"></a>
fish_config - start the web-based configuration interface</h1>
<h2><a class="anchor" id="fish_config-description"></a>
Description</h2>
<p><code>fish_config</code> starts the web-based configuration interface.</p>
<p>The web interface allows you to view your functions, variables and history, and to make changes to your prompt and color configuration.</p>
<p><code>fish_config</code> starts a local web server and then opens a web browser window; when you have finished, close the browser window and then press the Enter key to terminate the configuration session.</p>
<p><code>fish_config</code> optionally accepts name of the initial configuration tab. For e.g. <code>fish_config history</code> will start configuration interface with history tab.</p>
<p>If the <code>BROWSER</code> environment variable is set, it will be used as the name of the web browser to open instead of the system default.</p>
<h2><a class="anchor" id="fish_config-example"></a>
Example</h2>
<p><code>fish_config</code> opens a new web browser window and allows you to configure certain fish settings.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_indent"></a>
fish_indent - indenter and prettifier</h1>
<h2><a class="anchor" id="fish_indent-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">fish_indent</span> <span class="argument">[OPTIONS]</span>
</pre><h2><a class="anchor" id="fish_indent-description"></a>
Description</h2>
<p><code>fish_indent</code> is used to indent a piece of fish code. <code>fish_indent</code> reads commands from standard input and outputs them to standard output or a specified file.</p>
<p>The following options are available:</p>
<ul>
<li><code>-w</code> or <code>--write</code> indents a specified file and immediately writes to that file.</li>
<li><code>-i</code> or <code>--no-indent</code> do not indent commands; only reformat to one job per line.</li>
<li><code>-v</code> or <code>--version</code> displays the current fish version and then exits.</li>
<li><code>--ansi</code> colorizes the output using ANSI escape sequences, appropriate for the current $TERM, using the colors defined in the environment (such as <code>$fish_color_command</code>).</li>
<li><code>--html</code> outputs HTML, which supports syntax highlighting if the appropriate CSS is defined. The CSS class names are the same as the variable names, such as <code>fish_color_command</code>.</li>
<li><code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> enables debug output and specifies a verbosity level (like <code>fish -d</code>). Defaults to 0.</li>
<li><code>-D</code> or <code>--debug-stack-frames=DEBUG_LEVEL</code> specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.</li>
<li><code>--dump-parse-tree</code> dumps information about the parsed statements to stderr. This is likely to be of interest only to people working on the fish source code.</li>
</ul>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_key_reader"></a>
fish_key_reader - explore what characters keyboard keys send</h1>
<h2><a class="anchor" id="fish_key_reader-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">fish_key_reader</span> <span class="argument">[OPTIONS]</span>
</pre><h2><a class="anchor" id="fish_key_reader-description"></a>
Description</h2>
<p><code>fish_key_reader</code> is used to study input received from the terminal and can help with key binds. The program is interactive and works on standard input. Individual characters themselves and their hexadecimal values are displayed.</p>
<p>The tool will write an example <code>bind</code> command matching the character sequence captured to stdout. If the character sequence matches a special key name (see <code>bind --key-names</code>), both <code>bind CHARS ...</code> and <code>bind -k KEYNAME ...</code> usage will be shown. Additional details about the characters received, such as the delay between chars, are written to stderr.</p>
<p>The following options are available:</p>
<ul>
<li><code>-c</code> or <code>--continuous</code> begins a session where multiple key sequences can be inspected. By default the program exits after capturing a single key sequence.</li>
<li><code>-d</code> or <code>--debug-level=DEBUG_LEVEL</code> enables debug output and specifies a verbosity level (like <code>fish -d</code>). Defaults to 0.</li>
<li><code>-D</code> or <code>--debug-stack-frames=DEBUG_LEVEL</code> specify how many stack frames to display when debug messages are written. The default is zero. A value of 3 or 4 is usually sufficient to gain insight into how a given debug call was reached but you can specify a value up to 128.</li>
<li><code>-h</code> or <code>--help</code> prints usage information.</li>
</ul>
<h2><a class="anchor" id="fish_key_reader-usage-notes"></a>
Usage Notes</h2>
<p>The delay in milliseconds since the previous character was received is included in the diagnostic information written to stderr. This information may be useful to determine the optimal <code>fish_escape_delay_ms</code> setting or learn the amount of lag introduced by tools like <code>ssh</code>, <code>mosh</code> or <code>tmux</code>.</p>
<p><code>fish_key_reader</code> intentionally disables handling of many signals. To terminate <code>fish_key_reader</code> in <code>--continuous</code> mode do:</p>
<ul>
<li>press <code>Ctrl-C</code> twice, or</li>
<li>press <code>Ctrl-D</code> twice, or</li>
<li>type <code>exit</code>, or</li>
<li>type <code>quit</code></li>
</ul>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_mode_prompt"></a>
fish_mode_prompt - define the appearance of the mode indicator</h1>
<h2><a class="anchor" id="fish_mode_prompt-synopsis"></a>
Synopsis</h2>
<p>fish_mode_prompt will output the mode indicator for use in vi-mode.</p>
<h2><a class="anchor" id="fish_mode_prompt-description"></a>
Description</h2>
<p>The output of <code>fish_mode_prompt</code> will be displayed in the mode indicator position to the left of the regular prompt.</p>
<p>Multiple lines are not supported in <code>fish_mode_prompt</code>.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_prompt"></a>
fish_prompt - define the appearance of the command line prompt</h1>
<h2><a class="anchor" id="fish_prompt-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">function</span> <span class="argument">fish_prompt</span>
<span class="argument">...</span>
<span class="command">end</span>
</pre><h2><a class="anchor" id="fish_prompt-description"></a>
Description</h2>
<p>By defining the <code>fish_prompt</code> function, the user can choose a custom prompt. The <code>fish_prompt</code> function is executed when the prompt is to be shown, and the output is used as a prompt.</p>
<p>The exit status of commands within <code>fish_prompt</code> will not modify the value of <a href="index.html#variables-status">$status</a> outside of the <code>fish_prompt</code> function.</p>
<p><code>fish</code> ships with a number of example prompts that can be chosen with the <code>fish_config</code> command.</p>
<h2><a class="anchor" id="fish_prompt-example"></a>
Example</h2>
<p>A simple prompt:</p>
<pre class="fish">
<span class="command">function</span> <span class="argument">fish_prompt</span> <span class="argument">-d</span> <span class="string">"Write out the prompt"</span>
<span class="command">printf</span> <span class="string">'<span>%</span>s<span>@</span><span>%</span>s<span>%</span>s<span>%</span>s<span>%</span>s> '</span> <span class="operator">(</span><span class="binary">whoami</span><span class="operator">)</span> <span class="operator">(</span><span class="function">hostname</span> <span class="redirect">|</span> <span class="binary">cut</span> <span class="argument">-d</span> <span class="argument">.</span> <span class="argument">-f</span> <span class="argument">1</span><span class="operator">)</span> <span>\</span>
<span class="operator">(</span><span class="command">set_color</span> <span class="variable"><span class="operator">$</span>fish_color_cwd</span><span class="operator">)</span> <span class="operator">(</span><span class="command">prompt_pwd</span><span class="operator">)</span> <span class="operator">(</span><span class="command">set_color</span> <span class="argument">normal</span><span class="operator">)</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_right_prompt"></a>
fish_right_prompt - define the appearance of the right-side command line prompt</h1>
<h2><a class="anchor" id="fish_right_prompt-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">function</span> <span class="argument">fish_right_prompt</span>
<span class="argument">...</span>
<span class="command">end</span>
</pre><h2><a class="anchor" id="fish_right_prompt-description"></a>
Description</h2>
<p><code>fish_right_prompt</code> is similar to <code>fish_prompt</code>, except that it appears on the right side of the terminal window.</p>
<p>Multiple lines are not supported in <code>fish_right_prompt</code>.</p>
<h2><a class="anchor" id="fish_right_prompt-example"></a>
Example</h2>
<p>A simple right prompt:</p>
<pre class="fish">
<span class="command">function</span> <span class="argument">fish_right_prompt</span> <span class="argument">-d</span> <span class="string">"Write out the right prompt"</span>
<span class="binary">date</span> <span class="string">'+<span>%</span>m/<span>%</span>d/<span>%</span>y'</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_update_completions"></a>
fish_update_completions - Update completions using manual pages</h1>
<h2><a class="anchor" id="fish_update_completions-description"></a>
Description</h2>
<p><code>fish_update_completions</code> parses manual pages installed on the system, and attempts to create completion files in the <code>fish</code> configuration directory.</p>
<p>This does not overwrite custom completions.</p>
<p>There are no parameters for <code>fish_update_completions</code>.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="fish_vi_mode"></a>
fish_vi_mode - Enable vi mode</h1>
<h2><a class="anchor" id="fish_vi_mode-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">fish_vi_mode</span>
</pre><h2><a class="anchor" id="fish_vi_mode-description"></a>
Description</h2>
<p>This function is deprecated. Please call <code>fish_vi_key_bindings directly</code></p>
<p><code>fish_vi_mode</code> enters a vi-like command editing mode. To always start in vi mode, add <code>fish_vi_mode</code> to your <code>config.fish</code> file.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="for"></a>
for - perform a set of commands multiple times.</h1>
<h2><a class="anchor" id="for-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">for</span> <span class="argument">VARNAME</span> <span class="command">in</span> <span class="argument">[VALUES...]</span><span class="redirect">;</span> <span class="argument">COMMANDS...</span><span class="redirect">;</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="for-description"></a>
Description</h2>
<p><code>for</code> is a loop construct. It will perform the commands specified by <code>COMMANDS</code> multiple times. On each iteration, the local variable specified by <code>VARNAME</code> is assigned a new value from <code>VALUES</code>. If <code>VALUES</code> is empty, <code>COMMANDS</code> will not be executed at all.</p>
<h2><a class="anchor" id="for-example"></a>
Example</h2>
<pre class="fish">
<span class="command">for</span> <span class="argument">i</span> <span class="command">in</span> <span class="argument">foo</span> <span class="argument">bar</span> <span class="argument">baz</span><span class="redirect">;</span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>i</span><span class="redirect">;</span> <span class="command">end</span>
<span class="comment"># would output:</span>
<span class="argument">foo</span>
<span class="argument">bar</span>
<span class="argument">baz</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="funced"></a>
funced - edit a function interactively</h1>
<h2><a class="anchor" id="funced-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">funced</span> <span class="argument">[OPTIONS]</span> <span class="argument">NAME</span>
</pre><h2><a class="anchor" id="funced-description"></a>
Description</h2>
<p><code>funced</code> provides an interface to edit the definition of the function <code>NAME</code>.</p>
<p>If the <code>$VISUAL</code> environment variable is set, it will be used as the program to edit the function. If <code>$VISUAL</code> is unset but <code>$EDITOR</code> is set, that will be used. Otherwise, a built-in editor will be used.</p>
<p>If there is no function called <code>NAME</code> a new function will be created with the specified name</p>
<ul>
<li><code>-e command</code> or <code>--editor command</code> Open the function body inside the text editor given by the command (for example, "vi"). The command 'fish' will use the built-in editor.</li>
<li><code>-i</code> or <code>--interactive</code> Open function body in the built-in editor.</li>
</ul>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="funcsave"></a>
funcsave - save the definition of a function to the user's autoload directory</h1>
<h2><a class="anchor" id="funcsave-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">funcsave</span> <span class="argument">FUNCTION_NAME</span>
</pre><h2><a class="anchor" id="funcsave-description"></a>
Description</h2>
<p><code>funcsave</code> saves the current definition of a function to a file in the fish configuration directory. This function will be automatically loaded by current and future fish sessions. This can be useful if you have interactively created a new function and wish to save it for later use.</p>
<p>Note that because fish loads functions on-demand, saved functions will not function as <a href="index.html#event">event handlers</a> until they are run or sourced otherwise. To activate an event handler for every new shell, add the function to your <a href="index.html#initialization">shell initialization file</a> instead of using <code>funcsave</code>.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="function"></a>
function - create a function</h1>
<h2><a class="anchor" id="function-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">function</span> <span class="argument">NAME</span> <span class="argument">[OPTIONS]</span><span class="redirect">;</span> <span class="argument">BODY</span><span class="redirect">;</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="function-description"></a>
Description</h2>
<p><code>function</code> creates a new function <code>NAME</code> with the body <code>BODY</code>.</p>
<p>A function is a list of commands that will be executed when the name of the function is given as a command.</p>
<p>The following options are available:</p>
<ul>
<li><code>-a NAMES</code> or <code>--argument-names NAMES</code> assigns the value of successive command-line arguments to the names given in NAMES.</li>
<li><code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> is a description of what the function does, suitable as a completion description.</li>
<li><code>-w WRAPPED_COMMAND</code> or <code>--wraps=WRAPPED_COMMAND</code> causes the function to inherit completions from the given wrapped command. See the documentation for <a href="#complete"><code>complete</code></a> for more information.</li>
<li><code>-e</code> or <code>--on-event EVENT_NAME</code> tells fish to run this function when the specified named event is emitted. Fish internally generates named events e.g. when showing the prompt.</li>
<li><code>-v</code> or <code>--on-variable VARIABLE_NAME</code> tells fish to run this function when the variable VARIABLE_NAME changes value.</li>
<li><code>-j PGID</code> or <code>--on-job-exit PGID</code> tells fish to run this function when the job with group ID PGID exits. Instead of PGID, the string 'caller' can be specified. This is only legal when in a command substitution, and will result in the handler being triggered by the exit of the job which created this command substitution.</li>
<li><code>-p PID</code> or <code>--on-process-exit PID</code> tells fish to run this function when the fish child process with process ID PID exits.</li>
<li><code>-s</code> or <code>--on-signal SIGSPEC</code> tells fish to run this function when the signal SIGSPEC is delivered. SIGSPEC can be a signal number, or the signal name, such as SIGHUP (or just HUP).</li>
<li><code>-S</code> or <code>--no-scope-shadowing</code> allows the function to access the variables of calling functions. Normally, any variables inside the function that have the same name as variables from the calling function are "shadowed", and their contents is independent of the calling function.</li>
<li><code>-V</code> or <code>--inherit-variable NAME</code> snapshots the value of the variable <code>NAME</code> and defines a local variable with that same name and value when the function is executed.</li>
</ul>
<p>If the user enters any additional arguments after the function, they are inserted into the environment <a href="index.html#variables-arrays">variable array</a> <code>$argv</code>. If the <code>--argument-names</code> option is provided, the arguments are also assigned to names specified in that option.</p>
<p>By using one of the event handler switches, a function can be made to run automatically at specific events. The user may generate new events using the <a href="#emit">emit</a> builtin. Fish generates the following named events:</p>
<ul>
<li><code>fish_prompt</code>, which is emitted whenever a new fish prompt is about to be displayed.</li>
<li><code>fish_command_not_found</code>, which is emitted whenever a command lookup failed.</li>
<li><p class="startli"><code>fish_preexec</code>, which is emitted right before executing an interactive command. The commandline is passed as the first parameter.</p>
<p class="startli">Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.</p>
</li>
<li><p class="startli"><code>fish_postexec</code>, which is emitted right after executing an interactive command. The commandline is passed as the first parameter.</p>
<p class="startli">Note: This event will be emitted even if the command is invalid. The commandline parameter includes the entire commandline verbatim, and may potentially include newlines.</p>
</li>
</ul>
<h2><a class="anchor" id="function-example"></a>
Example</h2>
<pre class="fish">
<span class="command">function</span> <span class="argument">ll</span>
<span class="binary">ls</span> <span class="argument">-l</span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">end</span>
</pre><p>will run the <code>ls</code> command, using the <code>-l</code> option, while passing on any additional files and switches to <code>ls</code>.</p>
<pre class="fish">
<span class="command">function</span> <span class="argument"><span class="argument">mkdir</span></span> <span class="argument">-d</span> <span class="string">"Create a directory and set CWD"</span>
<span class="command">command</span> <span class="binary"><span class="argument">mkdir</span></span> <span class="variable"><span class="operator">$</span>argv</span>
<span class="command">if</span> <span class="command">test</span> <span class="variable"><span class="operator">$</span>status</span> = <span class="argument">0</span>
<span class="command">switch</span> <span class="variable"><span class="operator">$</span>argv</span>[<span class="operator">(</span><span class="command">count</span> <span class="variable"><span class="operator">$</span>argv</span><span class="operator">)</span>]
<span class="command">case</span> <span class="string">'-*'</span>
<span class="command">case</span> <span class="string">'*'</span>
<span class="command">cd</span> <span class="variable"><span class="operator">$</span>argv</span>[<span class="operator">(</span><span class="command">count</span> <span class="variable"><span class="operator">$</span>argv</span><span class="operator">)</span>]
<span class="command">return</span>
<span class="command">end</span>
<span class="command">end</span>
<span class="command">end</span>
</pre><p>This will run the <code>mkdir</code> command, and if it is successful, change the current working directory to the one just created.</p>
<pre class="fish">
<span class="command">function</span> <span class="argument">notify</span>
<span class="command">set</span> <span class="argument">-l</span> <span class="argument">job</span> <span class="operator">(</span><span class="command">jobs</span> <span class="argument">-l</span> <span class="argument">-g</span><span class="operator">)</span>
<span class="command">or</span> <span class="command">begin</span><span class="redirect">;</span> <span class="command">echo</span> <span class="string">"There are no jobs"</span> <span class="redirect">>&2</span><span class="redirect">;</span> <span class="command">return</span> <span class="argument">1</span><span class="redirect">;</span> <span class="command">end</span>
<span class="command">function</span> _notify_job_<span class="variable"><span class="operator">$</span>job</span> <span class="argument">--on-job-exit</span> <span class="variable"><span class="operator">$</span>job</span> <span class="argument">--inherit-variable</span> <span class="argument">job</span>
<span class="command">echo</span> <span class="argument">-n</span> <span class="argument"><span>\</span>a</span> <span class="comment">## beep</span>
<span class="command">functions</span> <span class="argument">-e</span> _notify_job_<span class="variable"><span class="operator">$</span>job</span>
<span class="command">end</span>
<span class="command">end</span>
</pre><p>This will beep when the most recent job completes.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="functions"></a>
functions - print or erase functions</h1>
<h2><a class="anchor" id="functions-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">functions</span> <span class="argument">[</span> <span class="argument">-a</span> <span class="redirect">|</span> <span class="argument">--all</span> <span class="argument">]</span> <span class="argument">[</span> <span class="argument">-n</span> <span class="redirect">|</span> <span class="argument">--names</span> <span class="argument">]</span>
<span class="command">functions</span> <span class="argument">-c</span> <span class="argument">OLDNAME</span> <span class="argument">NEWNAME</span>
<span class="command">functions</span> <span class="argument">-d</span> <span class="argument">DESCRIPTION</span> <span class="argument">FUNCTION</span>
<span class="command">functions</span> <span class="argument">[</span> <span class="argument">-e</span> <span class="redirect">|</span> <span class="argument">-q</span> <span class="argument">]</span> <span class="argument">FUNCTIONS...</span>
</pre><h2><a class="anchor" id="functions-description"></a>
Description</h2>
<p><code>functions</code> prints or erases functions.</p>
<p>The following options are available:</p>
<ul>
<li><code>-a</code> or <code>--all</code> lists all functions, even those whose name start with an underscore.</li>
<li><code>-c OLDNAME NEWNAME</code> or <code>--copy OLDNAME NEWNAME</code> creates a new function named NEWNAME, using the definition of the OLDNAME function.</li>
<li><code>-d DESCRIPTION</code> or <code>--description=DESCRIPTION</code> changes the description of this function.</li>
<li><code>-e</code> or <code>--erase</code> causes the specified functions to be erased.</li>
<li><code>-n</code> or <code>--names</code> lists the names of all defined functions.</li>
<li><code>-q</code> or <code>--query</code> tests if the specified functions exist.</li>
</ul>
<p>The default behavior of <code>functions</code>, when called with no arguments, is to print the names of all defined functions. Unless the <code>-a</code> option is given, no functions starting with underscores are not included in the output.</p>
<p>If any non-option parameters are given, the definition of the specified functions are printed.</p>
<p>Automatically loaded functions cannot be removed using <code>functions -e</code>. Either remove the definition file or change the $fish_function_path variable to remove autoloaded functions.</p>
<p>Copying a function using <code>-c</code> copies only the body of the function, and does not attach any event notifications from the original function.</p>
<p>Only one function's description can be changed in a single invocation of <code>functions -d</code>.</p>
<p>The exit status of <code>functions</code> is the number of functions specified in the argument list that do not exist, which can be used in concert with the <code>-q</code> option.</p>
<h2><a class="anchor" id="functions-example"></a>
Examples</h2>
<pre class="fish">
<span class="command">functions</span> <span class="argument">-n</span>
<span class="comment"># Displays a list of currently-defined functions</span>
<span class="command">functions</span> <span class="argument">-c</span> <span class="argument">foo</span> <span class="argument">bar</span>
<span class="comment"># Copies the 'foo' function to a new function called 'bar'</span>
<span class="command">functions</span> <span class="argument">-e</span> <span class="argument">bar</span>
<span class="comment"># Erases the function `bar`</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="help"></a>
help - display fish documentation</h1>
<h2><a class="anchor" id="help-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">help</span> <span class="argument">[SECTION]</span>
</pre><h2><a class="anchor" id="help-description"></a>
Description</h2>
<p><code>help</code> displays the fish help documentation.</p>
<p>If a <code>SECTION</code> is specified, the help for that command is shown.</p>
<p>If the BROWSER environment variable is set, it will be used to display the documentation. Otherwise, fish will search for a suitable browser.</p>
<p>Note that most builtin commands display their help in the terminal when given the <code>--help</code> option.</p>
<h2><a class="anchor" id="help-example"></a>
Example</h2>
<p><code>help fg</code> shows the documentation for the <code>fg</code> builtin.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="history"></a>
history - Show and manipulate command history</h1>
<h2><a class="anchor" id="history-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">history</span> <span class="argument">search</span> <span class="argument">[</span> <span class="argument">--show-time</span> <span class="argument">]</span> <span class="argument">[ <span class="argument">--</span><span class="argument">case</span>-sensitive ]</span> <span class="argument">[</span> <span class="argument">--exact</span> <span class="redirect">|</span> <span class="argument">--prefix</span> <span class="redirect">|</span> <span class="argument">--contains</span> <span class="argument">]</span> <span class="argument">[</span> <span class="argument">--max=n</span> <span class="argument">]</span> <span class="argument">[</span> <span class="argument">--null</span> <span class="argument">]</span> <span class="argument">[</span> <span class="string">"search string"</span><span class="argument">...</span> <span class="argument">]</span>
<span class="command">history</span> <span class="argument">delete</span> <span class="argument">[</span> <span class="argument">--show-time</span> <span class="argument">]</span> <span class="argument">[ <span class="argument">--</span><span class="argument">case</span>-sensitive ]</span> <span class="argument">[</span> <span class="argument">--exact</span> <span class="redirect">|</span> <span class="argument">--prefix</span> <span class="redirect">|</span> <span class="argument">--contains</span> <span class="argument">]</span> <span class="string">"search string"</span><span class="argument">...</span>
<span class="command">history</span> <span class="argument">merge</span>
<span class="command">history</span> <span class="argument">save</span>
<span class="command">history</span> <span class="argument">clear</span>
<span class="command">history</span> <span class="operator">(</span> <span class="argument">-h</span> <span class="redirect">|</span> <span class="argument">--help</span> <span class="operator">)</span>
</pre><h2><a class="anchor" id="history-description"></a>
Description</h2>
<p><code>history</code> is used to search, delete, and otherwise manipulate the history of interactive commands.</p>
<p>Note that for backwards compatibility each subcommand can also be specified as a long option. For example, rather than <code>history search</code> you can type <code>history --search</code>. Those long options are deprecated and will be removed in a future release.</p>
<p>The following operations (sub-commands) are available:</p>
<ul>
<li><code>search</code> returns history items matching the search string. If no search string is provided it returns all history items. This is the default operation if no other operation is specified. You only have to explicitly say <code>history search</code> if you wish to search for one of the subcommands. The <code>--contains</code> search option will be used if you don't specify a different search option. Entries are ordered newest to oldest. If stdout is attached to a tty the output will be piped through your pager by the history function. The history builtin simply writes the results to stdout.</li>
<li><code>delete</code> deletes history items. Without the <code>--prefix</code> or <code>--contains</code> options, the exact match of the specified text will be deleted. If you don't specify <code>--exact</code> a prompt will be displayed before any items are deleted asking you which entries are to be deleted. You can enter the word "all" to delete all matching entries. You can enter a single ID (the number in square brackets) to delete just that single entry. You can enter more than one ID separated by a space to delete multiple entries. Just press [enter] to not delete anything. Note that the interactive delete behavior is a feature of the history function. The history builtin only supports <code>--exact --case-sensitive</code> deletion.</li>
<li><code>merge</code> immediately incorporates history changes from other sessions. Ordinarily <code>fish</code> ignores history changes from sessions started after the current one. This command applies those changes immediately.</li>
<li><code>save</code> immediately writes all changes to the history file. The shell automatically saves the history file; this option is provided for internal use and should not normally need to be used by the user.</li>
<li><code>clear</code> clears the history file. A prompt is displayed before the history is erased asking you to confirm you really want to clear all history unless <code>builtin history</code> is used.</li>
</ul>
<p>The following options are available:</p>
<p>These flags can appear before or immediately after one of the sub-commands listed above.</p>
<ul>
<li><code>-C</code> or <code>--case-sensitive</code> does a case-sensitive search. The default is case-insensitive. Note that prior to fish 2.4.0 the default was case-sensitive.</li>
<li><code>-c</code> or <code>--contains</code> searches or deletes items in the history that contain the specified text string. This is the default for the <code>--search</code> flag. This is not currently supported by the <code>--delete</code> flag.</li>
<li><code>-e</code> or <code>--exact</code> searches or deletes items in the history that exactly match the specified text string. This is the default for the <code>--delete</code> flag. Note that the match is case-insensitive by default. If you really want an exact match, including letter case, you must use the <code>-C</code> or <code>--case-sensitive</code> flag.</li>
<li><code>-p</code> or <code>--prefix</code> searches or deletes items in the history that begin with the specified text string. This is not currently supported by the <code>--delete</code> flag.</li>
<li><code>-t</code> or <code>--show-time</code> prepends each history entry with the date and time the entry was recorded . By default it uses the strftime format <code># cn</code>. You can specify another format; e.g., `–show-time='Y-m-d H:M:S '<code>or</code>–show-time='aIp'<code>. The short option,</code>-t<code>doesn't accept a stftime format string; it only uses the default format. Any strftime format is allowed, including</code>s<code>to get the raw UNIX seconds since the epoch. Note that</code>–with-time` is also allowed but is deprecated and will be removed at a future date.</li>
<li><code>-z</code> or <code>--null</code> causes history entries written by the search operations to be terminated by a NUL character rather than a newline. This allows the output to be processed by <code>read -z</code> to correctly handle multiline history entries.</li>
<li><code>-<number></code> <code>-n <number></code> or <code>--max=<number></code> limits the matched history items to the first "n" matching entries. This is only valid for <code>history search</code>.</li>
<li><code>-h</code> or <code>--help</code> display help for this command.</li>
</ul>
<h2><a class="anchor" id="history-examples"></a>
Example</h2>
<pre class="fish">
<span class="command">history</span> <span class="argument">--clear</span>
<span class="comment"># Deletes all history items</span>
<span class="command">history</span> <span class="argument">--search</span> <span class="argument">--</span><span class="argument">contains</span> <span class="string">"foo"</span>
<span class="comment"># Outputs a list of all previous commands containing the string "foo".</span>
<span class="command">history</span> <span class="argument">--delete</span> <span class="argument">--prefix</span> <span class="string">"foo"</span>
<span class="comment"># Interactively deletes commands which start with "foo" from the history.</span>
<span class="comment"># You can select more than one entry by entering their IDs seperated by a space.</span>
\subsection <span class="argument">history</span>-notes <span class="argument">Notes</span>
<span class="argument">If</span> <span class="argument">you</span> <span class="argument">specify</span> <span class="argument">both</span> `--prefix` <span class="argument">and</span> `--<span class="argument">contains</span>` <span class="argument">the</span> <span class="argument">last</span> <span class="argument">flag</span> <span class="argument">seen</span> <span class="argument">is</span> <span class="argument">used.</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="if"></a>
if - conditionally execute a command</h1>
<h2><a class="anchor" id="if-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">if</span> <span class="argument">CONDITION</span><span class="redirect">;</span> <span class="argument">COMMANDS_TRUE...</span><span class="redirect">;</span>
<span class="argument">[<span class="command">else</span> <span class="command">if</span> <span class="argument">CONDITION2</span><span class="redirect">;</span> <span class="argument">COMMANDS_TRUE2...</span>;]</span>
<span class="argument">[<span class="command">else</span><span class="redirect">;</span> <span class="argument">COMMANDS_FALSE...</span>;]</span>
<span class="command">end</span>
</pre><h2><a class="anchor" id="if-description"></a>
Description</h2>
<p><code>if</code> will execute the command <code>CONDITION</code>. If the condition's exit status is 0, the commands <code>COMMANDS_TRUE</code> will execute. If the exit status is not 0 and <code>else</code> is given, <code>COMMANDS_FALSE</code> will be executed.</p>
<p>You can use <a href="#and"><code>and</code></a> or <a href="#or"><code>or</code></a> in the condition. See the second example below.</p>
<p>The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.</p>
<h2><a class="anchor" id="if-example"></a>
Example</h2>
<p>The following code will print <code>foo.txt exists</code> if the file foo.txt exists and is a regular file, otherwise it will print <code>bar.txt exists</code> if the file bar.txt exists and is a regular file, otherwise it will print <code>foo.txt and bar.txt do not exist</code>.</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="argument">-f</span> <span class="file">foo.txt</span>
<span class="command">echo</span> <span class="argument">foo.txt</span> <span class="argument">exists</span>
<span class="command">else</span> <span class="command">if</span> <span class="command">test</span> <span class="argument">-f</span> <span class="file">bar.txt</span>
<span class="command">echo</span> <span class="argument">bar.txt</span> <span class="argument">exists</span>
<span class="command">else</span>
<span class="command">echo</span> <span class="argument">foo.txt</span> <span class="argument">and</span> <span class="argument">bar.txt</span> <span class="argument">do</span> <span class="argument">not</span> <span class="argument">exist</span>
<span class="command">end</span>
</pre><p>The following code will print "foo.txt exists and is readable" if foo.txt is a regular file and readable </p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="argument">-f</span> <span class="file">foo.txt</span>
<span class="command">and</span> <span class="command">test</span> <span class="argument">-r</span> <span class="file">foo.txt</span>
<span class="command">echo</span> <span class="string">"foo.txt exists and is readable"</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="isatty"></a>
isatty - test if a file descriptor is a tty.</h1>
<h2><a class="anchor" id="isatty-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">isatty</span> <span class="argument">[FILE <span class="argument">DESCRIPTOR]</span></span>
</pre><h2><a class="anchor" id="isatty-description"></a>
Description</h2>
<p><code>isatty</code> tests if a file descriptor is a tty.</p>
<p><code>FILE DESCRIPTOR</code> may be either the number of a file descriptor, or one of the strings <code>stdin</code>, <code>stdout</code>, or <code>stderr</code>.</p>
<p>If the specified file descriptor is a tty, the exit status of the command is zero. Otherwise, the exit status is non-zero. No messages are printed to standard error.</p>
<h2><a class="anchor" id="isatty-examples"></a>
Examples</h2>
<p>From an interactive shell, the commands below exit with a return value of zero:</p>
<pre class="fish">
<span class="command">isatty</span>
<span class="command">isatty</span> <span class="argument">stdout</span>
<span class="command">isatty</span> <span class="argument">2</span>
<span class="command">echo</span> <span class="redirect">|</span> <span class="command">isatty</span> <span class="argument">1</span>
</pre><p>And these will exit non-zero:</p>
<pre class="fish">
<span class="command">echo</span> <span class="redirect">|</span> <span class="command">isatty</span>
<span class="command">isatty</span> <span class="argument">9</span>
<span class="command">isatty</span> <span class="argument">stdout</span> <span class="redirect">> file</span>
<span class="command">isatty</span> <span class="argument">2</span> <span class="redirect">2> file</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="jobs"></a>
jobs - print currently running jobs</h1>
<h2><a class="anchor" id="jobs-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">jobs</span> <span class="argument">[OPTIONS]</span> <span class="argument">[PID]</span>
</pre><h2><a class="anchor" id="jobs-description"></a>
Description</h2>
<p><code>jobs</code> prints a list of the currently running <a href="index.html#syntax-job-control">jobs</a> and their status.</p>
<p>jobs accepts the following switches:</p>
<ul>
<li><code>-c</code> or <code>--command</code> prints the command name for each process in jobs.</li>
<li><code>-g</code> or <code>--group</code> only prints the group ID of each job.</li>
<li><code>-l</code> or <code>--last</code> prints only the last job to be started.</li>
<li><code>-p</code> or <code>--pid</code> prints the process ID for each process in all jobs.</li>
</ul>
<p>On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100%.</p>
<h2><a class="anchor" id="jobs-example"></a>
Example</h2>
<p><code>jobs</code> outputs a summary of the current jobs.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="math"></a>
math - Perform mathematics calculations</h1>
<h2><a class="anchor" id="math-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">math</span> <span class="argument">[</span><span class="argument">-sN</span>] <span class="argument">EXPRESSION</span>
</pre><h2><a class="anchor" id="math-description"></a>
Description</h2>
<p><code>math</code> is used to perform mathematical calculations. It is a very thin wrapper for the bc program, which makes it possible to specify an expression from the command line without using non-standard extensions or a pipeline.</p>
<p>For a description of the syntax supported by math, see the manual for the bc program. Keep in mind that parameter expansion takes place on any expressions before they are evaluated. This can be very useful in order to perform calculations involving shell variables or the output of command substitutions, but it also means that parenthesis have to be escaped.</p>
<p>The following options are available:</p>
<ul>
<li><code>-sN</code> Sets the scale of the result. <code>N</code> must be an integer and defaults to zero. This simply sets bc's <code>scale</code> variable to the provided value. Note that you cannot put a space between <code>-s</code> and <code>N</code>.</li>
</ul>
<h2><a class="anchor" id="return-values"></a>
Return Values</h2>
<p>If invalid options or no expression is provided the return <code>status</code> is two. If the expression is invalid the return <code>status</code> is three. If bc returns a result of <code>0</code> (literally, not <code>0.0</code> or similar variants) the return <code>status</code> is one otherwise it's zero.</p>
<h2><a class="anchor" id="math-example"></a>
Examples</h2>
<p><code>math 1+1</code> outputs 2.</p>
<p><code>math $status-128</code> outputs the numerical exit status of the last command minus 128.</p>
<p><code>math 10 / 6</code> outputs <code>1</code>.</p>
<p><code>math -s0 10.0 / 6.0</code> outputs <code>1</code>.</p>
<p><code>math -s3 10 / 6</code> outputs <code>1.666</code>.</p>
<h2><a class="anchor" id="math-cautions"></a>
Cautions</h2>
<p>Note that the modulo operator (<code>x % y</code>) is not well defined for floating point arithmetic. The <code>bc</code> command produces a nonsensical result rather than emit an error and fail in that case. It doesn't matter if the arguments are integers; e.g., <code>10 % 4</code>. You'll still get an incorrect result. Do not use the <code>-sN</code> flag with N greater than zero if you want sensible answers when using the modulo operator.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="nextd"></a>
nextd - move forward through directory history</h1>
<h2><a class="anchor" id="nextd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">nextd</span> <span class="argument">[</span> <span class="argument">-l</span> <span class="redirect">|</span> <span class="argument">--list</span> <span class="argument">]</span> <span class="argument">[POS]</span>
</pre><h2><a class="anchor" id="nextd-description"></a>
Description</h2>
<p><code>nextd</code> moves forwards <code>POS</code> positions in the history of visited directories; if the end of the history has been hit, a warning is printed.</p>
<p>If the <code>-l</code> or <code>--list</code> flag is specified, the current directory history is also displayed.</p>
<p>Note that the <code>cd</code> command limits directory history to the 25 most recently visited directories. The history is stored in the <code>$dirprev</code> and <code>$dirnext</code> variables which this command manipulates.</p>
<h2><a class="anchor" id="nextd-example"></a>
Example</h2>
<pre class="fish">
<span class="command">cd</span> <span class="path">/usr/src</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="command">cd</span> <span class="path">/usr/src/fish-shell</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
<span class="command">prevd</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="command">nextd</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="not"></a>
not - negate the exit status of a job</h1>
<h2><a class="anchor" id="not-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">not</span> <span class="argument">COMMAND</span> <span class="argument">[OPTIONS...]</span>
</pre><h2><a class="anchor" id="not-description"></a>
Description</h2>
<p><code>not</code> negates the exit status of another command. If the exit status is zero, <code>not</code> returns 1. Otherwise, <code>not</code> returns 0.</p>
<h2><a class="anchor" id="not-example"></a>
Example</h2>
<p>The following code reports an error and exits if no file named spoon can be found.</p>
<pre class="fish">
<span class="command">if</span> <span class="command">not</span> <span class="command">test</span> <span class="argument">-f</span> <span class="argument">spoon</span>
<span class="command">echo</span> <span class="argument">There</span> <span class="argument">is</span> <span class="argument">no</span> <span class="argument">spoon</span>
<span class="command">exit</span> <span class="argument">1</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="open"></a>
open - open file in its default application</h1>
<h2><a class="anchor" id="open-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">open</span> <span class="argument">FILES...</span>
</pre><h2><a class="anchor" id="open-description"></a>
Description</h2>
<p><code>open</code> opens a file in its default application, using the appropriate tool for the operating system. On GNU/Linux, this requires the common but optional <code>xdg-open</code> utility, from the <code>xdg-utils</code> package.</p>
<h2><a class="anchor" id="open-example"></a>
Example</h2>
<p><code>open *.txt</code> opens all the text files in the current directory using your system's default text editor.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="or"></a>
or - conditionally execute a command</h1>
<h2><a class="anchor" id="or-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="argument">COMMAND1</span><span class="redirect">;</span> <span class="command">or</span> <span class="argument">COMMAND2</span>
</pre><h2><a class="anchor" id="or-description"></a>
Description</h2>
<p><code>or</code> is used to execute a command if the current exit status (as set by the previous command) is not 0.</p>
<p><code>or</code> statements may be used as part of the condition in an <a href="#if"><code>and</code></a> or <a href="#while"><code>while</code></a> block. See the documentation for <a href="#if"><code>if</code></a> and <a href="#while"><code>while</code></a> for examples.</p>
<p><code>or</code> does not change the current exit status. The exit status of the last foreground command to exit can always be accessed using the <a href="index.html#variables-status">$status</a> variable.</p>
<h2><a class="anchor" id="or-example"></a>
Example</h2>
<p>The following code runs the <code>make</code> command to build a program. If the build succeeds, the program is installed. If either step fails, <code>make clean</code> is run, which removes the files created by the build process.</p>
<pre class="fish">
<span class="binary">make</span><span class="redirect">;</span> <span class="command">and</span> <span class="binary">make</span> <span class="argument">install</span><span class="redirect">;</span> <span class="command">or</span> <span class="binary">make</span> <span class="argument">clean</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="popd"></a>
popd - move through directory stack</h1>
<h2><a class="anchor" id="popd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">popd</span>
</pre><h2><a class="anchor" id="popd-description"></a>
Description</h2>
<p><code>popd</code> removes the top directory from the directory stack and changes the working directory to the new top directory. Use <a href="#pushd"><code>pushd</code></a> to add directories to the stack.</p>
<h2><a class="anchor" id="popd-example"></a>
Example</h2>
<pre class="fish">
<span class="command">pushd</span> <span class="path">/usr/src</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="comment"># Directory stack contains /usr/src</span>
<span class="command">pushd</span> <span class="path">/usr/src/fish-shell</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
<span class="comment"># Directory stack contains /usr/src /usr/src/fish-shell</span>
<span class="command">popd</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="comment"># Directory stack contains /usr/src</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="prevd"></a>
prevd - move backward through directory history</h1>
<h2><a class="anchor" id="prevd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">prevd</span> <span class="argument">[</span> <span class="argument">-l</span> <span class="redirect">|</span> <span class="argument">--list</span> <span class="argument">]</span> <span class="argument">[POS]</span>
</pre><h2><a class="anchor" id="prevd-description"></a>
Description</h2>
<p><code>prevd</code> moves backwards <code>POS</code> positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.</p>
<p>If the <code>-l</code> or <code>--list</code> flag is specified, the current history is also displayed.</p>
<p>Note that the <code>cd</code> command limits directory history to the 25 most recently visited directories. The history is stored in the <code>$dirprev</code> and <code>$dirnext</code> variables which this command manipulates.</p>
<h2><a class="anchor" id="prevd-example"></a>
Example</h2>
<pre class="fish">
<span class="command">cd</span> <span class="path">/usr/src</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="command">cd</span> <span class="path">/usr/src/fish-shell</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
<span class="command">prevd</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="command">nextd</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="printf"></a>
printf - display text according to a format string</h1>
<h2><a class="anchor" id="printf-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">printf</span> <span class="argument">format</span> <span class="argument">[argument...]</span>
</pre><h2><a class="anchor" id="printf-description"></a>
Description</h2>
<p>printf formats the string FORMAT with ARGUMENT, and displays the result.</p>
<p>The string FORMAT should contain format specifiers, each of which are replaced with successive arguments according to the specifier. Specifiers are detailed below, and are taken from the C library function <code>printf(3)</code>.</p>
<p>Unlike <code>echo</code>, <code>printf</code> does not append a new line unless it is specified as part of the string.</p>
<p>Valid format specifiers are:</p>
<ul>
<li><code>%d</code>: Argument will be used as decimal integer (signed or unsigned)</li>
<li><code>%i</code>: Argument will be used as a signed integer</li>
<li><code>%o</code>: An octal unsigned integer</li>
<li><code>%u</code>: An unsigned decimal integer</li>
<li><code>%x</code> or <code>%X</code>: An unsigned hexadecimal integer</li>
<li><code>%f</code>, <code>%g</code> or <code>%G</code>: A floating-point number</li>
<li><code>%e</code> or <code>%E</code>: A floating-point number in scientific (XXXeYY) notation</li>
<li><code>%s</code>: A string</li>
<li><code>%b</code>: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.</li>
</ul>
<p><code>%%</code> signifies a literal "%".</p>
<p>Note that conversion may fail, e.g. "102.234" will not losslessly convert to an integer, causing printf to print an error.</p>
<p>printf also knows a number of backslash escapes:</p><ul>
<li><code>\"</code> double quote</li>
<li><code>\\</code> backslash</li>
<li><code>\a</code> alert (bell)</li>
<li><code>\b</code> backspace</li>
<li><code>\c</code> produce no further output</li>
<li><code>\e</code> escape</li>
<li><code>\f</code> form feed</li>
<li><code>\n</code> new line</li>
<li><code>\r</code> carriage return</li>
<li><code>\t</code> horizontal tab</li>
<li><code>\v</code> vertical tab</li>
<li><code>\ooo</code> octal number (ooo is 1 to 3 digits)</li>
<li><code>\xhh</code> hexadecimal number (hhh is 1 to 2 digits)</li>
<li><code>\uhhhh</code> 16-bit Unicode character (hhhh is 4 digits)</li>
<li><code>\Uhhhhhhhh</code> 32-bit Unicode character (hhhhhhhh is 8 digits)</li>
</ul>
<p>The <code>format</code> argument is re-used as many times as necessary to convert all of the given arguments. If a format specifier is not appropriate for the given argument, an error is printed. For example, `printf 'd' "102.234"` produces an error, as "102.234" cannot be formatted as an integer.</p>
<p>This file has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try <code>command printf</code>.</p>
<h2><a class="anchor" id="printf-example"></a>
Example</h2>
<pre class="fish">
<span class="command">printf</span> <span class="string">'<span>%</span>s<span>\</span>t<span>%</span>s<span>\</span>n'</span> <span class="argument">flounder</span> <span class="argument">fish</span>
</pre><p>Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.</p>
<pre class="fish">
<span class="command">printf</span> <span class="string">'<span>%</span>s:<span>%</span>d'</span> <span class="string">"Number of bananas in my pocket"</span> <span class="argument">42</span>
</pre><p>Will print "Number of bananas in my pocket: 42", <em>without</em> a newline.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="prompt_pwd"></a>
prompt_pwd - Print pwd suitable for prompt</h1>
<h2><a class="anchor" id="prompt_pwd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">prompt_pwd</span>
</pre><h2><a class="anchor" id="prompt_pwd-description"></a>
Description</h2>
<p>prompt_pwd is a function to print the current working directory in a way suitable for prompts. It will replace the home directory with "~" and shorten every path component but the last to a default of one character.</p>
<p>To change the number of characters per path component, set $fish_prompt_pwd_dir_length to the number of characters. Setting it to 0 or an invalid value will disable shortening entirely.</p>
<h2><a class="anchor" id="prompt_pwd-example"></a>
Examples</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">cd</span> <span class="path">~/</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>PWD</span>
<span class="output">/home/alfa</span>
<span class="prompt">></span> <span class="command">prompt_pwd</span>
<span class="output">~</span>
<span class="prompt">></span> <span class="command">cd</span> <span class="path">/tmp/banana/sausage/with/mustard</span>
<span class="prompt">></span> <span class="command">prompt_pwd</span>
<span class="output">/t/b/s/w/mustard</span>
<span class="prompt">></span> <span class="command">set</span> <span class="argument">-g</span> <span class="argument">fish_prompt_pwd_dir_length</span> <span class="argument">3</span>
<span class="prompt">></span> <span class="command">prompt_pwd</span>
<span class="output">/tmp/ban/sau/wit/mustard</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="psub"></a>
psub - perform process substitution</h1>
<h2><a class="anchor" id="psub-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="argument">COMMAND1</span> <span class="operator">(</span> <span class="argument">COMMAND2</span> <span class="redirect">|</span> <span class="command">psub</span> <span class="argument">[</span><span class="argument">-f</span>] <span class="argument">[</span><span class="argument">-s</span> <span class="argument">SUFFIX]</span><span class="operator">)</span>
</pre><h2><a class="anchor" id="psub-description"></a>
Description</h2>
<p>Posix shells feature a syntax that is a mix between command substitution and piping, called process substitution. It is used to send the output of a command into the calling command, much like command substitution, but with the difference that the output is not sent through commandline arguments but through a named pipe, with the filename of the named pipe sent as an argument to the calling program. <code>psub</code> combined with a regular command substitution provides the same functionality.</p>
<p>If the <code>-f</code> or <code>--file</code> switch is given to <code>psub</code>, <code>psub</code> will use a regular file instead of a named pipe to communicate with the calling process. This will cause <code>psub</code> to be significantly slower when large amounts of data are involved, but has the advantage that the reading process can seek in the stream.</p>
<p>If the <code>-s</code> or <code>---suffix</code> switch is given, <code>psub</code> will append SUFFIX to the filename.</p>
<h2><a class="anchor" id="psub-example"></a>
Example</h2>
<pre class="fish">
<span class="binary">diff</span> <span class="operator">(</span><span class="binary">sort</span> <span class="file">a.txt</span> <span class="redirect">|</span> <span class="command">psub</span><span class="operator">)</span> <span class="operator">(</span><span class="binary">sort</span> <span class="file">b.txt</span> <span class="redirect">|</span> <span class="command">psub</span><span class="operator">)</span>
<span class="comment"># shows the difference between the sorted versions of files `a.txt` and `b.txt`.</span>
<span class="command">source</span>-<span class="argument">highlight</span> <span class="argument">-f</span> <span class="argument">esc</span> <span class="operator">(</span>cpp <span class="file">main.c</span> <span class="redirect">|</span> <span class="command">psub</span> <span class="argument">-s</span> <span class="argument">.c</span><span class="operator">)</span>
<span class="comment"># highlights `main.c` after preprocessing as a C source.</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="pushd"></a>
pushd - push directory to directory stack</h1>
<h2><a class="anchor" id="pushd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">pushd</span> <span class="argument">[DIRECTORY]</span>
</pre><h2><a class="anchor" id="pushd-description"></a>
Description</h2>
<p>The <code>pushd</code> function adds <code>DIRECTORY</code> to the top of the directory stack and makes it the current working directory. <a href="#popd"><code>popd</code></a> will pop it off and return to the original directory.</p>
<p>Without arguments, it exchanges the top two directories in the stack.</p>
<p><code>pushd +NUMBER</code> rotates the stack counter-clockwise i.e. from bottom to top</p>
<p><code>pushd -NUMBER</code> rotates clockwise i.e. top to bottom.</p>
<p>See also <code>dirs</code> and <code>dirs -c</code>.</p>
<h2><a class="anchor" id="pushd-example"></a>
Example</h2>
<pre class="fish">
<span class="command">pushd</span> <span class="path">/usr/src</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="comment"># Directory stack contains /usr/src</span>
<span class="command">pushd</span> <span class="path">/usr/src/fish-shell</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
<span class="comment"># Directory stack contains /usr/src /usr/src/fish-shell</span>
<span class="command">pushd</span> <span class="path">/tmp/</span>
<span class="comment"># Working directory is now /tmp</span>
<span class="comment"># Directory stack contains /tmp /usr/src /usr/src/fish-shell</span>
<span class="command">pushd</span> <span class="argument">+1</span>
<span class="comment"># Working directory is now /usr/src</span>
<span class="comment"># Directory stack contains /usr/src /usr/src/fish-shell /tmp</span>
<span class="command">popd</span>
<span class="comment"># Working directory is now /usr/src/fish-shell</span>
<span class="comment"># Directory stack contains /usr/src/fish-shell /tmp</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="pwd"></a>
pwd - output the current working directory</h1>
<h2><a class="anchor" id="pwd-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">pwd</span>
</pre><h2><a class="anchor" id="pwd-description"></a>
Description</h2>
<p><code>pwd</code> outputs (prints) the current working directory.</p>
<p>Note that <code>fish</code> always resolves symbolic links in the current directory path.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="random"></a>
random - generate random number</h1>
<h2><a class="anchor" id="random-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">random</span> <span class="argument">[SEED]</span>
</pre><h2><a class="anchor" id="random-description"></a>
Description</h2>
<p><code>random</code> outputs a psuedo-random number from 0 to 32767, inclusive. Even ignoring the very narrow range of values you should not assume this produces truly random values within that range. Do not use the value for any cryptographic purposes, and take care to handle collisions: the same random number appearing more than once in a given fish instance.</p>
<p>If a <code>SEED</code> value is provided, it is used to seed the random number generator, and no output will be produced. This can be useful for debugging purposes, where it can be desirable to get the same random number sequence multiple times. If the random number generator is called without first seeding it, the current time will be used as the seed.</p>
<h2><a class="anchor" id="random-example"></a>
Example</h2>
<p>The following code will count down from a random number to 1:</p>
<pre class="fish">
<span class="command">for</span> <span class="argument">i</span> <span class="command">in</span> <span class="operator">(</span><span class="binary">seq</span> <span class="operator">(</span><span class="command">random</span><span class="operator">)</span> <span class="argument">-1</span> <span class="argument">1</span><span class="operator">)</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>i</span>
<span class="command">sleep</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="read"></a>
read - read line of input into variables</h1>
<h2><a class="anchor" id="read-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">read</span> <span class="argument">[OPTIONS]</span> <span class="argument">[VARIABLES...]</span>
</pre><h2><a class="anchor" id="read-description"></a>
Description</h2>
<p><code>read</code> reads one line from standard input and stores the result in one or more shell variables.</p>
<p>The following options are available:</p>
<ul>
<li><code>-c CMD</code> or <code>--command=CMD</code> sets the initial string in the interactive mode command buffer to <code>CMD</code>.</li>
<li><code>-g</code> or <code>--global</code> makes the variables global.</li>
<li><code>-l</code> or <code>--local</code> makes the variables local.</li>
<li><code>-m NAME</code> or <code>--mode-name=NAME</code> specifies that the name NAME should be used to save/load the history file. If NAME is fish, the regular fish history will be available.</li>
<li><code>-n NCHARS</code> or <code>--nchars=NCHARS</code> causes <code>read</code> to return after reading NCHARS characters rather than waiting for a complete line of input.</li>
<li><code>-p PROMPT_CMD</code> or <code>--prompt=PROMPT_CMD</code> uses the output of the shell command <code>PROMPT_CMD</code> as the prompt for the interactive mode. The default prompt command is <code>set_color green; echo read; set_color normal; echo "> "</code>.</li>
<li><code>-R RIGHT_PROMPT_CMD</code> or <code>--right-prompt=RIGHT_PROMPT_CMD</code> uses the output of the shell command <code>RIGHT_PROMPT_CMD</code> as the right prompt for the interactive mode. There is no default right prompt command.</li>
<li><code>-s</code> or <code>--shell</code> enables syntax highlighting, tab completions and command termination suitable for entering shellscript code in the interactive mode.</li>
<li><code>-u</code> or <code>--unexport</code> prevents the variables from being exported to child processes (default behaviour).</li>
<li><code>-U</code> or <code>--universal</code> causes the specified shell variable to be made universal.</li>
<li><code>-x</code> or <code>--export</code> exports the variables to child processes.</li>
<li><code>-a</code> or <code>--array</code> stores the result as an array.</li>
<li><code>-z</code> or <code>--null</code> reads up to NUL instead of newline. Disables interactive mode.</li>
</ul>
<p><code>read</code> reads a single line of input from stdin, breaks it into tokens based on the <code>IFS</code> shell variable, and then assigns one token to each variable specified in <code>VARIABLES</code>. If there are more tokens than variables, the complete remainder is assigned to the last variable. As a special case, if <code>IFS</code> is set to the empty string, each character of the input is considered a separate token.</p>
<p>If <code>-a</code> or <code>--array</code> is provided, only one variable name is allowed and the tokens are stored as an array in this variable.</p>
<p>See the documentation for <code>set</code> for more details on the scoping rules for variables.</p>
<h2><a class="anchor" id="read-example"></a>
Example</h2>
<p>The following code stores the value 'hello' in the shell variable <code>$foo</code>.</p>
<pre class="fish">
<span class="command">echo</span> <span class="argument">hello</span><span class="redirect">|</span><span class="command">read</span> <span class="argument">foo</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="realpath"></a>
realpath - Convert a path to an absolute path without symlinks</h1>
<h2><a class="anchor" id="realpath-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">realpath</span> <span class="argument">path</span>
</pre><h2><a class="anchor" id="realpath-description"></a>
Description</h2>
<p>This is implemented as a function and a builtin. The function will attempt to use an external realpath command if one can be found. Otherwise it falls back to the builtin. The builtin does not support any options. It's meant to be used only by scripts which need to be portable. The builtin implementation behaves like GNU realpath when invoked without any options (which is the most common use case). In general scripts should not invoke the builtin directly. They should just use <code>realpath</code>.</p>
<p>If the path is invalid no translated path will be written to stdout and an error will be reported.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="return"></a>
return - stop the current inner function</h1>
<h2><a class="anchor" id="return-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">function</span> <span class="argument">NAME</span><span class="redirect">;</span> <span class="argument">[COMMANDS...;]</span> <span class="command">return</span> <span class="argument">[STATUS]</span><span class="redirect">;</span> <span class="argument">[COMMANDS...;]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="return-description"></a>
Description</h2>
<p><code>return</code> halts a currently running function. The exit status is set to <code>STATUS</code> if it is given.</p>
<p>It is usually added inside of a conditional block such as an <a href="#if">if</a> statement or a <a href="#switch">switch</a> statement to conditionally stop the executing function and return to the caller, but it can also be used to specify the exit status of a function.</p>
<h2><a class="anchor" id="return-example"></a>
Example</h2>
<p>The following code is an implementation of the false command as a fish function</p>
<pre class="fish">
<span class="command">function</span> <span class="argument">false</span>
<span class="command">return</span> <span class="argument">1</span>
<span class="command">end</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="set"></a>
set - display and change shell variables.</h1>
<h2><a class="anchor" id="set-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">set</span> <span class="argument">[SCOPE_OPTIONS]</span>
<span class="command">set</span> <span class="argument">[OPTIONS]</span> <span class="argument">VARIABLE_NAME</span> <span class="argument">VALUES...</span>
<span class="command">set</span> <span class="argument">[OPTIONS]</span> <span class="argument">VARIABLE_NAME</span><span class="argument">[INDICES]</span>... <span class="argument">VALUES...</span>
<span class="command">set</span> <span class="operator">(</span> <span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--query</span> <span class="operator">)</span> <span class="argument">[SCOPE_OPTIONS]</span> <span class="argument">VARIABLE_NAMES...</span>
<span class="command">set</span> <span class="operator">(</span> <span class="argument">-e</span> <span class="redirect">|</span> <span class="argument">--erase</span> <span class="operator">)</span> <span class="argument">[SCOPE_OPTIONS]</span> <span class="argument">VARIABLE_NAME</span>
<span class="command">set</span> <span class="operator">(</span> <span class="argument">-e</span> <span class="redirect">|</span> <span class="argument">--erase</span> <span class="operator">)</span> <span class="argument">[SCOPE_OPTIONS]</span> <span class="argument">VARIABLE_NAME</span><span class="argument">[INDICES]</span><span class="argument">...</span>
</pre><h2><a class="anchor" id="set-description"></a>
Description</h2>
<p><code>set</code> manipulates <a href="index.html#variables">shell variables</a>.</p>
<p>If set is called with no arguments, the names and values of all shell variables are printed. If some of the scope or export flags have been given, only the variables matching the specified scope are printed.</p>
<p>With both variable names and values provided, <code>set</code> assigns the variable <code>VARIABLE_NAME</code> the values <code>VALUES...</code>.</p>
<p>The following options control variable scope:</p>
<ul>
<li><code>-l</code> or <code>--local</code> forces the specified shell variable to be given a scope that is local to the current block, even if a variable with the given name exists and is non-local</li>
<li><code>-g</code> or <code>--global</code> causes the specified shell variable to be given a global scope. Non-global variables disappear when the block they belong to ends</li>
<li><code>-U</code> or <code>--universal</code> causes the specified shell variable to be given a universal scope. If this option is supplied, the variable will be shared between all the current users fish instances on the current computer, and will be preserved across restarts of the shell.</li>
<li><code>-x</code> or <code>--export</code> causes the specified shell variable to be exported to child processes (making it an "environment variable")</li>
<li><code>-u</code> or <code>--unexport</code> causes the specified shell variable to NOT be exported to child processes</li>
</ul>
<p>The following options are available:</p>
<ul>
<li><code>-e</code> or <code>--erase</code> causes the specified shell variable to be erased</li>
<li><code>-q</code> or <code>--query</code> test if the specified variable names are defined. Does not output anything, but the builtins exit status is the number of variables specified that were not defined.</li>
<li><code>-n</code> or <code>--names</code> List only the names of all defined variables, not their value</li>
<li><code>-L</code> or <code>--long</code> do not abbreviate long values when printing set variables</li>
</ul>
<p>If a variable is set to more than one value, the variable will be an array with the specified elements. If a variable is set to zero elements, it will become an array with zero elements.</p>
<p>If the variable name is one or more array elements, such as <code>PATH[1 3 7]</code>, only those array elements specified will be changed. When array indices are specified to <code>set</code>, multiple arguments may be used to specify additional indexes, e.g. <code>set PATH[1] PATH[4] /bin /sbin</code>. If you specify a negative index when expanding or assigning to an array variable, the index will be calculated from the end of the array. For example, the index -1 means the last index of an array.</p>
<p>The scoping rules when creating or updating a variable are:</p>
<ol type="1">
<li>If a variable is explicitly set to either universal, global or local, that setting will be honored. If a variable of the same name exists in a different scope, that variable will not be changed.</li>
<li>If a variable is not explicitly set to be either universal, global or local, but has been previously defined, the previous variable scope is used.</li>
<li>If a variable is not explicitly set to be either universal, global or local and has never before been defined, the variable will be local to the currently executing function. Note that this is different from using the <code>-l</code> or <code>--local</code> flag. If one of those flags is used, the variable will be local to the most inner currently executing block, while without these the variable will be local to the function. If no function is executing, the variable will be global.</li>
</ol>
<p>The exporting rules when creating or updating a variable are identical to the scoping rules for variables:</p>
<ol type="1">
<li>If a variable is explicitly set to either be exported or not exported, that setting will be honored.</li>
<li>If a variable is not explicitly set to be exported or not exported, but has been previously defined, the previous exporting rule for the variable is kept.</li>
<li>If a variable is not explicitly set to be either exported or unexported and has never before been defined, the variable will not be exported.</li>
</ol>
<p>In query mode, the scope to be examined can be specified.</p>
<p>In erase mode, if variable indices are specified, only the specified slices of the array variable will be erased.</p>
<p><code>set</code> requires all options to come before any other arguments. For example, <code>set flags -l</code> will have the effect of setting the value of the variable <code>flags</code> to '-l', not making the variable local.</p>
<p>In assignment mode, <code>set</code> exits with a non-zero exit status if variable assignments could not be successfully performed. If the variable assignments were performed, the exit status is unchanged. This allows simultaneous capture of the output and exit status of a subcommand, e.g. <code>if set output (command)</code>. In query mode, the exit status is the number of variables that were not found. In erase mode, <code>set</code> exits with a zero exit status in case of success, with a non-zero exit status if the commandline was invalid, if the variable was write-protected or if the variable did not exist.</p>
<h2><a class="anchor" id="set-example"></a>
Example</h2>
<pre class="fish">
<span class="command">set</span> <span class="argument">-xg</span>
<span class="comment"># Prints all global, exported variables.</span>
<span class="command">set</span> <span class="argument">foo</span> <span class="argument">hi</span>
<span class="comment"># Sets the value of the variable $foo to be 'hi'.</span>
<span class="command">set</span> <span class="argument">-e</span> <span class="argument">smurf</span>
<span class="comment"># Removes the variable $smurf</span>
<span class="command">set</span> <span class="argument">PATH</span><span class="argument">[4]</span> <span class="path">~/bin</span>
<span class="comment"># Changes the fourth element of the $PATH array to ~/bin</span>
<span class="command">if</span> <span class="command">set</span> <span class="argument">python_path</span> <span class="operator">(</span><span class="binary">which</span> <span class="argument">python</span><span class="operator">)</span>
<span class="command">echo</span> <span class="string">"Python is at $python_path"</span>
<span class="command">end</span>
<span class="comment"># Outputs the path to Python if `which` returns true.</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="set_color"></a>
set_color - set the terminal color</h1>
<h2><a class="anchor" id="set_color-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">set_color</span> <span class="argument">[OPTIONS]</span> <span class="argument">VALUE</span>
</pre><h2><a class="anchor" id="set_color-description"></a>
Description</h2>
<p><code>set_color</code> is used to control the color and styling of text in the terminal. <code>VALUE</code> corresponds to a reserved color name such as <em>red</em> or a RGB color value given as 3 or 6 hexadecimal digits. The <em>br</em>-, as in 'bright', forms are full-brightness variants of the 8 standard-brightness colors on many terminals. <em>brblack</em> has higher brightness than <em>black</em> - towards gray. A special keyword <em>normal</em> resets text formatting to terminal defaults.</p>
<p>Valid colors include:</p>
<ul>
<li><em>black</em>, <em>red</em>, <em>green</em>, <em>yellow</em>, <em>blue</em>, <em>magenta</em>, <em>cyan</em>, <em>white</em></li>
<li><em>brblack</em>, <em>brred</em>, <em>brgreen</em>, <em>bryellow</em>, <em>brblue</em>, <em>brmagenta</em>, <em>brcyan</em>, <em>brwhite</em></li>
</ul>
<p>An RGB value with three or six hex digits, such as A0FF33 or f2f can be used. <code>fish</code> will choose the closest supported color. A three digit value is equivalent to specifying each digit twice; e.g., <code>set_color 2BC</code> is the same as <code>set_color 22BBCC</code>. Hexadecimal RGB values can be in lower or uppercase. Depending on the capabilities of your terminal (and the level of support <code>set_color</code> has for it) the actual color may be approximated by a nearby matching reserved color name or <code>set_color</code> may not have an effect on color. A second color may be given as a desired fallback color. e.g. <code>set_color 124212</code> <em>brblue</em> will instruct set_color to use <em>brblue</em> if a terminal is not capable of the exact shade of grey desired. This is very useful when an 8 or 16 color terminal might otherwise not use a color.</p>
<p>The following options are available:</p>
<ul>
<li><code>-b</code>, <code>--background</code> <em>COLOR</em> sets the background color.</li>
<li><code>-c</code>, <code>--print-colors</code> prints a list of the 16 named colors.</li>
<li><code>-o</code>, <code>--bold</code> sets bold mode.</li>
<li><code>-u</code>, <code>--underline</code> sets underlined mode.</li>
</ul>
<p>Using the <em>normal</em> keyword will reset foreground, background, and all formatting back to default.</p>
<h2><a class="anchor" id="set_color-notes"></a>
Notes</h2>
<ol type="1">
<li>Using the <em>normal</em> keyword will reset both background and foreground colors to whatever is the default for the terminal.</li>
<li>Setting the background color only affects subsequently written characters. Fish provides no way to set the background color for the entire terminal window. Configuring the window background color (and other attributes such as its opacity) has to be done using whatever mechanisms the terminal provides.</li>
<li>Some terminals use the <code>--bold</code> escape sequence to switch to a brighter color set rather than increasing the weight of text.</li>
<li><code>set_color</code> works by printing sequences of characters to <em>stdout</em>. If used in command substitution or a pipe, these characters will also be captured. This may or may not be desirable. Checking the exit code of <code>isatty stdout</code> before using <code>set_color</code> can be useful to decide not to colorize output in a script.</li>
</ol>
<h2><a class="anchor" id="set_color-example"></a>
Examples</h2>
<pre class="fish">
<span class="command">set_color</span> <span class="argument">red</span><span class="redirect">;</span> <span class="command">echo</span> <span class="string">"Roses are red"</span>
<span class="command">set_color</span> <span class="argument">blue</span><span class="redirect">;</span> <span class="command">echo</span> <span class="string">"Violets are blue"</span>
<span class="command">set_color</span> <span class="argument">62A</span><span class="redirect">;</span> <span class="command">echo</span> <span class="string">"Eggplants are dark purple"</span>
<span class="command">set_color</span> <span class="argument">normal</span><span class="redirect">;</span> <span class="command">echo</span> <span class="string">"Normal is nice"</span> <span class="comment">## Resets the background too</span>
</pre><h2><a class="anchor" id="set_color-detection"></a>
Terminal Capability Detection</h2>
<p>Fish uses a heuristic to decide if a terminal supports the 256-color palette as opposed to the more limited 16 color palette of older terminals. Support can be forced on by setting <code>fish_term256</code> to <em>1</em>. If <code>$TERM</code> contains "256color" (e.g., <em>xterm-256color</em>), 256-color support is enabled. If <code>$TERM</code> contains <em>xterm</em>, 256 color support is enabled (except for MacOS: <code>$TERM_PROGRAM</code> and <code>$TERM_PROGRAM_VERSION</code> are used to detect Terminal.app from MacOS 10.6; support is disabled here it because it is known that it reports <code>xterm</code> and only supports 16 colors.</p>
<p>If terminfo reports 256 color support for a terminal, support will always be enabled. To debug color palette problems, <code>tput colors</code> may be useful to see the number of colors in terminfo for a terminal. Fish launched as <code>fish -d2</code> will include diagnostic messages that indicate the color support mode in use.</p>
<p>Many terminals support 24-bit (i.e., true-color) color escape sequences. This includes modern xterm, Gnome Terminal, Konsole, and iTerm2. Fish attempts to detect such terminals through various means in <code>config.fish</code> You can explicitly force that support via <code>set fish_term24bit 1</code>.</p>
<p>The <code>set_color</code> command uses the terminfo database to look up how to change terminal colors on whatever terminal is in use. Some systems have old and incomplete terminfo databases, and may lack color information for terminals that support it. Fish will assume that all terminals can use the <a href="https://en.wikipedia.org/wiki/ANSI_escape_code">ANSI X3.64</a> escape sequences if the terminfo definition indicates a color below 16 is not supported.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="source"></a>
source - evaluate contents of file.</h1>
<h2><a class="anchor" id="source-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">source</span> <span class="argument">FILENAME</span> <span class="argument">[ARGUMENTS...]</span>
</pre><h2><a class="anchor" id="source-description"></a>
Description</h2>
<p><code>source</code> evaluates the commands of the specified file in the current shell. This is different from starting a new process to perform the commands (i.e. <code>fish < FILENAME</code>) since the commands will be evaluated by the current shell, which means that changes in shell variables will affect the current shell. If additional arguments are specified after the file name, they will be inserted into the <code>$argv</code> variable. The <code>$argv</code> variable will not include the name of the sourced file.</p>
<p>If no file is specified, or if the file name '<code>-</code>' is used, stdin will be read.</p>
<p>The return status of <code>source</code> is the return status of the last job to execute. If something goes wrong while opening or reading the file, <code>source</code> exits with a non-zero status.</p>
<p><code>.</code> (a single period) is an alias for the <code>source</code> command. The use of <code>.</code> is deprecated in favour of <code>source</code>, and <code>.</code> will be removed in a future version of fish.</p>
<h2><a class="anchor" id="source-example"></a>
Example</h2>
<pre class="fish">
<span class="command">source</span> <span class="path">~/.config/fish/config.fish</span>
<span class="comment"># Causes fish to re-read its initialization file.</span>
</pre><h2><a class="anchor" id="Caveats"></a>
Caveats</h2>
<p>In fish versions prior to 2.3.0 the <code>$argv</code> variable would have a single element (the name of the sourced file) if no arguments are present. Otherwise it would contain arguments without the name of the sourced file. That behavior was very confusing and unlike other shells such as bash and zsh.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="status"></a>
status - query fish runtime information</h1>
<h2><a class="anchor" id="status-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">status</span> <span class="argument">[OPTION]</span>
</pre><h2><a class="anchor" id="status-description"></a>
Description</h2>
<p>With no arguments, <code>status</code> displays a summary of the current login and job control status of the shell.</p>
<p>The following options are available:</p>
<ul>
<li><code>-c</code> or <code>--is-command-substitution</code> returns 0 if fish is currently executing a command substitution.</li>
<li><code>-b</code> or <code>--is-block</code> returns 0 if fish is currently executing a block of code.</li>
<li><code>-i</code> or <code>--is-interactive</code> returns 0 if fish is interactive - that is, connected to a keyboard.</li>
<li><code>-l</code> or <code>--is-login</code> returns 0 if fish is a login shell - that is, if fish should perform login tasks such as setting up the PATH.</li>
<li><code>--is-full-job-control</code> returns 0 if full job control is enabled.</li>
<li><code>--is-interactive-job-control</code> returns 0 if interactive job control is enabled.</li>
<li><code>--is-no-job-control</code> returns 0 if no job control is enabled.</li>
<li><code>-f</code> or <code>--current-filename</code> prints the filename of the currently running script.</li>
<li><code>-n</code> or <code>--current-line-number</code> prints the line number of the currently running script.</li>
<li><code>-j CONTROLTYPE</code> or <code>--job-control=CONTROLTYPE</code> sets the job control type, which can be <code>none</code>, <code>full</code>, or <code>interactive</code>.</li>
<li><code>-t</code> or <code>--print-stack-trace</code> prints a stack trace of all function calls on the call stack.</li>
</ul>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="string"></a>
string - manipulate strings</h1>
<h2><a class="anchor" id="string-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">string</span> <span class="argument">length</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>] <span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">sub</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-s</span> <span class="redirect">|</span> <span class="argument">--start</span><span class="operator">)</span> <span class="argument">START]</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-l</span> <span class="redirect">|</span> <span class="argument">--length</span><span class="operator">)</span> <span class="argument">LENGTH]</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>]
<span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">split</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-m</span> <span class="redirect">|</span> <span class="argument">--max</span><span class="operator">)</span> <span class="argument">MAX]</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-r</span> <span class="redirect">|</span> <span class="argument">--right</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>] <span class="argument">SEP</span>
<span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">join</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>] <span class="argument">SEP</span> <span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">trim</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-l</span> <span class="redirect">|</span> <span class="argument">--left</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-r</span> <span class="redirect">|</span> <span class="argument">--right</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-c</span> <span class="redirect">|</span> <span class="argument">--chars</span> <span class="argument">CHARS</span><span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>] <span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">escape</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-n</span> <span class="redirect">|</span> <span class="argument">--no-quoted</span><span class="operator">)</span>] <span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">match</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-a</span> <span class="redirect">|</span> <span class="argument">--all</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-i</span> <span class="redirect">|</span> <span class="argument">--ignore-case</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-r</span> <span class="redirect">|</span> <span class="argument">--regex</span><span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span><span class="argument">-n</span> <span class="redirect">|</span> <span class="argument">--index</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-v</span> <span class="redirect">|</span> <span class="argument">--invert</span><span class="operator">)</span>] <span class="argument">PATTERN</span> <span class="argument">[STRING...]</span>
<span class="command">string</span> <span class="argument">replace</span> <span class="argument">[</span><span class="operator">(</span><span class="argument">-a</span> <span class="redirect">|</span> <span class="argument">--all</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-i</span> <span class="redirect">|</span> <span class="argument">--ignore-case</span><span class="operator">)</span>] <span class="argument">[</span><span class="operator">(</span><span class="argument">-r</span> <span class="redirect">|</span> <span class="argument">--regex</span><span class="operator">)</span>]
<span class="argument">[</span><span class="operator">(</span><span class="argument">-q</span> <span class="redirect">|</span> <span class="argument">--quiet</span><span class="operator">)</span>] <span class="argument">PATTERN</span> <span class="argument">REPLACEMENT</span> <span class="argument">[STRING...]</span>
</pre><h2><a class="anchor" id="string-description"></a>
Description</h2>
<p><code>string</code> performs operations on strings.</p>
<p>STRING arguments are taken from the command line unless standard input is connected to a pipe or a file, in which case they are read from standard input, one STRING per line. It is an error to supply STRING arguments on the command line and on standard input.</p>
<p>Arguments beginning with <code>-</code> are normally interpreted as switches; <code>--</code> causes the following arguments not to be treated as switches even if they begin with <code>-</code>. Switches and required arguments are recognized only on the command line.</p>
<p>Most subcommands accept a <code>-q</code> or <code>--quiet</code> switch, which suppresses the usual output but exits with the documented status.</p>
<p>In addition to the exit codes documented below, all the string subcommands exit with a value of 2 to indicate that an error occurred.</p>
<p>The following subcommands are available:</p>
<ul>
<li><code>length</code> reports the length of each string argument in characters. Exit status: 0 if at least one non-empty STRING was given, or 1 otherwise.</li>
<li><code>sub</code> prints a substring of each string argument. The start of the substring can be specified with <code>-s</code> or <code>--start</code> followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with <code>-l</code> or <code>--length</code>. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise.</li>
<li><code>split</code> splits each STRING on the separator SEP, which can be an empty string. If <code>-m</code> or <code>--max</code> is specified, at most MAX splits are done on each STRING. If <code>-r</code> or <code>--right</code> is given, splitting is performed right-to-left. This is useful in combination with <code>-m</code> or <code>--max</code>. Exit status: 0 if at least one split was performed, or 1 otherwise.</li>
<li><code>join</code> joins its STRING arguments into a single string separated by SEP, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise.</li>
<li><code>trim</code> removes leading and trailing whitespace from each STRING. If <code>-l</code> or <code>--left</code> is given, only leading whitespace is removed. If <code>-r</code> or <code>--right</code> is given, only trailing whitespace is trimmed. The <code>-c</code> or <code>--chars</code> switch causes the characters in CHARS to be removed instead of whitespace. Exit status: 0 if at least one character was trimmed, or 1 otherwise.</li>
<li><code>escape</code> escapes each STRING such that it can be passed back to <code>eval</code> to produce the original argument again. By default, all special characters are escaped, and quotes are used to simplify the output when possible. If <code>-n</code> or <code>--no-quoted</code> is given, the simplifying quoted format is not used. Exit status: 0 if at least one string was escaped, or 1 otherwise.</li>
<li><code>match</code> tests each STRING against PATTERN and prints matching substrings. Only the first match for each STRING is reported unless <code>-a</code> or <code>--all</code> is given, in which case all matches are reported. Matching can be made case-insensitive with <code>-i</code> or <code>--ignore-case</code>. If <code>-n</code> or <code>--index</code> is given, each match is reported as a 1-based start position and a length. By default, PATTERN is interpreted as a glob pattern matched against each entire STRING argument. A glob pattern is only considered a valid match if it matches the entire STRING. If <code>-r</code> or <code>--regex</code> is given, PATTERN is interpreted as a Perl-compatible regular expression, which does not have to match the entire STRING. For a regular expression containing capturing groups, multiple items will be reported for each match, one for the entire match and one for each capturing group. If –invert or -v is used the selected lines will be only those which do not match the given glob pattern or regular expression. Exit status: 0 if at least one match was found, or 1 otherwise.</li>
<li><code>replace</code> is similar to <code>match</code> but replaces non-overlapping matching substrings with a replacement string and prints the result. By default, PATTERN is treated as a literal substring to be matched. If <code>-r</code> or <code>--regex</code> is given, PATTERN is interpreted as a Perl-compatible regular expression, and REPLACEMENT can contain C-style escape sequences like <code>\t</code> as well as references to capturing groups by number or name as <code>$n</code> or <code>${n}</code>. Exit status: 0 if at least one replacement was performed, or 1 otherwise.</li>
</ul>
<h2><a class="anchor" id="regular-expressions"></a>
Regular Expressions</h2>
<p>Both the <code>match</code> and <code>replace</code> subcommand support regular expressions when used with the <code>-r</code> or <code>--regex</code> option. The dialect is that of PCRE2.</p>
<p>In general, special characters are special by default, so <code>a+</code> matches one or more "a"s, while <code>a\+</code> matches an "a" and then a "+". <code>(a+)</code> matches one or more "a"s in a capturing group (<code>(?:XXXX)</code> denotes a non-capturing group). For the replacement parameter of <code>replace</code>, <code>$n</code> refers to the n-th group of the match. In the match parameter, <code>\n</code> (e.g. <code>\1</code>) refers back to groups.</p>
<h2><a class="anchor" id="string-example"></a>
Examples</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">length</span> <span class="string">'hello, world'</span>
<span class="output">12</span>
<span class="prompt">></span> <span class="command">set</span> <span class="argument">str</span> <span class="argument">foo</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">length</span> <span class="argument">-q</span> <span class="variable"><span class="operator">$</span>str</span><span class="redirect">;</span> <span class="command">echo</span> <span class="variable"><span class="operator">$</span>status</span>
0
<span class="comment"># Equivalent to test -n $str</span>
</pre>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">sub</span> <span class="argument">--length</span> <span class="argument">2</span> <span class="argument">abcde</span>
<span class="output">ab</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">sub</span> <span class="argument">-s</span> <span class="argument">2</span> <span class="argument">-l</span> <span class="argument">2</span> <span class="argument">abcde</span>
<span class="output">bc</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">sub</span> <span class="argument">--start=-2</span> <span class="argument">abcde</span>
<span class="output">de</span>
</pre>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">split</span> <span class="argument">.</span> <span class="file">example.com</span>
<span class="output">example</span>
<span class="output">com</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">split</span> <span class="argument">-r</span> <span class="argument">-m1</span> <span class="path">/</span> <span class="path">/usr/local/bin/fish</span>
<span class="output">/usr/local/bin</span>
<span class="output">fish</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">split</span> '' <span class="argument">abc</span>
<span class="output">a</span>
<span class="output">b</span>
<span class="output">c</span>
</pre>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="binary">seq</span> <span class="argument">3</span> <span class="redirect">|</span> <span class="command">string</span> <span class="argument">join</span> <span class="argument">...</span>
<span class="output">1...2...3</span>
</pre>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">trim</span> <span class="string">' abc '</span>
<span class="output">abc</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">trim</span> <span class="argument">--right</span> <span class="argument">--chars=yz</span> <span class="argument">xyzzy</span> <span class="argument">zany</span>
<span class="output">x</span>
<span class="output">zan</span>
</pre>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">echo</span> <span>\</span>x07 <span class="redirect">|</span> <span class="command">string</span> <span class="argument">escape</span>
<span>\</span>cg
</pre><h2><a class="anchor" id="string-example-match-glob"></a>
Match Glob Examples</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="string">'?'</span> <span class="argument">a</span>
<span class="output">a</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="string">'a*b'</span> <span class="argument">axxb</span>
<span class="output">axxb</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-i</span> <span class="string">'a??B'</span> <span class="argument">Axxb</span>
<span class="output">Axxb</span>
<span class="prompt">></span> <span class="command">echo</span> <span class="string">'ok?'</span> <span class="redirect">|</span> <span class="command">string</span> <span class="argument">match</span> <span class="string">'*<span>\</span>?'</span>
>_ <span class="output">ok?</span>
</pre><h2><a class="anchor" id="string-example-match-regex"></a>
Match Regex Examples</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-r</span> <span class="string">'cat|dog|fish'</span> <span class="string">'nice dog'</span>
<span class="output">dog</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-r</span> <span class="argument">-v</span> <span class="string">"c.*[12]"</span> {<span class="argument">cat</span>,dog}<span class="operator">(</span><span class="binary">seq</span> <span class="argument">1</span> <span class="argument">4</span><span class="operator">)</span>
<span class="output">dog1</span>
<span class="output">dog2</span>
<span class="output">cat3</span>
<span class="output">dog3</span>
<span class="output">cat4</span>
<span class="output">dog4</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-r</span> <span class="string">'<span class="operator">(</span><span>\</span>d<span>\</span>d?<span class="operator">)</span>:<span class="operator">(</span><span>\</span>d<span>\</span>d<span class="operator">)</span>:<span class="operator">(</span><span>\</span>d<span>\</span>d<span class="operator">)</span>'</span> 2:34:56
<span class="output">2:34:56</span>
<span class="output">2</span>
<span class="output">34</span>
<span class="output">56</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-r</span> <span class="string">'^<span class="operator">(</span><span>\</span>w{2,4}<span class="operator">)</span><span>\</span>g1$'</span> <span class="argument">papa</span> <span class="argument">mud</span> <span class="argument">murmur</span>
<span class="output">papa</span>
<span class="output">pa</span>
<span class="output">murmur</span>
<span class="output">mur</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-r</span> <span class="argument">-a</span> <span class="argument">-n</span> <span class="argument">at</span> <span class="argument">ratatat</span>
<span class="output">2 2</span>
<span class="output">4 2</span>
<span class="output">6 2</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">match</span> <span class="argument">-r</span> <span class="argument">-i</span> <span class="string">'0x[0-9a-f]{1,8}'</span> <span class="string">'int magic = 0xBadC0de;'</span>
<span class="output">0xBadC0de</span>
</pre><h2><a class="anchor" id="string-example-replace-literal"></a>
Replace Literal Examples</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">replace</span> <span class="argument">is</span> <span class="argument">was</span> <span class="string">'blue is my favorite'</span>
<span class="output">blue was my favorite</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">replace</span> <span class="argument">3rd</span> <span class="argument">last</span> <span class="argument">1st</span> <span class="argument">2nd</span> <span class="argument">3rd</span>
<span class="output">1st</span>
<span class="output">2nd</span>
<span class="output">last</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">replace</span> <span class="argument">-a</span> <span class="string">' '</span> _ <span class="string">'spaces to underscores'</span>
<span class="output">spaces_to_underscores</span>
</pre><h2><a class="anchor" id="string-example-replace-Regex"></a>
Replace Regex Examples</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">string</span> <span class="argument">replace</span> <span class="argument">-r</span> <span class="argument">-a</span> <span class="string">'[^<span>\</span>d.]+'</span> <span class="string">' '</span> <span class="string">'0 one two 3.14 four 5x'</span>
<span class="output">0 3.14 5</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">replace</span> <span class="argument">-r</span> <span class="string">'<span class="operator">(</span><span>\</span>w+<span class="operator">)</span><span>\</span>s+<span class="operator">(</span><span>\</span>w+<span class="operator">)</span>'</span> <span class="string">'$2 $1 $$'</span> <span class="string">'left right'</span>
<span class="output">right left $</span>
<span class="prompt">></span> <span class="command">string</span> <span class="argument">replace</span> <span class="argument">-r</span> <span class="string">'<span>\</span>s*newline<span>\</span>s*'</span> <span class="string">'<span>\</span>n'</span> <span class="string">'put a newline here'</span>
<span class="output">put a</span>
<span class="output">here</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="suspend"></a>
suspend - suspend the current shell</h1>
<h2><a class="anchor" id="suspend-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">suspend</span> <span class="argument">[</span><span class="argument">--force</span>]
</pre><h2><a class="anchor" id="suspend-description"></a>
Description</h2>
<p><code>suspend</code> suspends execution of the current shell by sending it a SIGTSTP signal, returning to the controlling process. It can be resumed later by sending it a SIGCONT. In order to prevent suspending a shell that doesn't have a controlling process, it will not suspend the shell if it is a login shell. This requirement is bypassed if the <code>--force</code> option is given or the shell is not interactive.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="switch"></a>
switch - conditionally execute a block of commands</h1>
<h2><a class="anchor" id="switch-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">switch</span> <span class="argument">VALUE</span><span class="redirect">;</span> <span class="argument">[</span><span class="command">case</span> <span class="argument">[WILDCARD...]</span><span class="redirect">;</span> <span class="argument">[COMMANDS...]</span><span class="redirect">;</span> <span class="argument">...]</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="switch-description"></a>
Description</h2>
<p><code>switch</code> performs one of several blocks of commands, depending on whether a specified value equals one of several wildcarded values. <code>case</code> is used together with the <code>switch</code> statement in order to determine which block should be executed.</p>
<p>Each <code>case</code> command is given one or more parameters. The first <code>case</code> command with a parameter that matches the string specified in the switch command will be evaluated. <code>case</code> parameters may contain wildcards. These need to be escaped or quoted in order to avoid regular wildcard expansion using filenames.</p>
<p>Note that fish does not fall through on case statements. Only the first matching case is executed.</p>
<p>Note that command substitutions in a case statement will be evaluated even if its body is not taken. All substitutions, including command substitutions, must be performed before the value can be compared against the parameter.</p>
<h2><a class="anchor" id="switch-example"></a>
Example</h2>
<p>If the variable $animal contains the name of an animal, the following code would attempt to classify it:</p>
<pre class="fish">
<span class="command">switch</span> <span class="variable"><span class="operator">$</span>animal</span>
<span class="command">case</span> <span class="argument">cat</span>
<span class="command">echo</span> <span class="argument">evil</span>
<span class="command">case</span> <span class="argument">wolf</span> <span class="argument">dog</span> <span class="argument">human</span> <span class="argument">moose</span> <span class="argument">dolphin</span> <span class="argument">whale</span>
<span class="command">echo</span> <span class="argument">mammal</span>
<span class="command">case</span> <span class="argument">duck</span> <span class="argument">goose</span> <span class="argument">albatross</span>
<span class="command">echo</span> <span class="argument">bird</span>
<span class="command">case</span> <span class="argument">shark</span> <span class="argument">trout</span> <span class="argument">stingray</span>
<span class="command">echo</span> <span class="argument">fish</span>
<span class="command">case</span> <span class="string">'*'</span>
<span class="command">echo</span> <span class="argument">I</span> <span class="argument">have</span> <span class="argument">no</span> <span class="argument">idea</span> <span class="argument">what</span> <span class="argument">a</span> <span class="variable"><span class="operator">$</span>animal</span> <span class="argument">is</span>
<span class="command">end</span>
</pre><p>If the above code was run with <code>$animal</code> set to <code>whale</code>, the output would be <code>mammal</code>.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="test"></a>
test - perform tests on files and text</h1>
<h2><a class="anchor" id="test-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">test</span> <span class="argument">[EXPRESSION]</span>
[ <span class="argument">[EXPRESSION]</span> <span class="argument">]</span>
</pre><h2><a class="anchor" id="test-description"></a>
Description</h2>
<p>Tests the expression given and sets the exit status to 0 if true, and 1 if false. An expression is made up of one or more operators and their arguments.</p>
<p>The first form (<code>test</code>) is preferred. For compatibility with other shells, the second form is available: a matching pair of square brackets (<code>[ [EXPRESSION ] ]</code>).</p>
<p>This test is mostly POSIX-compatible.</p>
<h2><a class="anchor" id="test-files"></a>
Operators for files and directories</h2>
<ul>
<li><code>-b FILE</code> returns true if <code>FILE</code> is a block device.</li>
<li><code>-c FILE</code> returns true if <code>FILE</code> is a character device.</li>
<li><code>-d FILE</code> returns true if <code>FILE</code> is a directory.</li>
<li><code>-e FILE</code> returns true if <code>FILE</code> exists.</li>
<li><code>-f FILE</code> returns true if <code>FILE</code> is a regular file.</li>
<li><code>-g FILE</code> returns true if <code>FILE</code> has the set-group-ID bit set.</li>
<li><code>-G FILE</code> returns true if <code>FILE</code> exists and has the same group ID as the current user.</li>
<li><code>-L FILE</code> returns true if <code>FILE</code> is a symbolic link.</li>
<li><code>-O FILE</code> returns true if <code>FILE</code> exists and is owned by the current user.</li>
<li><code>-p FILE</code> returns true if <code>FILE</code> is a named pipe.</li>
<li><code>-r FILE</code> returns true if <code>FILE</code> is marked as readable.</li>
<li><code>-s FILE</code> returns true if the size of <code>FILE</code> is greater than zero.</li>
<li><code>-S FILE</code> returns true if <code>FILE</code> is a socket.</li>
<li><code>-t FD</code> returns true if the file descriptor <code>FD</code> is a terminal (TTY).</li>
<li><code>-u FILE</code> returns true if <code>FILE</code> has the set-user-ID bit set.</li>
<li><code>-w FILE</code> returns true if <code>FILE</code> is marked as writable; note that this does not check if the filesystem is read-only.</li>
<li><code>-x FILE</code> returns true if <code>FILE</code> is marked as executable.</li>
</ul>
<h2><a class="anchor" id="test-strings"></a>
Operators for text strings</h2>
<ul>
<li><code>STRING1 = STRING2</code> returns true if the strings <code>STRING1</code> and <code>STRING2</code> are identical.</li>
<li><code>STRING1 != STRING2</code> returns true if the strings <code>STRING1</code> and <code>STRING2</code> are not identical.</li>
<li><code>-n STRING</code> returns true if the length of <code>STRING</code> is non-zero.</li>
<li><code>-z STRING</code> returns true if the length of <code>STRING</code> is zero.</li>
</ul>
<h2><a class="anchor" id="test-numbers"></a>
Operators to compare and examine numbers</h2>
<ul>
<li><code>NUM1 -eq NUM2</code> returns true if <code>NUM1</code> and <code>NUM2</code> are numerically equal.</li>
<li><code>NUM1 -ne NUM2</code> returns true if <code>NUM1</code> and <code>NUM2</code> are not numerically equal.</li>
<li><code>NUM1 -gt NUM2</code> returns true if <code>NUM1</code> is greater than <code>NUM2</code>.</li>
<li><code>NUM1 -ge NUM2</code> returns true if <code>NUM1</code> is greater than or equal to <code>NUM2</code>.</li>
<li><code>NUM1 -lt NUM2</code> returns true if <code>NUM1</code> is less than <code>NUM2</code>.</li>
<li><code>NUM1 -le NUM2</code> returns true if <code>NUM1</code> is less than or equal to <code>NUM2</code>.</li>
</ul>
<p>Note that only integers are supported. For more complex mathematical operations, including fractions, the <code>env</code> program may be useful. Consult the documentation for your operating system.</p>
<h2><a class="anchor" id="test-combinators"></a>
Operators to combine expressions</h2>
<ul>
<li><code>COND1 -a COND2</code> returns true if both <code>COND1</code> and <code>COND2</code> are true.</li>
<li><code>COND1 -o COND2</code> returns true if either <code>COND1</code> or <code>COND2</code> are true.</li>
</ul>
<p>Expressions can be inverted using the <code>!</code> operator:</p>
<ul>
<li><code>! EXPRESSION</code> returns true if <code>EXPRESSION</code> is false, and false if <code>EXPRESSION</code> is true.</li>
</ul>
<p>Expressions can be grouped using parentheses.</p>
<ul>
<li><p class="startli"><code>( EXPRESSION )</code> returns the value of <code>EXPRESSION</code>.</p>
<p class="startli">Note that parentheses will usually require escaping with <code>\(</code> to avoid being interpreted as a command substitution.</p>
</li>
</ul>
<h2><a class="anchor" id="test-example"></a>
Examples</h2>
<p>If the <code>/tmp</code> directory exists, copy the <code>/etc/motd</code> file to it:</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="argument">-d</span> <span class="path">/tmp</span>
<span class="binary">cp</span> <span class="path">/etc/motd</span> <span class="path">/tmp/motd</span>
<span class="command">end</span>
</pre><p>If the variable <code>MANPATH</code> is defined and not empty, print the contents. (If <code>MANPATH</code> is not defined, then it will expand to zero arguments, unless quoted.)</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="argument">-n</span> <span class="string">"$MANPATH"</span>
<span class="command">echo</span> <span class="variable"><span class="operator">$</span>MANPATH</span>
<span class="command">end</span>
</pre><p>Parentheses and the <code>-o</code> and <code>-a</code> operators can be combined to produce more complicated expressions. In this example, success is printed if there is a <code>/foo</code> or <code>/bar</code> file as well as a <code>/baz</code> or <code>/bat</code> file.</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="operator"><span>\</span><span class="operator">(</span></span> <span class="argument">-f</span> <span class="path">/foo</span> <span class="argument">-o</span> <span class="argument">-f</span> <span class="path">/bar</span> <span class="operator"><span>\</span><span class="operator">)</span></span> <span class="argument">-a</span> <span class="operator"><span>\</span><span class="operator">(</span></span> <span class="argument">-f</span> <span class="path">/baz</span> <span class="argument">-o</span> <span class="argument">-f</span> <span class="path">/bat</span> <span class="operator"><span>\</span><span class="operator">)</span></span>
<span class="command">echo</span> <span class="argument">Success.</span>
<span class="command">end</span><span class="argument">.</span>
</pre><p>Numerical comparisons will simply fail if one of the operands is not a number:</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="argument">42</span> <span class="argument">-eq</span> <span class="string">"The answer to life, the universe and everything"</span>
<span class="command">echo</span> <span class="argument">So</span> <span class="argument">long</span> <span class="argument">and</span> <span class="argument">thanks</span> <span class="command">for</span> <span class="argument">all</span> <span class="argument">the</span> <span class="argument">fish</span> <span class="comment">## will not be executed</span>
<span class="command">end</span>
</pre><p>A common comparison is with $status:</p>
<pre class="fish">
<span class="command">if</span> <span class="command">test</span> <span class="variable"><span class="operator">$</span>status</span> <span class="argument">-eq</span> <span class="argument">0</span>
<span class="command">echo</span> <span class="string">"Previous command succeeded"</span>
<span class="command">end</span>
</pre><h2><a class="anchor" id="test-standards"></a>
Standards</h2>
<p><code>test</code> implements a subset of the <a href="http://www.unix.com/man-page/POSIX/1/test/">IEEE Std 1003.1-2008 (POSIX.1) standard</a>. The following exceptions apply:</p>
<ul>
<li>The <code><</code> and <code>></code> operators for comparing strings are not implemented.</li>
<li><p class="startli">Because this test is a shell builtin and not a standalone utility, using the -c flag on a special file descriptors like standard input and output may not return the same result when invoked from within a pipe as one would expect when invoking the <code>test</code> utility in another shell.</p>
<p class="startli">In cases such as this, one can use <code>command</code> <code>test</code> to explicitly use the system's standalone <code>test</code> rather than this <code>builtin</code> <code>test</code>.</p>
</li>
</ul>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="trap"></a>
trap - perform an action when the shell receives a signal</h1>
<h2><a class="anchor" id="trap-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">trap</span> <span class="argument">[OPTIONS]</span> <span class="argument">[</span><span class="argument">[ARG]</span> <span class="argument">SIGSPEC</span> <span class="argument">...</span> <span class="argument">]</span>
</pre><h2><a class="anchor" id="trap-description"></a>
Description</h2>
<p><code>trap</code> is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an <a href="index.html#event">event handler</a>.</p>
<p>The following parameters are available:</p>
<ul>
<li><code>ARG</code> is the command to be executed on signal delivery.</li>
<li><code>SIGSPEC</code> is the name of the signal to trap.</li>
<li><code>-l</code> or <code>--list-signals</code> prints a list of signal names.</li>
<li><code>-p</code> or <code>--print</code> prints all defined signal handlers.</li>
</ul>
<p>If <code>ARG</code> and <code>SIGSPEC</code> are both specified, <code>ARG</code> is the command to be executed when the signal specified by <code>SIGSPEC</code> is delivered.</p>
<p>If <code>ARG</code> is absent (and there is a single SIGSPEC) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell). If <code>ARG</code> is the null string the signal specified by each <code>SIGSPEC</code> is ignored by the shell and by the commands it invokes.</p>
<p>If <code>ARG</code> is not present and <code>-p</code> has been supplied, then the trap commands associated with each <code>SIGSPEC</code> are displayed. If no arguments are supplied or if only <code>-p</code> is given, <code>trap</code> prints the list of commands associated with each signal.</p>
<p>Signal names are case insensitive and the <code>SIG</code> prefix is optional.</p>
<p>The return status is 1 if any <code>SIGSPEC</code> is invalid; otherwise trap returns 0.</p>
<h2><a class="anchor" id="trap-example"></a>
Example</h2>
<pre class="fish">
<span class="command">trap</span> <span class="string">"status --print-stack-trace"</span> <span class="argument">SIGUSR1</span>
<span class="comment"># Prints a stack trace each time the SIGUSR1 signal is sent to the shell.</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="true"></a>
true - return a successful result</h1>
<h2><a class="anchor" id="true-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">true</span>
</pre><h2><a class="anchor" id="true-description"></a>
Description</h2>
<p><code>true</code> sets the exit status to 0.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="type"></a>
type - indicate how a command would be interpreted</h1>
<h2><a class="anchor" id="type-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">type</span> <span class="argument">[OPTIONS]</span> <span class="argument">NAME</span> <span class="argument">[NAME <span class="argument">...]</span></span>
</pre><h2><a class="anchor" id="type-description"></a>
Description</h2>
<p>With no options, <code>type</code> indicates how each <code>NAME</code> would be interpreted if used as a command name.</p>
<p>The following options are available:</p>
<ul>
<li><code>-a</code> or <code>--all</code> prints all of possible definitions of the specified names.</li>
<li><code>-f</code> or <code>--no-functions</code> suppresses function and builtin lookup.</li>
<li><code>-t</code> or <code>--type</code> prints <code>function</code>, <code>builtin</code>, or <code>file</code> if <code>NAME</code> is a shell function, builtin, or disk file, respectively.</li>
<li><code>-p</code> or <code>--path</code> returns the name of the disk file that would be executed, or nothing if <code>type -t name</code> would not return <code>file</code>.</li>
<li><code>-P</code> or <code>--force-path</code> returns the name of the disk file that would be executed, or nothing if no file with the specified name could be found in the <code>$PATH</code>.</li>
<li><code>-q</code> or <code>--quiet</code> suppresses all output; this is useful when testing the exit status.</li>
</ul>
<h2><a class="anchor" id="type-example"></a>
Example</h2>
<pre class="fish cli-dark">
<span class="prompt">></span> <span class="command">type</span> <span class="argument">fg</span>
<span class="output">fg is a builtin</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="ulimit"></a>
ulimit - set or get resource usage limits</h1>
<h2><a class="anchor" id="ulimit-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">ulimit</span> <span class="argument">[OPTIONS]</span> <span class="argument">[LIMIT]</span>
</pre><h2><a class="anchor" id="ulimit-description"></a>
Description</h2>
<p><code>ulimit</code> builtin sets or outputs the resource usage limits of the shell and any processes spawned by it. If a new limit value is omitted, the current value of the limit of the resource is printed; otherwise, the specified limit is set to the new value.</p>
<p>Use one of the following switches to specify which resource limit to set or report:</p>
<ul>
<li><code>-c</code> or <code>--core-size</code>: the maximum size of core files created. By setting this limit to zero, core dumps can be disabled.</li>
<li><code>-d</code> or <code>--data-size</code>: the maximum size of a process' data segment.</li>
<li><code>-f</code> or <code>--file-size</code>: the maximum size of files created by the shell.</li>
<li><code>-l</code> or <code>--lock-size</code>: the maximum size that may be locked into memory.</li>
<li><code>-m</code> or <code>--resident-set-size</code>: the maximum resident set size.</li>
<li><code>-n</code> or <code>--file-descriptor-count</code>: the maximum number of open file descriptors (most systems do not allow this value to be set).</li>
<li><code>-s</code> or <code>--stack-size</code>: the maximum stack size.</li>
<li><code>-t</code> or <code>--cpu-time</code>: the maximum amount of CPU time in seconds.</li>
<li><code>-u</code> or <code>--process-count</code>: the maximum number of processes available to a single user.</li>
<li><code>-v</code> or <code>--virtual-memory-size</code> The maximum amount of virtual memory available to the shell.</li>
</ul>
<p>Note that not all these limits are available in all operating systems.</p>
<p>The value of limit can be a number in the unit specified for the resource or one of the special values <code>hard</code>, <code>soft</code>, or <code>unlimited</code>, which stand for the current hard limit, the current soft limit, and no limit, respectively.</p>
<p>If limit is given, it is the new value of the specified resource. If no option is given, then <code>-f</code> is assumed. Values are in kilobytes, except for <code>-t</code>, which is in seconds and <code>-n</code> and <code>-u</code>, which are unscaled values. The return status is 0 unless an invalid option or argument is supplied, or an error occurs while setting a new limit.</p>
<p><code>ulimit</code> also accepts the following switches that determine what type of limit to set:</p>
<ul>
<li><code>-H</code> or <code>--hard</code> sets hard resource limit</li>
<li><code>-S</code> or <code>--soft</code> sets soft resource limit</li>
</ul>
<p>A hard limit can only be decreased. Once it is set it cannot be increased; a soft limit may be increased up to the value of the hard limit. If neither -H nor -S is specified, both the soft and hard limits are updated when assigning a new limit value, and the soft limit is used when reporting the current value.</p>
<p>The following additional options are also understood by <code>ulimit</code>:</p>
<ul>
<li><code>-a</code> or <code>--all</code> prints all current limits</li>
</ul>
<p>The <code>fish</code> implementation of <code>ulimit</code> should behave identically to the implementation in bash, except for these differences:</p>
<ul>
<li>Fish <code>ulimit</code> supports GNU-style long options for all switches</li>
<li>Fish <code>ulimit</code> does not support the <code>-p</code> option for getting the pipe size. The bash implementation consists of a compile-time check that empirically guesses this number by writing to a pipe and waiting for SIGPIPE. Fish does not do this because it this method of determining pipe size is unreliable. Depending on bash version, there may also be further additional limits to set in bash that do not exist in fish.</li>
<li>Fish <code>ulimit</code> does not support getting or setting multiple limits in one command, except reporting all values using the -a switch</li>
</ul>
<h2><a class="anchor" id="ulimit-example"></a>
Example</h2>
<p><code>ulimit -Hs 64</code> sets the hard stack size limit to 64 kB.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="umask"></a>
umask - set or get the file creation mode mask</h1>
<h2><a class="anchor" id="umask-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">umask</span> <span class="argument">[OPTIONS]</span> <span class="argument">[MASK]</span>
</pre><h2><a class="anchor" id="umask-description"></a>
Description</h2>
<p><code>umask</code> displays and manipulates the "umask", or file creation mode mask, which is used to restrict the default access to files.</p>
<p>The umask may be expressed either as an octal number, which represents the rights that will be removed by default, or symbolically, which represents the only rights that will be granted by default.</p>
<p>Access rights are explained in the manual page for the <code>chmod</code>(1) program.</p>
<p>With no parameters, the current file creation mode mask is printed as an octal number.</p>
<ul>
<li><code>-h</code> or <code>--help</code> prints this message.</li>
<li><code>-S</code> or <code>--symbolic</code> prints the umask in symbolic form instead of octal form.</li>
<li><code>-p</code> or <code>--as-command</code> outputs the umask in a form that may be reused as input</li>
</ul>
<p>If a numeric mask is specified as a parameter, the current shell's umask will be set to that value, and the rights specified by that mask will be removed from new files and directories by default.</p>
<p>If a symbolic mask is specified, the desired permission bits, and not the inverse, should be specified. A symbolic mask is a comma separated list of rights. Each right consists of three parts:</p>
<ul>
<li>The first part specifies to whom this set of right applies, and can be one of <code>u</code>, <code>g</code>, <code>o</code> or <code>a</code>, where <code>u</code> specifies the user who owns the file, <code>g</code> specifies the group owner of the file, <code>o</code> specific other users rights and <code>a</code> specifies all three should be changed.</li>
<li>The second part of a right specifies the mode, and can be one of <code>=</code>, <code>+</code> or <code>-</code>, where <code>=</code> specifies that the rights should be set to the new value, <code>+</code> specifies that the specified right should be added to those previously specified and <code>-</code> specifies that the specified rights should be removed from those previously specified.</li>
<li>The third part of a right specifies what rights should be changed and can be any combination of <code>r</code>, <code>w</code> and <code>x</code>, representing read, write and execute rights.</li>
</ul>
<p>If the first and second parts are skipped, they are assumed to be <code>a</code> and <code>=</code>, respectively. As an example, <code>r,u+w</code> means all users should have read access and the file owner should also have write access.</p>
<p>Note that symbolic masks currently do not work as intended.</p>
<h2><a class="anchor" id="umask-example"></a>
Example</h2>
<p><code>umask 177</code> or <code>umask u=rw</code> sets the file creation mask to read and write for the owner and no permissions at all for any other users.</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="vared"></a>
vared - interactively edit the value of an environment variable</h1>
<h2><a class="anchor" id="vared-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">vared</span> <span class="argument">VARIABLE_NAME</span>
</pre><h2><a class="anchor" id="vared-description"></a>
Description</h2>
<p><code>vared</code> is used to interactively edit the value of an environment variable. Array variables as a whole can not be edited using <code>vared</code>, but individual array elements can.</p>
<h2><a class="anchor" id="vared-example"></a>
Example</h2>
<p><code>vared PATH[3]</code> edits the third element of the PATH array</p>
<p>Back to <a href="index.html#toc-commands">command index</a>. </p><hr/>
<h1><a class="anchor" id="while"></a>
while - perform a command multiple times</h1>
<h2><a class="anchor" id="while-synopsis"></a>
Synopsis</h2>
<pre class="fish synopsis">
<span class="command">while</span> <span class="argument">CONDITION</span><span class="redirect">;</span> <span class="argument">COMMANDS...</span><span class="redirect">;</span> <span class="command">end</span>
</pre><h2><a class="anchor" id="while-description"></a>
Description</h2>
<p><code>while</code> repeatedly executes <code>CONDITION</code>, and if the exit status is 0, then executes <code>COMMANDS</code>.</p>
<p>If the exit status of <code>CONDITION</code> is non-zero on the first iteration, <code>COMMANDS</code> will not be executed at all.</p>
<p>You can use <a href="#and"><code>and</code></a> or <a href="#or"><code>or</code></a> for complex conditions. Even more complex control can be achieved with <code>while true</code> containing a <a href="#break">break</a>.</p>
<h2><a class="anchor" id="while-example"></a>
Example</h2>
<pre class="fish">
<span class="command">while</span> <span class="argument">test</span> <span class="argument">-f</span> <span class="file">foo.txt</span><span class="redirect">;</span> <span class="command">or</span> <span class="command">test</span> <span class="argument">-f</span> <span class="file">bar.txt</span> ; <span class="command">echo</span> <span class="argument">file</span> <span class="argument">exists</span><span class="redirect">;</span> <span class="command">sleep</span> <span class="argument">10</span><span class="redirect">;</span> <span class="command">end</span>
<span class="comment"># outputs 'file exists' at 10 second intervals as long as the file foo.txt or bar.txt exists.</span>
</pre><p>Back to <a href="index.html#toc-commands">command index</a>.</p>
</div>
</div></div><!-- contents -->
</body>
</html>
|