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
|
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>The fish language — fish-shell 4.2.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=4da8bbd6" />
<link rel="stylesheet" type="text/css" href="_static/pydoctheme.css?v=f89b4716" />
<script src="_static/documentation_options.js?v=6fb65176"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Commands" href="commands.html" />
<link rel="prev" title="Interactive use" href="interactive.html" />
<link rel="shortcut icon" type="image/png" href="_static/fish.png" />
</head><body><div id="fmain">
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-this"><a href="">The fish language</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Documents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently asked questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="interactive.html">Interactive use</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">The fish language</a></li>
<li class="toctree-l1"><a class="reference internal" href="commands.html">Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="fish_for_bash_users.html">Fish for bash users</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="completions.html">Writing your own completions</a></li>
<li class="toctree-l1"><a class="reference internal" href="prompt.html">Writing your own prompt</a></li>
<li class="toctree-l1"><a class="reference internal" href="design.html">Design</a></li>
<li class="toctree-l1"><a class="reference internal" href="relnotes.html">Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="terminal-compatibility.html">Terminal Compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributing.html">Contributing To Fish</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<div>
<h4><a href="index.html">Sections</a></h4>
<ul>
<li><a class="reference internal" href="#">The fish language</a><ul>
<li><a class="reference internal" href="#syntax-overview">Syntax overview</a></li>
<li><a class="reference internal" href="#terminology">Terminology</a></li>
<li><a class="reference internal" href="#quotes">Quotes</a></li>
<li><a class="reference internal" href="#escaping-characters">Escaping Characters</a></li>
<li><a class="reference internal" href="#input-output-redirection">Input/Output Redirection</a></li>
<li><a class="reference internal" href="#piping">Piping</a></li>
<li><a class="reference internal" href="#combining-pipes-and-redirections">Combining pipes and redirections</a></li>
<li><a class="reference internal" href="#job-control">Job control</a></li>
<li><a class="reference internal" href="#functions">Functions</a><ul>
<li><a class="reference internal" href="#defining-aliases">Defining aliases</a></li>
<li><a class="reference internal" href="#autoloading-functions">Autoloading functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#comments">Comments</a></li>
<li><a class="reference internal" href="#conditions">Conditions</a><ul>
<li><a class="reference internal" href="#the-if-statement">The <code class="docutils literal notranslate"><span class="pre">if</span></code> statement</a></li>
<li><a class="reference internal" href="#the-switch-statement">The <code class="docutils literal notranslate"><span class="pre">switch</span></code> statement</a></li>
<li><a class="reference internal" href="#combiners-and-or">Combiners (<code class="docutils literal notranslate"><span class="pre">and</span></code> / <code class="docutils literal notranslate"><span class="pre">or</span></code> / <code class="docutils literal notranslate"><span class="pre">&&</span></code> / <code class="docutils literal notranslate"><span class="pre">||</span></code>)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#loops-and-blocks">Loops and blocks</a></li>
<li><a class="reference internal" href="#parameter-expansion">Parameter expansion</a><ul>
<li><a class="reference internal" href="#wildcards-globbing">Wildcards (“Globbing”)</a></li>
<li><a class="reference internal" href="#variable-expansion">Variable expansion</a><ul>
<li><a class="reference internal" href="#quoting-variables">Quoting variables</a></li>
<li><a class="reference internal" href="#dereferencing-variables">Dereferencing variables</a></li>
<li><a class="reference internal" href="#variables-as-command">Variables as command</a></li>
</ul>
</li>
<li><a class="reference internal" href="#command-substitution">Command substitution</a></li>
<li><a class="reference internal" href="#brace-expansion">Brace expansion</a></li>
<li><a class="reference internal" href="#combining-lists">Combining lists</a></li>
<li><a class="reference internal" href="#slices">Slices</a></li>
<li><a class="reference internal" href="#home-directory-expansion">Home directory expansion</a></li>
<li><a class="reference internal" href="#combining-different-expansions">Combining different expansions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#table-of-operators">Table Of Operators</a></li>
<li><a class="reference internal" href="#shell-variables">Shell variables</a><ul>
<li><a class="reference internal" href="#variable-scope">Variable Scope</a></li>
<li><a class="reference internal" href="#overriding-variables-for-a-single-command">Overriding variables for a single command</a></li>
<li><a class="reference internal" href="#universal-variables">Universal Variables</a></li>
<li><a class="reference internal" href="#exporting-variables">Exporting variables</a></li>
<li><a class="reference internal" href="#lists">Lists</a></li>
<li><a class="reference internal" href="#argument-handling">Argument Handling</a></li>
<li><a class="reference internal" href="#path-variables">PATH variables</a></li>
<li><a class="reference internal" href="#special-variables">Special variables</a></li>
<li><a class="reference internal" href="#the-status-variable">The status variable</a></li>
<li><a class="reference internal" href="#locale-variables">Locale Variables</a></li>
</ul>
</li>
<li><a class="reference internal" href="#builtin-commands">Builtin commands</a></li>
<li><a class="reference internal" href="#command-lookup">Command lookup</a></li>
<li><a class="reference internal" href="#querying-for-user-input">Querying for user input</a></li>
<li><a class="reference internal" href="#shell-variable-and-function-names">Shell variable and function names</a></li>
<li><a class="reference internal" href="#configuration-files">Configuration files</a></li>
<li><a class="reference internal" href="#future-feature-flags">Future feature flags</a></li>
<li><a class="reference internal" href="#event-handlers">Event handlers</a></li>
<li><a class="reference internal" href="#debugging-fish-scripts">Debugging fish scripts</a><ul>
<li><a class="reference internal" href="#profiling-fish-scripts">Profiling fish scripts</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="the-fish-language">
<h1>The fish language<a class="headerlink" href="#the-fish-language" title="Link to this heading">¶</a></h1>
<p>This document is a comprehensive overview of fish’s scripting language.</p>
<p>For interactive features see <a class="reference internal" href="interactive.html"><span class="doc">Interactive use</span></a>.</p>
<section id="syntax-overview">
<span id="syntax"></span><h2>Syntax overview<a class="headerlink" href="#syntax-overview" title="Link to this heading">¶</a></h2>
<p>Shells like fish are used by giving them commands. A command is executed by writing the name of the command followed by any arguments. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="no">hello</span><span class="w"> </span><span class="no">world</span>
</pre></div>
</div>
<p><a class="reference internal" href="cmds/echo.html"><span class="doc">echo</span></a> command writes its arguments to the screen. In this example the output is <code class="docutils literal notranslate"><span class="pre">hello</span> <span class="pre">world</span></code>.</p>
<p>Everything in fish is done with commands. There are commands for repeating other commands, commands for assigning variables, commands for treating a group of commands as a single command, etc. All of these commands follow the same basic syntax.</p>
<p>Every program on your computer can be used as a command in fish. If the program file is located in one of the <span class="target" id="index-0"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a> directories, you can just type the name of the program to use it. Otherwise the whole filename, including the directory (like <code class="docutils literal notranslate"><span class="pre">/home/me/code/checkers/checkers</span></code> or <code class="docutils literal notranslate"><span class="pre">../checkers</span></code>) is required.</p>
<p>Here is a list of some useful commands:</p>
<ul class="simple">
<li><p><a class="reference internal" href="cmds/cd.html"><span class="doc">cd</span></a>: Change the current directory</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ls</span></code>: List files and directories</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">man</span></code>: Display a manual page - try <code class="docutils literal notranslate"><span class="pre">man</span> <span class="pre">ls</span></code> to get help on your “ls” command, or <code class="docutils literal notranslate"><span class="pre">man</span> <span class="pre">mv</span></code> to get information about “mv”.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mv</span></code>: Move (rename) files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cp</span></code>: Copy files</p></li>
<li><p><a class="reference internal" href="cmds/open.html"><span class="doc">open</span></a>: Open files with the default application associated with each filetype</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">less</span></code>: Display the contents of files</p></li>
</ul>
<p>Commands and arguments are separated by the space character <code class="docutils literal notranslate"><span class="pre">'</span> <span class="pre">'</span></code>. Every command ends with either a newline (by pressing the return key) or a semicolon <code class="docutils literal notranslate"><span class="pre">;</span></code>. Multiple commands can be written on the same line by separating them with semicolons.</p>
<p>A switch is a very common special type of argument. Switches almost always start with one or more hyphens <code class="docutils literal notranslate"><span class="pre">-</span></code> and alter the way a command operates. For example, the <code class="docutils literal notranslate"><span class="pre">ls</span></code> command usually lists the names of all files and directories in the current working directory. By using the <code class="docutils literal notranslate"><span class="pre">-l</span></code> switch, the behavior of <code class="docutils literal notranslate"><span class="pre">ls</span></code> is changed to not only display the filename, but also the size, permissions, owner, and modification time of each file.</p>
<p>Switches differ between commands and are usually documented on a command’s manual page. There are some switches, however, that are common to most commands. For example, <code class="docutils literal notranslate"><span class="pre">--help</span></code> will usually display a help text, <code class="docutils literal notranslate"><span class="pre">--version</span></code> will usually display the command version, and <code class="docutils literal notranslate"><span class="pre">-i</span></code> will often turn on interactive prompting before taking action. Try <code class="docutils literal notranslate"><span class="pre">man</span> <span class="pre">your-command-here</span></code> to get information on your command’s switches.</p>
<p>So the basic idea of fish is the same as with other unix shells: It gets a commandline, runs <a class="reference internal" href="#expand"><span class="std std-ref">expansions</span></a>, and the result is then run as a command.</p>
</section>
<section id="terminology">
<h2>Terminology<a class="headerlink" href="#terminology" title="Link to this heading">¶</a></h2>
<p>Here we define some of the terms used on this page and throughout the rest of the fish documentation:</p>
<ul class="simple">
<li><p><strong>Argument</strong>: A parameter given to a command. In <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">foo</span></code>, the “foo” is an argument.</p></li>
<li><p><strong>Builtin</strong>: A command that is implemented by the shell. Builtins are so closely tied to the operation of the shell that it is impossible to implement them as external commands. In <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">foo</span></code>, the “echo” is a builtin.</p></li>
<li><p><strong>Command</strong>: A program that the shell can run, or more specifically an external program that the shell runs in another process. External commands are provided on your system, as executable files. In <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">foo</span></code> the “echo” is a builtin command, in <code class="docutils literal notranslate"><span class="pre">command</span> <span class="pre">echo</span> <span class="pre">foo</span></code> the “echo” is an external command, provided by a file like /bin/echo.</p></li>
<li><p><strong>Function</strong>: A block of commands that can be called as if they were a single command. By using functions, it is possible to string together multiple simple commands into one more advanced command.</p></li>
<li><p><strong>Job</strong>: A running pipeline or command.</p></li>
<li><p><strong>Pipeline</strong>: A set of commands strung together so that the output of one command is the input of the next command. <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">foo</span> <span class="pre">|</span> <span class="pre">grep</span> <span class="pre">foo</span></code> is a pipeline.</p></li>
<li><p><strong>Redirection</strong>: An operation that changes one of the input or output streams associated with a job.</p></li>
<li><p><strong>Switch</strong> or <strong>Option</strong>: A special kind of argument that alters the behavior of a command. A switch almost always begins with one or two hyphens. In <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">-n</span> <span class="pre">foo</span></code> the “-n” is an option.</p></li>
</ul>
</section>
<section id="quotes">
<span id="id1"></span><h2>Quotes<a class="headerlink" href="#quotes" title="Link to this heading">¶</a></h2>
<p>Sometimes you want to give a command an argument that contains characters special to fish, like spaces or <code class="docutils literal notranslate"><span class="pre">$</span></code> or <code class="docutils literal notranslate"><span class="pre">*</span></code>. To do that, you can use quotes:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">rm</span><span class="w"> </span><span class="s2">"my file.txt"</span>
</pre></div>
</div>
<p>to remove a file called <code class="docutils literal notranslate"><span class="pre">my</span> <span class="pre">file.txt</span></code> instead of trying to remove two files, <code class="docutils literal notranslate"><span class="pre">my</span></code> and <code class="docutils literal notranslate"><span class="pre">file.txt</span></code>.</p>
<p>Fish understands two kinds of quotes: Single (<code class="docutils literal notranslate"><span class="pre">'</span></code>) and double (<code class="docutils literal notranslate"><span class="pre">"</span></code>), and both work slightly differently.</p>
<p>Between single quotes, fish performs no expansions. Between double quotes, fish only performs <a class="reference internal" href="#expand-variable"><span class="std std-ref">variable expansion</span></a> and <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitution</span></a> in the <code class="docutils literal notranslate"><span class="pre">$(command)</span></code>. No other kind of expansion (including <a class="reference internal" href="#expand-brace"><span class="std std-ref">brace expansion</span></a> or parameter expansion) is performed, and escape sequences (for example, <code class="docutils literal notranslate"><span class="pre">\n</span></code>) are ignored. Within quotes, whitespace is not used to separate arguments, allowing quoted arguments to contain spaces.</p>
<p>The only meaningful escape sequences in single quotes are <code class="docutils literal notranslate"><span class="pre">\'</span></code>, which escapes a single quote and <code class="docutils literal notranslate"><span class="pre">\\</span></code>, which escapes the backslash symbol. The only meaningful escapes in double quotes are <code class="docutils literal notranslate"><span class="pre">\"</span></code>, which escapes a double quote, <code class="docutils literal notranslate"><span class="pre">\$</span></code>, which escapes a dollar character, <code class="docutils literal notranslate"><span class="pre">\</span></code> followed by a newline, which deletes the backslash and the newline, and <code class="docutils literal notranslate"><span class="pre">\\</span></code>, which escapes the backslash symbol.</p>
<p>Single quotes have no special meaning within double quotes and vice versa.</p>
<p>More examples:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">grep</span><span class="w"> </span><span class="s1">'enabled)$'</span><span class="w"> </span><span class="no">foo.txt</span>
</pre></div>
</div>
<p>searches for lines ending in <code class="docutils literal notranslate"><span class="pre">enabled)</span></code> in <code class="docutils literal notranslate"><span class="pre">foo.txt</span></code> (the <code class="docutils literal notranslate"><span class="pre">$</span></code> is special to <code class="docutils literal notranslate"><span class="pre">grep</span></code>: it matches the end of the line).</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">apt</span><span class="w"> </span><span class="no">install</span><span class="w"> </span><span class="s2">"postgres-*"</span>
</pre></div>
</div>
<p>installs all packages with a name starting with “postgres-”, instead of looking through the current directory for files named “postgres-something”.</p>
</section>
<section id="escaping-characters">
<span id="escapes"></span><h2>Escaping Characters<a class="headerlink" href="#escaping-characters" title="Link to this heading">¶</a></h2>
<p>Some characters cannot be written directly on the command line. For these characters, so-called escape sequences are provided. These are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">\a</span></code> represents the alert character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\e</span></code> represents the escape character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\f</span></code> represents the form feed character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\n</span></code> represents a newline character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\r</span></code> represents the carriage return character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\t</span></code> represents the tab character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\v</span></code> represents the vertical tab character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\xHH</span></code> or <code class="docutils literal notranslate"><span class="pre">\XHH</span></code>, where <code class="docutils literal notranslate"><span class="pre">HH</span></code> is a hexadecimal number, represents a byte of data with the specified value. For example, <code class="docutils literal notranslate"><span class="pre">\x9</span></code> is the tab character. If you are using a multibyte encoding, this can be used to enter invalid strings. Typically fish is run with the ASCII or UTF-8 encoding, so anything up to <code class="docutils literal notranslate"><span class="pre">\X7f</span></code> is an ASCII character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\ooo</span></code>, where <code class="docutils literal notranslate"><span class="pre">ooo</span></code> is an octal number, represents the ASCII character with the specified value. For example, <code class="docutils literal notranslate"><span class="pre">\011</span></code> is the tab character. The highest allowed value is <code class="docutils literal notranslate"><span class="pre">\177</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\uXXXX</span></code>, where <code class="docutils literal notranslate"><span class="pre">XXXX</span></code> is a hexadecimal number, represents the 16-bit Unicode character with the specified value. For example, <code class="docutils literal notranslate"><span class="pre">\u9</span></code> is the tab character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\UXXXXXXXX</span></code>, where <code class="docutils literal notranslate"><span class="pre">XXXXXXXX</span></code> is a hexadecimal number, represents the 32-bit Unicode character with the specified value. For example, <code class="docutils literal notranslate"><span class="pre">\U9</span></code> is the tab character. The highest allowed value is U10FFFF.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\cX</span></code>, where <code class="docutils literal notranslate"><span class="pre">X</span></code> is a letter of the alphabet, represents the control sequence generated by pressing the control key and the specified letter. For example, <code class="docutils literal notranslate"><span class="pre">\ci</span></code> is the tab character</p></li>
</ul>
<p>Some characters have special meaning to the shell. For example, an apostrophe <code class="docutils literal notranslate"><span class="pre">'</span></code> disables expansion (see <a class="reference internal" href="#quotes"><span class="std std-ref">Quotes</span></a>). To tell the shell to treat these characters literally, escape them with a backslash. For example, the command:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="se">\'</span><span class="no">hello</span><span class="w"> </span><span class="no">world</span><span class="se">\'</span>
</pre></div>
</div>
<p>outputs <code class="docutils literal notranslate"><span class="pre">'hello</span> <span class="pre">world'</span></code> (including the apostrophes), while the command:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="s1">'hello world'</span>
</pre></div>
</div>
<p>outputs <code class="docutils literal notranslate"><span class="pre">hello</span> <span class="pre">world</span></code> (without the apostrophes). In the former case the shell treats the apostrophes as literal <code class="docutils literal notranslate"><span class="pre">'</span></code> characters, while in the latter case it treats them as special expansion modifiers.</p>
<p>The special characters and their escape sequences are:</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">\ </span></code> (backslash space) escapes the space character. This keeps the shell from splitting arguments on the escaped space.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\$</span></code> escapes the dollar character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\\</span></code> escapes the backslash character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\*</span></code> escapes the star character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\?</span></code> escapes the question mark character (this is not necessary if the <code class="docutils literal notranslate"><span class="pre">qmark-noglob</span></code> <a class="reference internal" href="#featureflags"><span class="std std-ref">feature flag</span></a> is enabled).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\~</span></code> escapes the tilde character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\#</span></code> escapes the hash character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\(</span></code> escapes the left parenthesis character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\)</span></code> escapes the right parenthesis character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\{</span></code> escapes the left curly bracket character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\}</span></code> escapes the right curly bracket character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\[</span></code> escapes the left bracket character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\]</span></code> escapes the right bracket character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\<</span></code> escapes the less than character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\></span></code> escapes the more than character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\&</span></code> escapes the ampersand character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\|</span></code> escapes the vertical bar character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\;</span></code> escapes the semicolon character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\"</span></code> escapes the quote character.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">\'</span></code> escapes the apostrophe character.</p></li>
</ul>
<p>As a special case, <code class="docutils literal notranslate"><span class="pre">\</span></code> immediately followed by a literal new line is a “continuation” and tells fish to ignore the line break and resume input at the start of the next line (without introducing any whitespace or terminating a token).</p>
</section>
<section id="input-output-redirection">
<span id="redirects"></span><h2>Input/Output Redirection<a class="headerlink" href="#input-output-redirection" title="Link to this heading">¶</a></h2>
<p>Most programs use three input/output (I/O) streams:</p>
<ul class="simple">
<li><p>Standard input (stdin) for reading. Defaults to reading from the keyboard.</p></li>
<li><p>Standard output (stdout) for writing output. Defaults to writing to the screen.</p></li>
<li><p>Standard error (stderr) for writing errors and warnings. Defaults to writing to the screen.</p></li>
</ul>
<p>Each stream has a number called the file descriptor (FD): 0 for stdin, 1 for stdout, and 2 for stderr.</p>
<p>The destination of a stream can be changed using something called <em>redirection</em>. For example, <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">hello</span> <span class="pre">></span> <span class="pre">output.txt</span></code>, redirects the standard output of the <code class="docutils literal notranslate"><span class="pre">echo</span></code> command to a text file.</p>
<ul class="simple">
<li><p>To read standard input from a file, use <code class="docutils literal notranslate"><span class="pre"><SOURCE_FILE</span></code>.</p></li>
<li><p>To read standard input from a file or /dev/null if it can’t be read, use <code class="docutils literal notranslate"><span class="pre"><?SOURCE_FILE</span></code>.</p></li>
<li><p>To write standard output to a file, use <code class="docutils literal notranslate"><span class="pre">>DESTINATION</span></code>.</p></li>
<li><p>To write standard error to a file, use <code class="docutils literal notranslate"><span class="pre">2>DESTINATION</span></code>. <a class="footnote-reference brackets" href="#id3" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p></li>
<li><p>To append standard output to a file, use <code class="docutils literal notranslate"><span class="pre">>>DESTINATION_FILE</span></code>.</p></li>
<li><p>To append standard error to a file, use <code class="docutils literal notranslate"><span class="pre">2>>DESTINATION_FILE</span></code>.</p></li>
<li><p>To not overwrite (“clobber”) an existing file, use <code class="docutils literal notranslate"><span class="pre">>?DESTINATION</span></code> or <code class="docutils literal notranslate"><span class="pre">2>?DESTINATION</span></code>. This is known as the “noclobber” redirection.</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">DESTINATION</span></code> can be one of the following:</p>
<ul class="simple">
<li><p>A filename to write the output to. Often <code class="docutils literal notranslate"><span class="pre">>/dev/null</span></code> to silence output by writing it to the special “sinkhole” file.</p></li>
<li><p>An ampersand (<code class="docutils literal notranslate"><span class="pre">&</span></code>) followed by the number of another file descriptor like <code class="docutils literal notranslate"><span class="pre">&2</span></code> for standard error. The output will be written to the destination descriptor.</p></li>
<li><p>An ampersand followed by a minus sign (<code class="docutils literal notranslate"><span class="pre">&-</span></code>). The file descriptor will be closed. Note: This may cause the program to fail because its writes will be unsuccessful.</p></li>
</ul>
<p>As a convenience, the redirection <code class="docutils literal notranslate"><span class="pre">&></span></code> can be used to direct both stdout and stderr to the same destination. For example, <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">hello</span> <span class="pre">&></span> <span class="pre">all_output.txt</span></code> redirects both stdout and stderr to the file <code class="docutils literal notranslate"><span class="pre">all_output.txt</span></code>. This is equivalent to <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">hello</span> <span class="pre">></span> <span class="pre">all_output.txt</span> <span class="pre">2>&1</span></code>. You can also use <code class="docutils literal notranslate"><span class="pre">&>></span></code> to append both stdout and stderr to the same destination.</p>
<p>Any arbitrary file descriptor can be used in a redirection by prefixing the redirection with the FD number.</p>
<ul class="simple">
<li><p>To redirect the input of descriptor N, use <code class="docutils literal notranslate"><span class="pre">N<DESTINATION</span></code>.</p></li>
<li><p>To redirect the output of descriptor N, use <code class="docutils literal notranslate"><span class="pre">N>DESTINATION</span></code>.</p></li>
<li><p>To append the output of descriptor N to a file, use <code class="docutils literal notranslate"><span class="pre">N>>DESTINATION_FILE</span></code>.</p></li>
</ul>
<p>File descriptors cannot be used with a <code class="docutils literal notranslate"><span class="pre"><?</span></code> input redirection, only a regular <code class="docutils literal notranslate"><span class="pre"><</span></code> one.</p>
<p>For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Write `foo`'s standard error (file descriptor 2)</span>
<span class="c"># to a file called "output.stderr":</span>
<span class="nf">foo</span><span class="w"> </span><span class="p">2></span><span class="w"> </span><span class="p">output.stderr</span>
<span class="c"># if $num doesn't contain a number,</span>
<span class="c"># this test will be false and print an error,</span>
<span class="c"># so by ignoring the error we can be sure that we're dealing</span>
<span class="c"># with a number in the "if" block:</span>
<span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="s2">"</span><span class="o">$num</span><span class="s2">"</span><span class="w"> </span><span class="no">-gt</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="p">2>/dev/null</span>
<span class="w"> </span><span class="c"># do things with $num as a number greater than 2</span>
<span class="nf">else</span>
<span class="w"> </span><span class="c"># do things if $num is <= 2 or not a number</span>
<span class="nf">end</span>
<span class="c"># Save `make`s output in a file:</span>
<span class="nf">make</span><span class="w"> </span><span class="p">&>/log</span>
<span class="c"># Redirections stack and can be used with blocks:</span>
<span class="nf">begin</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">stdout</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">stderr</span><span class="w"> </span><span class="p">>&2</span><span class="w"> </span><span class="c"># <- this goes to stderr!</span>
<span class="nf">end</span><span class="w"> </span><span class="p">>/dev/null</span><span class="w"> </span><span class="c"># ignore stdout, so this prints "stderr"</span>
<span class="c"># print all lines that include "foo" from myfile, or nothing if it doesn't exist.</span>
<span class="nf">string</span><span class="w"> </span><span class="no">match</span><span class="w"> </span><span class="s1">'*foo*'</span><span class="w"> </span><span class="p"><?myfile</span>
</pre></div>
</div>
<p>It is an error to redirect a builtin, function, or block to a file descriptor above 2. However this is supported for external commands.</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id3" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">1</a><span class="fn-bracket">]</span></span>
<p>Previous versions of fish also allowed specifying this as <code class="docutils literal notranslate"><span class="pre">^DESTINATION</span></code>, but that made another character special so it was deprecated and removed. See <a class="reference internal" href="#featureflags"><span class="std std-ref">feature flags</span></a>.</p>
</aside>
</aside>
</section>
<section id="piping">
<span id="pipes"></span><h2>Piping<a class="headerlink" href="#piping" title="Link to this heading">¶</a></h2>
<p>Another way to redirect streams is a <em>pipe</em>. A pipe connects streams with each other. Usually the standard output of one command is connected with the standard input of another. This is done by separating commands with the pipe character <code class="docutils literal notranslate"><span class="pre">|</span></code>. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">cat</span><span class="w"> </span><span class="no">foo.txt</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">head</span>
</pre></div>
</div>
<p>The command <code class="docutils literal notranslate"><span class="pre">cat</span> <span class="pre">foo.txt</span></code> sends the contents of <code class="docutils literal notranslate"><span class="pre">foo.txt</span></code> to stdout. This output is provided as input for the <code class="docutils literal notranslate"><span class="pre">head</span></code> program, which prints the first 10 lines of its input.</p>
<p>It is possible to pipe a different output file descriptor by prepending its FD number and the output redirect symbol to the pipe. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">make</span><span class="w"> </span><span class="no">fish</span><span class="w"> </span><span class="p">2>|</span><span class="w"> </span><span class="nf">less</span>
</pre></div>
</div>
<p>will attempt to build <code class="docutils literal notranslate"><span class="pre">fish</span></code>, and any errors will be shown using the <code class="docutils literal notranslate"><span class="pre">less</span></code> pager. <a class="footnote-reference brackets" href="#id5" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p>
<p>As a convenience, the pipe <code class="docutils literal notranslate"><span class="pre">&|</span></code> redirects both stdout and stderr to the same process. This is different from bash, which uses <code class="docutils literal notranslate"><span class="pre">|&</span></code>.</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id5" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id4">2</a><span class="fn-bracket">]</span></span>
<p>A “pager” here is a program that takes output and “paginates” it. <code class="docutils literal notranslate"><span class="pre">less</span></code> doesn’t just do pages, it allows arbitrary scrolling (even back!).</p>
</aside>
</aside>
</section>
<section id="combining-pipes-and-redirections">
<h2>Combining pipes and redirections<a class="headerlink" href="#combining-pipes-and-redirections" title="Link to this heading">¶</a></h2>
<p>It is possible to use multiple redirections and a pipe at the same time. In that case, they are read in this order:</p>
<ol class="arabic simple">
<li><p>First the pipe is set up.</p></li>
<li><p>Then the redirections are evaluated from left-to-right.</p></li>
</ol>
<p>This is important when any redirections reference other file descriptors with the <code class="docutils literal notranslate"><span class="pre">&N</span></code> syntax. When you say <code class="docutils literal notranslate"><span class="pre">>&2</span></code>, that will redirect stdout to where stderr is pointing to <em>at that time</em>.</p>
<p>Consider this helper function:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Make a function that prints something to stdout and stderr</span>
<span class="nf">function</span><span class="w"> </span><span class="no">print</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">out</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">err</span><span class="w"> </span><span class="p">>&2</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>Now let’s see a few cases:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Redirect both stderr and stdout to less</span>
<span class="nf">print</span><span class="w"> </span><span class="p">2>&1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">less</span>
<span class="c"># or</span>
<span class="nf">print</span><span class="w"> </span><span class="p">&|</span><span class="w"> </span><span class="nf">less</span>
<span class="c"># Show the "out" on stderr, silence the "err"</span>
<span class="nf">print</span><span class="w"> </span><span class="p">>&2</span><span class="w"> </span><span class="p">2>/dev/null</span>
<span class="c"># Silence both</span>
<span class="nf">print</span><span class="w"> </span><span class="p">>/dev/null</span><span class="w"> </span><span class="p">2>&1</span>
</pre></div>
</div>
</section>
<section id="job-control">
<span id="syntax-job-control"></span><h2>Job control<a class="headerlink" href="#job-control" title="Link to this heading">¶</a></h2>
<p>When you start a job in fish, fish itself will pause, and give control of the terminal to the program it just started. Sometimes, you want to continue using the commandline, and have the job run in the background. To create a background job, append an <code class="docutils literal notranslate"><span class="pre">&</span></code> (ampersand) to your command. This will tell fish to run the job in the background. Background jobs are very useful when running programs that have a graphical user interface.</p>
<p>Example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">emacs</span><span class="w"> </span><span class="p">&</span>
</pre></div>
</div>
<p>will start the emacs text editor in the background. <a class="reference internal" href="cmds/fg.html"><span class="doc">fg</span></a> can be used to bring it into the foreground again when needed.</p>
<p>Most programs allow you to suspend the program’s execution and return control to fish by pressing <kbd class="kbd docutils literal notranslate">ctrl</kbd>-<kbd class="kbd docutils literal notranslate">z</kbd> (also referred to as <code class="docutils literal notranslate"><span class="pre">^Z</span></code>). Once back at the fish commandline, you can start other programs and do anything you want. If you then want you can go back to the suspended command by using the <a class="reference internal" href="cmds/fg.html"><span class="doc">fg</span></a> (foreground) command.</p>
<p>If you instead want to put a suspended job into the background, use the <a class="reference internal" href="cmds/bg.html"><span class="doc">bg</span></a> command.</p>
<p>To get a listing of all currently started jobs, use the <a class="reference internal" href="cmds/jobs.html"><span class="doc">jobs</span></a> command.
These listed jobs can be removed with the <a class="reference internal" href="cmds/disown.html"><span class="doc">disown</span></a> command.</p>
<p>At the moment, functions cannot be started in the background. Functions that are stopped and then restarted in the background using the <a class="reference internal" href="cmds/bg.html"><span class="doc">bg</span></a> command will not execute correctly.</p>
<p>If the <code class="docutils literal notranslate"><span class="pre">&</span></code> character is followed by a non-separating character, it is not interpreted as background operator. Separating characters are whitespace and the characters <code class="docutils literal notranslate"><span class="pre">;<>&|</span></code>.</p>
</section>
<section id="functions">
<span id="syntax-function"></span><h2>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h2>
<p>Functions are programs written in the fish syntax. They group together various commands and their arguments using a single name.</p>
<p>For example, here’s a simple function to list directories:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">ll</span>
<span class="w"> </span><span class="nf">ls</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="o">$argv</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>The first line tells fish to define a function by the name of <code class="docutils literal notranslate"><span class="pre">ll</span></code>, so it can be used by writing <code class="docutils literal notranslate"><span class="pre">ll</span></code> on the commandline. The second line tells fish that the command <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">-l</span> <span class="pre">$argv</span></code> should be called when <code class="docutils literal notranslate"><span class="pre">ll</span></code> is invoked. <a class="reference internal" href="#variables-argv"><span class="std std-ref">$argv</span></a> is a <a class="reference internal" href="#variables-lists"><span class="std std-ref">list variable</span></a>, which always contains all arguments sent to the function. In the example above, these are passed on to the <code class="docutils literal notranslate"><span class="pre">ls</span></code> command. The <code class="docutils literal notranslate"><span class="pre">end</span></code> on the third line ends the definition.</p>
<p>Calling this as <code class="docutils literal notranslate"><span class="pre">ll</span> <span class="pre">/tmp/</span></code> will end up running <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">-l</span> <span class="pre">/tmp/</span></code>, which will list the contents of /tmp.</p>
<p>This is a kind of function known as an <a class="reference internal" href="#syntax-aliases"><span class="std std-ref">alias</span></a>.</p>
<p>Fish’s prompt is also defined in a function, called <a class="reference internal" href="cmds/fish_prompt.html"><span class="doc">fish_prompt</span></a>. It is run when the prompt is about to be displayed and its output forms the prompt:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">fish_prompt</span>
<span class="w"> </span><span class="c"># A simple prompt. Displays the current directory</span>
<span class="w"> </span><span class="c"># (which fish stores in the $PWD variable)</span>
<span class="w"> </span><span class="c"># and then a user symbol - a '►' for a normal user and a '#' for root.</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">user_char</span><span class="w"> </span><span class="s1">'►'</span>
<span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">fish_is_root_user</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">user_char</span><span class="w"> </span><span class="s1">'#'</span>
<span class="w"> </span><span class="nf">end</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">set_color</span><span class="w"> </span><span class="no">yellow</span><span class="o">)$PWD</span><span class="w"> </span><span class="o">(</span><span class="nf">set_color</span><span class="w"> </span><span class="no">purple</span><span class="o">)$user_char</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>To edit a function, you can use <a class="reference internal" href="cmds/funced.html"><span class="doc">funced</span></a>, and to save a function <a class="reference internal" href="cmds/funcsave.html"><span class="doc">funcsave</span></a>. This will store it in a function file that fish will <a class="reference internal" href="#syntax-function-autoloading"><span class="std std-ref">autoload</span></a> when needed.</p>
<p>The <a class="reference internal" href="cmds/functions.html"><span class="doc">functions</span></a> builtin can show a function’s current definition (and <a class="reference internal" href="cmds/type.html"><span class="doc">type</span></a> will also do if given a function).</p>
<p>For more information on functions, see the documentation for the <a class="reference internal" href="cmds/function.html"><span class="doc">function</span></a> builtin.</p>
<section id="defining-aliases">
<span id="syntax-aliases"></span><h3>Defining aliases<a class="headerlink" href="#defining-aliases" title="Link to this heading">¶</a></h3>
<p>One of the most common uses for functions is to slightly alter the behavior of an already existing command. For example, one might want to redefine the <code class="docutils literal notranslate"><span class="pre">ls</span></code> command to display colors. The switch for turning on colors on GNU systems is <code class="docutils literal notranslate"><span class="pre">--color=auto</span></code>. An alias around <code class="docutils literal notranslate"><span class="pre">ls</span></code> might look like this:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">ls</span>
<span class="w"> </span><span class="nf">command</span><span class="w"> </span><span class="nf">ls</span><span class="w"> </span><span class="no">--color=auto</span><span class="w"> </span><span class="o">$argv</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>There are a few important things that need to be noted about aliases:</p>
<ul class="simple">
<li><p>Always take care to add the <a class="reference internal" href="#variables-argv"><span class="std std-ref">$argv</span></a> variable to the list of parameters to the wrapped command. This makes sure that if the user specifies any additional parameters to the function, they are passed on to the underlying command.</p></li>
<li><p>If the alias has the same name as the aliased command, you need to prefix the call to the program with <code class="docutils literal notranslate"><span class="pre">command</span></code> to tell fish that the function should not call itself, but rather a command with the same name. If you forget to do so, the function would call itself until the end of time. Usually fish is smart enough to figure this out and will refrain from doing so (which is hopefully in your interest).</p></li>
</ul>
<p>To easily create a function of this form, you can use the <a class="reference internal" href="cmds/alias.html"><span class="doc">alias</span></a> command. Unlike other shells, this just makes functions - fish has no separate concept of an “alias”, we just use the word for a simple wrapping function like this. <a class="reference internal" href="cmds/alias.html"><span class="doc">alias</span></a> immediately creates a function. Consider using <code class="docutils literal notranslate"><span class="pre">alias</span> <span class="pre">--save</span></code> or <a class="reference internal" href="cmds/funcsave.html"><span class="doc">funcsave</span></a> to save the created function into an autoload file instead of recreating the alias each time.</p>
<p>For an alternative, try <a class="reference internal" href="interactive.html#abbreviations"><span class="std std-ref">abbreviations</span></a>. These are words that are expanded while you type, instead of being actual functions inside the shell.</p>
</section>
<section id="autoloading-functions">
<span id="syntax-function-autoloading"></span><h3>Autoloading functions<a class="headerlink" href="#autoloading-functions" title="Link to this heading">¶</a></h3>
<p>Functions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. This has some advantages:</p>
<ul class="simple">
<li><p>An autoloaded function becomes available automatically to all running shells.</p></li>
<li><p>If the function definition is changed, all running shells will automatically reload the altered version, after a while.</p></li>
<li><p>Startup time and memory usage is improved, etc.</p></li>
</ul>
<p>When fish needs to load a function, it searches through any directories in the <a class="reference internal" href="#variables-lists"><span class="std std-ref">list variable</span></a> <code class="docutils literal notranslate"><span class="pre">$fish_function_path</span></code> for a file with a name consisting of the name of the function plus the suffix <code class="docutils literal notranslate"><span class="pre">.fish</span></code> and loads the first it finds.</p>
<p>For example if you try to execute something called <code class="docutils literal notranslate"><span class="pre">banana</span></code>, fish will go through all directories in $fish_function_path looking for a file called <code class="docutils literal notranslate"><span class="pre">banana.fish</span></code> and load the first one it finds.</p>
<p>By default <code class="docutils literal notranslate"><span class="pre">$fish_function_path</span></code> contains the following:</p>
<ul class="simple">
<li><p>A directory for users to keep their own functions, usually <code class="docutils literal notranslate"><span class="pre">~/.config/fish/functions</span></code> (controlled by the <code class="docutils literal notranslate"><span class="pre">XDG_CONFIG_HOME</span></code> environment variable).</p></li>
<li><p>A directory for functions for all users on the system, usually <code class="docutils literal notranslate"><span class="pre">/etc/fish/functions</span></code> (really <code class="docutils literal notranslate"><span class="pre">$__fish_sysconfdir/functions</span></code>).</p></li>
<li><p>Directories for other software to put their own functions. These are in the directories under <code class="docutils literal notranslate"><span class="pre">$__fish_user_data_dir</span></code> (usually <code class="docutils literal notranslate"><span class="pre">~/.local/share/fish</span></code>, controlled by the <code class="docutils literal notranslate"><span class="pre">XDG_DATA_HOME</span></code> environment variable) and in the <code class="docutils literal notranslate"><span class="pre">XDG_DATA_DIRS</span></code> environment variable, in a subdirectory called <code class="docutils literal notranslate"><span class="pre">fish/vendor_functions.d</span></code>. The default value for <code class="docutils literal notranslate"><span class="pre">XDG_DATA_DIRS</span></code> is usually <code class="docutils literal notranslate"><span class="pre">/usr/share/fish/vendor_functions.d</span></code> and <code class="docutils literal notranslate"><span class="pre">/usr/local/share/fish/vendor_functions.d</span></code>.</p></li>
</ul>
<p>If you are unsure, your functions probably belong in <code class="docutils literal notranslate"><span class="pre">~/.config/fish/functions</span></code>.</p>
<p>As we’ve explained, autoload files are loaded <em>by name</em>, so, while you can put multiple functions into one file, the file will only be loaded automatically once you try to execute the one that shares the name.</p>
<p>Autoloading also won’t work for <a class="reference internal" href="#event"><span class="std std-ref">event handlers</span></a>, since fish cannot know that a function is supposed to be executed when an event occurs when it hasn’t yet loaded the function. See the <a class="reference internal" href="#event"><span class="std std-ref">event handlers</span></a> section for more information.</p>
<p>If a file of the right name doesn’t define the function, fish will not read other autoload files, instead it will go on to try builtins and finally commands. This allows masking a function defined later in $fish_function_path, e.g. if your administrator has put something into /etc/fish/functions that you want to skip.</p>
<p>If you are developing another program and want to install fish functions for it, install them to the “vendor” functions directory. As this path varies from system to system, you can use <code class="docutils literal notranslate"><span class="pre">pkgconfig</span></code> to discover it with the output of <code class="docutils literal notranslate"><span class="pre">pkg-config</span> <span class="pre">--variable</span> <span class="pre">functionsdir</span> <span class="pre">fish</span></code>. Your installation system should support a custom path to override the pkgconfig path, as other distributors may need to alter it easily.</p>
</section>
</section>
<section id="comments">
<span id="id6"></span><h2>Comments<a class="headerlink" href="#comments" title="Link to this heading">¶</a></h2>
<p>Anything after a <code class="docutils literal notranslate"><span class="pre">#</span></code> until the end of the line is a comment. That means it’s purely for the reader’s benefit, fish ignores it.</p>
<p>This is useful to explain what and why you are doing something:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">ls</span>
<span class="w"> </span><span class="c"># The function is called ls,</span>
<span class="w"> </span><span class="c"># so we have to explicitly call `command ls` to avoid calling ourselves.</span>
<span class="w"> </span><span class="nf">command</span><span class="w"> </span><span class="nf">ls</span><span class="w"> </span><span class="no">--color=auto</span><span class="w"> </span><span class="o">$argv</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>There are no multiline comments. If you want to make a comment span multiple lines, start each line with a <code class="docutils literal notranslate"><span class="pre">#</span></code>.</p>
<p>Comments can also appear after a line like so:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">EDITOR</span><span class="w"> </span><span class="no">emacs</span><span class="w"> </span><span class="c"># I don't like vim.</span>
</pre></div>
</div>
</section>
<section id="conditions">
<span id="syntax-conditional"></span><h2>Conditions<a class="headerlink" href="#conditions" title="Link to this heading">¶</a></h2>
<p>Fish has some builtins that let you execute commands only if a specific criterion is met: <a class="reference internal" href="cmds/if.html"><span class="doc">if</span></a>, <a class="reference internal" href="cmds/switch.html"><span class="doc">switch</span></a>, <a class="reference internal" href="cmds/and.html"><span class="doc">and</span></a> and <a class="reference internal" href="cmds/or.html"><span class="doc">or</span></a>, and also the familiar <a class="reference internal" href="#syntax-combiners"><span class="std std-ref">&&/||</span></a> syntax.</p>
<section id="the-if-statement">
<span id="syntax-if"></span><h3>The <code class="docutils literal notranslate"><span class="pre">if</span></code> statement<a class="headerlink" href="#the-if-statement" title="Link to this heading">¶</a></h3>
<p>The <a class="reference internal" href="cmds/if.html"><span class="doc">if</span></a> statement runs a block of commands if the condition was true.</p>
<p>Like other shells, but unlike typical programming languages you might know, the condition here is a <em>command</em>. Fish runs it, and if it returns a true <a class="reference internal" href="#variables-status"><span class="std std-ref">exit status</span></a> (that’s 0), the if-block is run. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">/etc/os-release</span>
<span class="w"> </span><span class="nf">cat</span><span class="w"> </span><span class="no">/etc/os-release</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>This uses the <a class="reference internal" href="cmds/test.html"><span class="doc">test</span></a> command to see if the file /etc/os-release exists. If it does, it runs <code class="docutils literal notranslate"><span class="pre">cat</span></code>, which prints it on the screen.</p>
<p>Unlike other shells, the condition command ends after the first job, there is no <code class="docutils literal notranslate"><span class="pre">then</span></code> here. Combiners like <code class="docutils literal notranslate"><span class="pre">and</span></code> and <code class="docutils literal notranslate"><span class="pre">or</span></code> extend the condition.</p>
<p>A more complicated example with a <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitution</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="s2">"</span><span class="o">$(</span><span class="nf">uname</span><span class="o">)</span><span class="s2">"</span><span class="w"> </span><span class="no">=</span><span class="w"> </span><span class="no">Linux</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">I</span><span class="w"> </span><span class="no">like</span><span class="w"> </span><span class="no">penguins</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>Because <code class="docutils literal notranslate"><span class="pre">test</span></code> can be used for many different tests, it is important to quote variables and command substitutions. If the <code class="docutils literal notranslate"><span class="pre">$(uname)</span></code> was not quoted, and <code class="docutils literal notranslate"><span class="pre">uname</span></code> printed nothing it would run <code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">=</span> <span class="pre">Linux</span></code>, which is an error.</p>
<p><code class="docutils literal notranslate"><span class="pre">if</span></code> can also take <code class="docutils literal notranslate"><span class="pre">else</span> <span class="pre">if</span></code> clauses with additional conditions and an <a class="reference internal" href="cmds/else.html"><span class="doc">else</span></a> clause that is executed when everything else was false:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="s2">"</span><span class="o">$number</span><span class="s2">"</span><span class="w"> </span><span class="no">-gt</span><span class="w"> </span><span class="no">10</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Your</span><span class="w"> </span><span class="no">number</span><span class="w"> </span><span class="no">was</span><span class="w"> </span><span class="no">greater</span><span class="w"> </span><span class="no">than</span><span class="w"> </span><span class="no">10</span>
<span class="nf">else</span><span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="s2">"</span><span class="o">$number</span><span class="s2">"</span><span class="w"> </span><span class="no">-gt</span><span class="w"> </span><span class="no">5</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Your</span><span class="w"> </span><span class="no">number</span><span class="w"> </span><span class="no">was</span><span class="w"> </span><span class="no">greater</span><span class="w"> </span><span class="no">than</span><span class="w"> </span><span class="no">5</span>
<span class="nf">else</span><span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="s2">"</span><span class="o">$number</span><span class="s2">"</span><span class="w"> </span><span class="no">-gt</span><span class="w"> </span><span class="no">1</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Your</span><span class="w"> </span><span class="no">number</span><span class="w"> </span><span class="no">was</span><span class="w"> </span><span class="no">greater</span><span class="w"> </span><span class="no">than</span><span class="w"> </span><span class="no">1</span>
<span class="nf">else</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Your</span><span class="w"> </span><span class="no">number</span><span class="w"> </span><span class="no">was</span><span class="w"> </span><span class="no">smaller</span><span class="w"> </span><span class="no">or</span><span class="w"> </span><span class="no">equal</span><span class="w"> </span><span class="no">to</span><span class="w"> </span><span class="no">1</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>The <a class="reference internal" href="cmds/not.html"><span class="doc">not</span></a> keyword can be used to invert the status:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Check if the file contains the string "fish" anywhere.</span>
<span class="c"># This executes the `grep` command, which searches for a string,</span>
<span class="c"># and if it finds it returns a status of 0.</span>
<span class="c"># The `not` then turns 0 into 1 or anything else into 0.</span>
<span class="c"># The `-q` switch stops it from printing any matches.</span>
<span class="nf">if</span><span class="w"> </span><span class="o">not</span><span class="w"> </span><span class="nf">grep</span><span class="w"> </span><span class="no">-q</span><span class="w"> </span><span class="no">fish</span><span class="w"> </span><span class="no">myanimals</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"You don't have fish!"</span>
<span class="nf">else</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"You have fish!"</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>Other things commonly used in if-conditions:</p>
<ul class="simple">
<li><p><a class="reference internal" href="cmds/contains.html"><span class="doc">contains</span></a> - to see if a list contains a specific element (<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">contains</span> <span class="pre">--</span> <span class="pre">/usr/bin</span> <span class="pre">$PATH</span></code>)</p></li>
<li><p><a class="reference internal" href="cmds/string.html"><span class="doc">string</span></a> - to e.g. match strings (<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">string</span> <span class="pre">match</span> <span class="pre">-q</span> <span class="pre">--</span> <span class="pre">'*-'</span> <span class="pre">$arg</span></code>)</p></li>
<li><p><a class="reference internal" href="cmds/path.html"><span class="doc">path</span></a> - to check if paths of some criteria exist (<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">path</span> <span class="pre">is</span> <span class="pre">-rf</span> <span class="pre">--</span> <span class="pre">~/.config/fish/config.fish</span></code>)</p></li>
<li><p><a class="reference internal" href="cmds/type.html"><span class="doc">type</span></a> - to see if a command, function or builtin exists (<code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">type</span> <span class="pre">-q</span> <span class="pre">git</span></code>)</p></li>
</ul>
</section>
<section id="the-switch-statement">
<h3>The <code class="docutils literal notranslate"><span class="pre">switch</span></code> statement<a class="headerlink" href="#the-switch-statement" title="Link to this heading">¶</a></h3>
<p>The <a class="reference internal" href="cmds/switch.html"><span class="doc">switch</span></a> command is used to execute one of possibly many blocks of commands depending on the value of a string. It can take multiple <a class="reference internal" href="cmds/case.html"><span class="doc">case</span></a> blocks that are executed when the string matches. They can take <a class="reference internal" href="#expand-wildcard"><span class="std std-ref">wildcards</span></a>. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">switch</span><span class="w"> </span><span class="o">(</span><span class="nf">uname</span><span class="o">)</span>
<span class="nf">case</span><span class="w"> </span><span class="no">Linux</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Hi</span><span class="w"> </span><span class="no">Tux!</span>
<span class="nf">case</span><span class="w"> </span><span class="no">Darwin</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Hi</span><span class="w"> </span><span class="no">Hexley!</span>
<span class="nf">case</span><span class="w"> </span><span class="no">DragonFly</span><span class="w"> </span><span class="s1">'*BSD'</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Hi</span><span class="w"> </span><span class="no">Beastie!</span><span class="w"> </span><span class="c"># this also works for FreeBSD and NetBSD</span>
<span class="nf">case</span><span class="w"> </span><span class="s1">'*'</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Hi,</span><span class="w"> </span><span class="no">stranger!</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>Unlike other shells or programming languages, there is no fallthrough - the first matching <code class="docutils literal notranslate"><span class="pre">case</span></code> block is executed and then control jumps out of the <code class="docutils literal notranslate"><span class="pre">switch</span></code>.</p>
</section>
<section id="combiners-and-or">
<span id="syntax-combiners"></span><h3>Combiners (<code class="docutils literal notranslate"><span class="pre">and</span></code> / <code class="docutils literal notranslate"><span class="pre">or</span></code> / <code class="docutils literal notranslate"><span class="pre">&&</span></code> / <code class="docutils literal notranslate"><span class="pre">||</span></code>)<a class="headerlink" href="#combiners-and-or" title="Link to this heading">¶</a></h3>
<p>For simple checks, you can use combiners. <a class="reference internal" href="cmds/and.html"><span class="doc">and</span></a> or <code class="docutils literal notranslate"><span class="pre">&&</span></code> run the second command if the first succeeded, while <a class="reference internal" href="cmds/or.html"><span class="doc">or</span></a> or <code class="docutils literal notranslate"><span class="pre">||</span></code> run it if the first failed. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># $XDG_CONFIG_HOME is a standard place to store configuration.</span>
<span class="c"># If it's not set applications should use ~/.config.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-q</span><span class="w"> </span><span class="no">XDG_CONFIG_HOME</span><span class="p">;</span><span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">configdir</span><span class="w"> </span><span class="o">$XDG_CONFIG_HOME</span>
<span class="o">or</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">configdir</span><span class="w"> </span><span class="o">~</span><span class="no">/.config</span>
</pre></div>
</div>
<p>Note that combiners are <em>lazy</em> - only the part that is necessary to determine the final status is run.</p>
<p>Compare:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="nf">sleep</span><span class="w"> </span><span class="no">2</span><span class="p">;</span><span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">false</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s1">'How did I get here? This should be impossible'</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>and:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="nf">false</span><span class="p">;</span><span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">sleep</span><span class="w"> </span><span class="no">2</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s1">'How did I get here? This should be impossible'</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>These do essentially the same thing, but the former takes 2 seconds longer because the <code class="docutils literal notranslate"><span class="pre">sleep</span></code> always needs to run.</p>
<p>Or you can have a case where it is necessary to stop early:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="nf">command</span><span class="w"> </span><span class="no">-sq</span><span class="w"> </span><span class="no">foo</span><span class="p">;</span><span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">foo</span>
</pre></div>
</div>
<p>If this went on after seeing that the command “foo” doesn’t exist, it would try to run <code class="docutils literal notranslate"><span class="pre">foo</span></code> and error because it wasn’t found!</p>
<p>Combiners execute step-by-step, so it isn’t recommended to build longer chains of them because they might do something you don’t want. Consider:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">test</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">/etc/my.config</span>
<span class="o">or</span><span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"OH NO WE NEED A CONFIG FILE"</span>
<span class="o">and</span><span class="w"> </span><span class="nf">return</span><span class="w"> </span><span class="no">1</span>
</pre></div>
</div>
<p>This will execute <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">1</span></code> also if the <code class="docutils literal notranslate"><span class="pre">test</span></code> succeeded. This is because fish runs <code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">-e</span> <span class="pre">/etc/my.config</span></code>, sets $status to 0, then skips the <code class="docutils literal notranslate"><span class="pre">echo</span></code>, keeps $status at 0, and then executes the <code class="docutils literal notranslate"><span class="pre">return</span> <span class="pre">1</span></code> because $status is still 0.</p>
<p>So if you have more complex conditions or want to run multiple things after something failed, consider using an <a class="reference internal" href="#syntax-if"><span class="std std-ref">if</span></a>. Here that would be:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">if</span><span class="w"> </span><span class="o">not</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">/etc/my.config</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"OH NO WE NEED A CONFIG FILE"</span>
<span class="w"> </span><span class="nf">return</span><span class="w"> </span><span class="no">1</span>
<span class="nf">end</span>
</pre></div>
</div>
</section>
</section>
<section id="loops-and-blocks">
<span id="syntax-loops-and-blocks"></span><h2>Loops and blocks<a class="headerlink" href="#loops-and-blocks" title="Link to this heading">¶</a></h2>
<p>Like most programming language, fish also has the familiar <a class="reference internal" href="cmds/while.html"><span class="doc">while</span></a> and <a class="reference internal" href="cmds/for.html"><span class="doc">for</span></a> loops.</p>
<p><code class="docutils literal notranslate"><span class="pre">while</span></code> works like a repeated <a class="reference internal" href="#syntax-if"><span class="std std-ref">if</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">while</span><span class="w"> </span><span class="nf">true</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Still</span><span class="w"> </span><span class="no">running</span>
<span class="w"> </span><span class="nf">sleep</span><span class="w"> </span><span class="no">1</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>will print “Still running” once a second. You can abort it with ctrl-c.</p>
<p><code class="docutils literal notranslate"><span class="pre">for</span></code> loops work like in other shells, which is more like python’s for-loops than e.g. C’s:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">for</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">*</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">file:</span><span class="w"> </span><span class="o">$file</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>will print each file in the current directory. The part after the <code class="docutils literal notranslate"><span class="pre">in</span></code> is a list of arguments, so you can use any <a class="reference internal" href="#expand"><span class="std std-ref">expansions</span></a> there:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">moreanimals</span><span class="w"> </span><span class="no">bird</span><span class="w"> </span><span class="no">fox</span>
<span class="nf">for</span><span class="w"> </span><span class="no">animal</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">{</span><span class="no">cat</span><span class="o">,}</span><span class="no">fish</span><span class="w"> </span><span class="no">dog</span><span class="w"> </span><span class="o">$moreanimals</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">I</span><span class="w"> </span><span class="no">like</span><span class="w"> </span><span class="no">the</span><span class="w"> </span><span class="o">$animal</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>If you need a list of numbers, you can use the <code class="docutils literal notranslate"><span class="pre">seq</span></code> command to create one:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">for</span><span class="w"> </span><span class="no">i</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">5</span><span class="o">)</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$i</span>
<span class="nf">end</span>
</pre></div>
</div>
<p><a class="reference internal" href="cmds/break.html"><span class="doc">break</span></a> is available to break out of a loop, and <a class="reference internal" href="cmds/continue.html"><span class="doc">continue</span></a> to jump to the next iteration.</p>
<p><a class="reference internal" href="#redirects"><span class="std std-ref">Input and output redirections</span></a> (including <a class="reference internal" href="#pipes"><span class="std std-ref">pipes</span></a>) can also be applied to loops:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">while</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">line</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">line:</span><span class="w"> </span><span class="o">$line</span>
<span class="nf">end</span><span class="w"> </span><span class="p"><</span><span class="w"> </span><span class="p">file</span>
</pre></div>
</div>
<p>In addition there’s a <a class="reference internal" href="cmds/begin.html"><span class="doc">begin</span></a> block that just groups commands together so you can redirect to a block or use a new <a class="reference internal" href="#variables-scope"><span class="std std-ref">variable scope</span></a> without any repetition:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">begin</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">bar</span><span class="w"> </span><span class="c"># this variable will only be available in this block!</span>
<span class="nf">end</span>
</pre></div>
</div>
</section>
<section id="parameter-expansion">
<span id="expand"></span><h2>Parameter expansion<a class="headerlink" href="#parameter-expansion" title="Link to this heading">¶</a></h2>
<p>When fish is given a commandline, it expands the parameters before sending them to the command. There are multiple different kinds of expansions:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#expand-wildcard"><span class="std std-ref">Wildcards</span></a>, to create filenames from patterns - <code class="docutils literal notranslate"><span class="pre">*.jpg</span></code></p></li>
<li><p><a class="reference internal" href="#expand-variable"><span class="std std-ref">Variable expansion</span></a>, to use the value of a variable - <code class="docutils literal notranslate"><span class="pre">$HOME</span></code></p></li>
<li><p><a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">Command substitution</span></a>, to use the output of another command - <code class="docutils literal notranslate"><span class="pre">$(cat</span> <span class="pre">/path/to/file)</span></code></p></li>
<li><p><a class="reference internal" href="#expand-brace"><span class="std std-ref">Brace expansion</span></a>, to write lists with common pre- or suffixes in a shorter way <code class="docutils literal notranslate"><span class="pre">{/usr,}/bin</span></code></p></li>
<li><p><a class="reference internal" href="#expand-home"><span class="std std-ref">Tilde expansion</span></a>, to turn the <code class="docutils literal notranslate"><span class="pre">~</span></code> at the beginning of paths into the path to the home directory <code class="docutils literal notranslate"><span class="pre">~/bin</span></code></p></li>
</ul>
<p>Parameter expansion is limited to 524288 items. There is a limit to how many arguments the operating system allows for any command, and 524288 is far above it. This is a measure to stop the shell from hanging doing useless computation.</p>
<section id="wildcards-globbing">
<span id="expand-wildcard"></span><h3>Wildcards (“Globbing”)<a class="headerlink" href="#wildcards-globbing" title="Link to this heading">¶</a></h3>
<p>When a parameter includes an <a class="reference internal" href="#quotes"><span class="std std-ref">unquoted</span></a> <code class="docutils literal notranslate"><span class="pre">*</span></code> star (or “asterisk”) or a <code class="docutils literal notranslate"><span class="pre">?</span></code> question mark, fish uses it as a wildcard to match files.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">*</span></code> matches any number of characters (including zero) in a file name, not including <code class="docutils literal notranslate"><span class="pre">/</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">**</span></code> matches any number of characters (including zero), and also descends into subdirectories. If <code class="docutils literal notranslate"><span class="pre">**</span></code> is a segment by itself, that segment may match zero times, for compatibility with other shells.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">?</span></code> can match any single character except <code class="docutils literal notranslate"><span class="pre">/</span></code>. This is deprecated and can be disabled via the <code class="docutils literal notranslate"><span class="pre">qmark-noglob</span></code> <a class="reference internal" href="#featureflags"><span class="std std-ref">feature flag</span></a>, so <code class="docutils literal notranslate"><span class="pre">?</span></code> will be an ordinary character.</p></li>
</ul>
<p>Wildcard matches are sorted case insensitively. When sorting matches containing numbers, they are naturally sorted, so that the strings ‘1’ ‘5’ and ‘12’ would be sorted like 1, 5, 12.</p>
<p>Hidden files (where the name begins with a dot) are not considered when wildcarding unless the wildcard string has a dot in that place.</p>
<p>Examples:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">a*</span></code> matches any files beginning with an ‘a’ in the current directory.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">**</span></code> matches any files and directories in the current directory and all of its subdirectories.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">~/.*</span></code> matches all hidden files (also known as “dotfiles”) and directories in your home directory.</p></li>
</ul>
<p>For most commands, if any wildcard fails to expand, the command is not executed, <a class="reference internal" href="#variables-status"><span class="std std-ref">$status</span></a> is set to nonzero, and a warning is printed. This behavior is like what bash does with <code class="docutils literal notranslate"><span class="pre">shopt</span> <span class="pre">-s</span> <span class="pre">failglob</span></code>. There are exceptions, namely <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a> and <a class="reference internal" href="cmds/path.html"><span class="doc">path</span></a>, overriding variables in <a class="reference internal" href="#variables-override"><span class="std std-ref">overrides</span></a>, <a class="reference internal" href="cmds/count.html"><span class="doc">count</span></a> and <a class="reference internal" href="cmds/for.html"><span class="doc">for</span></a>. Their globs will instead expand to zero arguments (so the command won’t see them at all), like with <code class="docutils literal notranslate"><span class="pre">shopt</span> <span class="pre">-s</span> <span class="pre">nullglob</span></code> in bash.</p>
<p>Examples:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># List the .foo files, or warns if there aren't any.</span>
<span class="nf">ls</span><span class="w"> </span><span class="o">*</span><span class="no">.foo</span>
<span class="c"># List the .foo files, if any.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">foos</span><span class="w"> </span><span class="o">*</span><span class="no">.foo</span>
<span class="nf">if</span><span class="w"> </span><span class="nf">count</span><span class="w"> </span><span class="o">$foos</span><span class="w"> </span><span class="p">>/dev/null</span>
<span class="w"> </span><span class="nf">ls</span><span class="w"> </span><span class="o">$foos</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>Unlike bash (by default), fish will not pass on the literal glob character if no match was found, so for a command like <code class="docutils literal notranslate"><span class="pre">apt</span> <span class="pre">install</span></code> that does the matching itself, you need to add quotes:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">apt</span><span class="w"> </span><span class="no">install</span><span class="w"> </span><span class="s2">"ncurses-*"</span>
</pre></div>
</div>
</section>
<section id="variable-expansion">
<span id="expand-variable"></span><h3>Variable expansion<a class="headerlink" href="#variable-expansion" title="Link to this heading">¶</a></h3>
<p>One of the most important expansions in fish is the “variable expansion”. This is the replacing of a dollar sign (<code class="docutils literal notranslate"><span class="pre">$</span></code>) followed by a variable name with the _value_ of that variable.</p>
<p>A simple example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">$HOME</span>
</pre></div>
</div>
<p>which will replace <code class="docutils literal notranslate"><span class="pre">$HOME</span></code> with the home directory of the current user, and pass it to <a class="reference internal" href="cmds/echo.html"><span class="doc">echo</span></a>, which will then print it.</p>
<p>Some variables like <code class="docutils literal notranslate"><span class="pre">$HOME</span></code> are already set because fish sets them by default or because fish’s parent process passed them to fish when it started it. You can define your own variables by setting them with <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">my_directory</span><span class="w"> </span><span class="no">/home/cooluser/mystuff</span>
<span class="nf">ls</span><span class="w"> </span><span class="o">$my_directory</span>
<span class="c"># shows the contents of /home/cooluser/mystuff</span>
</pre></div>
</div>
<p>For more on how setting variables works, see <a class="reference internal" href="#variables"><span class="std std-ref">Shell variables</span></a> and the following sections.</p>
<p>Sometimes a variable has no value because it is undefined or empty, and it expands to nothing:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">$nonexistentvariable</span>
<span class="c"># Prints no output.</span>
</pre></div>
</div>
<p>To separate a variable name from text you can encase the variable within double-quotes or braces:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">WORD</span><span class="w"> </span><span class="no">cat</span>
<span class="nf">echo</span><span class="w"> </span><span class="no">The</span><span class="w"> </span><span class="no">plural</span><span class="w"> </span><span class="no">of</span><span class="w"> </span><span class="o">$WORD</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="s2">"</span><span class="o">$WORD</span><span class="s2">"</span><span class="no">s</span>
<span class="c"># Prints "The plural of cat is cats" because $WORD is set to "cat".</span>
<span class="nf">echo</span><span class="w"> </span><span class="no">The</span><span class="w"> </span><span class="no">plural</span><span class="w"> </span><span class="no">of</span><span class="w"> </span><span class="o">$WORD</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">{$WORD}</span><span class="no">s</span>
<span class="c"># ditto</span>
</pre></div>
</div>
<p>Without the quotes or braces, fish will try to expand a variable called <code class="docutils literal notranslate"><span class="pre">$WORDs</span></code>, which may not exist.</p>
<p>The latter syntax <code class="docutils literal notranslate"><span class="pre">{$WORD}</span></code> is a special case of <a class="reference internal" href="#expand-brace"><span class="std std-ref">brace expansion</span></a>.</p>
<p>If $WORD here is undefined or an empty list, the “s” is not printed. However, it is printed if $WORD is the empty string (like after <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">WORD</span> <span class="pre">""</span></code>).</p>
<p>For more on shell variables, read the <a class="reference internal" href="#variables"><span class="std std-ref">Shell variables</span></a> section.</p>
<section id="quoting-variables">
<h4>Quoting variables<a class="headerlink" href="#quoting-variables" title="Link to this heading">¶</a></h4>
<p>Variable expansion also happens in double quoted strings. Inside double quotes (<code class="docutils literal notranslate"><span class="pre">"these"</span></code>), variables will always expand to exactly one argument. If they are empty or undefined, it will result in an empty string. If they have one element, they’ll expand to that element. If they have more than that, the elements will be joined with spaces, unless the variable is a <a class="reference internal" href="#variables-path"><span class="std std-ref">path variable</span></a> - in that case it will use a colon (<code class="docutils literal notranslate"><span class="pre">:</span></code>) instead <a class="footnote-reference brackets" href="#id8" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>3<span class="fn-bracket">]</span></a>.</p>
<p>Fish variables are all <a class="reference internal" href="#variables-lists"><span class="std std-ref">lists</span></a>, and they are split into elements when they are <em>set</em> - that means it is important to decide whether to use quotes or not with <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span><span class="w"> </span><span class="c"># a variable with three elements</span>
<span class="nf">rm</span><span class="w"> </span><span class="o">$foo</span><span class="w"> </span><span class="c"># runs the equivalent of `rm 1 2 3` - trying to delete three files: 1, 2 and 3.</span>
<span class="nf">rm</span><span class="w"> </span><span class="s2">"</span><span class="o">$foo</span><span class="s2">"</span><span class="w"> </span><span class="c"># runs `rm '1 2 3'` - trying to delete one file called '1 2 3'</span>
<span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="c"># an empty variable</span>
<span class="nf">rm</span><span class="w"> </span><span class="o">$foo</span><span class="w"> </span><span class="c"># runs `rm` without arguments</span>
<span class="nf">rm</span><span class="w"> </span><span class="s2">"</span><span class="o">$foo</span><span class="s2">"</span><span class="w"> </span><span class="c"># runs the equivalent of `rm ''`</span>
<span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="s2">"1 2 3"</span>
<span class="nf">rm</span><span class="w"> </span><span class="o">$foo</span><span class="w"> </span><span class="c"># runs the equivalent of `rm '1 2 3'` - trying to delete one file</span>
<span class="nf">rm</span><span class="w"> </span><span class="s2">"</span><span class="o">$foo</span><span class="s2">"</span><span class="w"> </span><span class="c"># same thing</span>
</pre></div>
</div>
<p>This is unlike other shells, which do what is known as “Word Splitting”, where they split the variable when it is <em>used</em> in an expansion. E.g. in bash:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nv">foo</span><span class="o">=</span><span class="s2">"1 2 3"</span>
rm<span class="w"> </span><span class="nv">$foo</span><span class="w"> </span><span class="c1"># runs the equivalent of `rm 1 2 3`</span>
rm<span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="c1"># runs the equivalent of `rm '1 2 3'`</span>
</pre></div>
</div>
<p>This is the cause of very common problems with filenames with spaces in bash scripts.</p>
<p>In fish, unquoted variables will expand to as many arguments as they have elements. That means an empty list will expand to nothing, a variable with one element will expand to that element, and a variable with multiple elements will expand to each of those elements separately.</p>
<p>If a variable expands to nothing, it will cancel out any other strings attached to it. See the <a class="reference internal" href="#cartesian-product"><span class="std std-ref">Combining Lists</span></a> section for more information.</p>
<p>Most of the time, not quoting a variable is correct. The exception is when you need to ensure that the variable is passed as one element, even if it might be unset or have multiple elements. This happens often with <a class="reference internal" href="cmds/test.html"><span class="doc">test</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">one</span><span class="w"> </span><span class="no">two</span><span class="w"> </span><span class="no">three</span>
<span class="nf">test</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="o">$foo</span>
<span class="c"># prints an error that it got too many arguments, because it was executed like</span>
<span class="nf">test</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">one</span><span class="w"> </span><span class="no">two</span><span class="w"> </span><span class="no">three</span>
<span class="nf">test</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="s2">"</span><span class="o">$foo</span><span class="s2">"</span>
<span class="c"># works, because it was executed like</span>
<span class="nf">test</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="s2">"one two three"</span>
</pre></div>
</div>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id8" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id7">3</a><span class="fn-bracket">]</span></span>
<p>Unlike bash or zsh, which will join with the first character of $IFS (which usually is space).</p>
</aside>
</aside>
</section>
<section id="dereferencing-variables">
<h4>Dereferencing variables<a class="headerlink" href="#dereferencing-variables" title="Link to this heading">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">$</span></code> symbol can also be used multiple times, as a kind of “dereference” operator (the <code class="docutils literal notranslate"><span class="pre">*</span></code> in C or C++), like in the following code:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">c</span>
<span class="nf">set</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">10</span><span class="p">;</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">20</span><span class="p">;</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">c</span><span class="w"> </span><span class="no">30</span>
<span class="nf">for</span><span class="w"> </span><span class="no">i</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="o">(</span><span class="nf">count</span><span class="w"> </span><span class="o">$$foo))</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$$foo[</span><span class="no">$i</span><span class="o">]</span>
<span class="nf">end</span>
<span class="c"># Output is:</span>
<span class="c"># 10</span>
<span class="c"># 20</span>
<span class="c"># 30</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">$$foo[$i]</span></code> is “the value of the variable named by <code class="docutils literal notranslate"><span class="pre">$foo[$i]</span></code>”.</p>
<p>This can also be used to give a variable name to a function:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">print_var</span>
<span class="w"> </span><span class="nf">for</span><span class="w"> </span><span class="no">arg</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">$argv</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Variable</span><span class="w"> </span><span class="o">$arg</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$$arg</span>
<span class="w"> </span><span class="nf">end</span>
<span class="nf">end</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">bar</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">c</span>
<span class="nf">print_var</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">bar</span>
<span class="c"># prints "Variable foo is 1 2 3" and "Variable bar is a b c"</span>
</pre></div>
</div>
<p>Of course the variable will have to be accessible from the function, so it needs to be <a class="reference internal" href="#variables-scope"><span class="std std-ref">global/universal</span></a> or <a class="reference internal" href="#variables-export"><span class="std std-ref">exported</span></a>. It also can’t clash with a variable name used inside the function. So if we had made $foo there a local variable, or if we had named it “arg” instead, it would not have worked.</p>
<p>When using this feature together with <a class="reference internal" href="#expand-slices"><span class="std std-ref">slices</span></a>, the slices will be used from the inside out. <code class="docutils literal notranslate"><span class="pre">$$foo[5]</span></code> will use the fifth element of <code class="docutils literal notranslate"><span class="pre">$foo</span></code> as a variable name, instead of giving the fifth element of all the variables $foo refers to. That would instead be expressed as <code class="docutils literal notranslate"><span class="pre">$$foo[1..-1][5]</span></code> (take all elements of <code class="docutils literal notranslate"><span class="pre">$foo</span></code>, use them as variable names, then give the fifth element of those).</p>
<p>Some more examples:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">listone</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span>
<span class="nf">set</span><span class="w"> </span><span class="no">listtwo</span><span class="w"> </span><span class="no">4</span><span class="w"> </span><span class="no">5</span><span class="w"> </span><span class="no">6</span>
<span class="nf">set</span><span class="w"> </span><span class="no">var</span><span class="w"> </span><span class="no">listone</span><span class="w"> </span><span class="no">listtwo</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$$var</span>
<span class="c"># Output is 1 2 3 4 5 6</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$$var[</span><span class="no">1</span><span class="o">]</span>
<span class="c"># Output is 1 2 3</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$$var[</span><span class="no">2</span><span class="o">][</span><span class="no">3</span><span class="o">]</span>
<span class="c"># $var[2] is listtwo, third element of that is 6, output is 6</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$$var[</span><span class="no">..</span><span class="o">][</span><span class="no">2</span><span class="o">]</span>
<span class="c"># The second element of every variable, so output is 2 5</span>
</pre></div>
</div>
</section>
<section id="variables-as-command">
<h4>Variables as command<a class="headerlink" href="#variables-as-command" title="Link to this heading">¶</a></h4>
<p>Like other shells, you can run the value of a variable as a command.</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">EDITOR</span><span class="w"> </span><span class="no">emacs</span>
<span class="gp">> </span><span class="o">$EDITOR</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="c"># opens emacs, possibly the GUI version</span>
</pre></div>
</div>
<p>If you want to give the command an argument inside the variable it needs to be a separate element:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">EDITOR</span><span class="w"> </span><span class="no">emacs</span><span class="w"> </span><span class="no">-nw</span>
<span class="gp">> </span><span class="o">$EDITOR</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="c"># opens emacs in the terminal even if the GUI is installed</span>
<span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">EDITOR</span><span class="w"> </span><span class="s2">"emacs -nw"</span>
<span class="gp">> </span><span class="o">$EDITOR</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="c"># tries to find a command called "emacs -nw"</span>
</pre></div>
</div>
<p>Also like other shells, this only works with commands, builtins and functions - it will not work with keywords because they have syntactical importance.</p>
<p>For instance <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">if</span> <span class="pre">$if</span></code> won’t allow you to make an if-block, and <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">cmd</span> <span class="pre">command</span></code> won’t allow you to use the <a class="reference internal" href="cmds/command.html"><span class="doc">command</span></a> decorator, but only uses like <code class="docutils literal notranslate"><span class="pre">$cmd</span> <span class="pre">-q</span> <span class="pre">foo</span></code>.</p>
</section>
</section>
<section id="command-substitution">
<span id="expand-command-substitution"></span><h3>Command substitution<a class="headerlink" href="#command-substitution" title="Link to this heading">¶</a></h3>
<p>A <code class="docutils literal notranslate"><span class="pre">command</span> <span class="pre">substitution</span></code> is an expansion that uses the <em>output</em> of a command as the arguments to another. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">$(</span><span class="nf">pwd</span><span class="o">)</span>
</pre></div>
</div>
<p>This executes the <a class="reference internal" href="cmds/pwd.html"><span class="doc">pwd</span></a> command, takes its output (more specifically what it wrote to the standard output “stdout” stream) and uses it as arguments to <a class="reference internal" href="cmds/echo.html"><span class="doc">echo</span></a>. So the inner command (the <code class="docutils literal notranslate"><span class="pre">pwd</span></code>) is run first and has to complete before the outer command can even be started.</p>
<p>If the inner command prints multiple lines, fish will use each separate line as a separate argument to the outer command. Unlike other shells, the value of <code class="docutils literal notranslate"><span class="pre">$IFS</span></code> is not used <a class="footnote-reference brackets" href="#id10" id="id9" role="doc-noteref"><span class="fn-bracket">[</span>4<span class="fn-bracket">]</span></a>, fish splits on newlines.</p>
<p>Command substitutions can also be double-quoted:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="s2">"</span><span class="o">$(</span><span class="nf">pwd</span><span class="o">)</span><span class="s2">"</span>
</pre></div>
</div>
<p>When using double quotes, the command output is not split up by lines, but trailing empty lines are still removed.</p>
<p>If the output is piped to <a class="reference internal" href="cmds/string-split.html"><span class="doc">string split or string split0</span></a> as the last step, those splits are used as they appear instead of splitting lines.</p>
<p>Fish also allows spelling command substitutions without the dollar, like <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">(pwd)</span></code>. This variant will not be expanded in double-quotes (<code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">"(pwd)"</span></code> will print <code class="docutils literal notranslate"><span class="pre">(pwd)</span></code>).</p>
<p>The exit status of the last run command substitution is available in the <a class="reference internal" href="#variables-status"><span class="std std-ref">status</span></a> variable if the substitution happens in the context of a <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a> command (so <code class="docutils literal notranslate"><span class="pre">if</span> <span class="pre">set</span> <span class="pre">-l</span> <span class="pre">(something)</span></code> checks if <code class="docutils literal notranslate"><span class="pre">something</span></code> returned true).</p>
<p>To use only some lines of the output, refer to <a class="reference internal" href="#expand-slices"><span class="std std-ref">slices</span></a>.</p>
<p>Examples:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Outputs 'image.png'.</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">basename</span><span class="w"> </span><span class="no">image.jpg</span><span class="w"> </span><span class="no">.jpg</span><span class="o">)</span><span class="no">.png</span>
<span class="c"># Convert all JPEG files in the current directory to the</span>
<span class="c"># PNG format using the 'convert' program.</span>
<span class="nf">for</span><span class="w"> </span><span class="no">i</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">*</span><span class="no">.jpg</span><span class="p">;</span><span class="w"> </span><span class="nf">convert</span><span class="w"> </span><span class="o">$i</span><span class="w"> </span><span class="o">(</span><span class="nf">basename</span><span class="w"> </span><span class="o">$i</span><span class="w"> </span><span class="no">.jpg</span><span class="o">)</span><span class="no">.png</span><span class="p">;</span><span class="w"> </span><span class="nf">end</span>
<span class="c"># Set the ``data`` variable to the contents of 'data.txt'</span>
<span class="c"># without splitting it into a list.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">data</span><span class="w"> </span><span class="s2">"</span><span class="o">$(</span><span class="nf">cat</span><span class="w"> </span><span class="no">data.txt</span><span class="o">)</span><span class="s2">"</span>
<span class="c"># Set ``$data`` to the contents of data, splitting on NUL-bytes.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">data</span><span class="w"> </span><span class="o">(</span><span class="nf">cat</span><span class="w"> </span><span class="no">data</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">string</span><span class="w"> </span><span class="no">split0</span><span class="o">)</span>
</pre></div>
</div>
<p>Sometimes you want to pass the output of a command to another command that only accepts files. If it’s just one file, you can usually pass it via a pipe, like:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">grep</span><span class="w"> </span><span class="no">fish</span><span class="w"> </span><span class="no">myanimallist1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">wc</span><span class="w"> </span><span class="no">-l</span>
</pre></div>
</div>
<p>but if you need multiple or the command doesn’t read from standard input, “process substitution” is useful. Other shells allow this via <code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre"><(bar)</span> <span class="pre"><(baz)</span></code>, and fish uses the <a class="reference internal" href="cmds/psub.html"><span class="doc">psub</span></a> command:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Compare only the lines containing "fish" in two files:</span>
<span class="nf">diff</span><span class="w"> </span><span class="no">-u</span><span class="w"> </span><span class="o">(</span><span class="nf">grep</span><span class="w"> </span><span class="no">fish</span><span class="w"> </span><span class="no">myanimallist1</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">psub</span><span class="o">)</span><span class="w"> </span><span class="o">(</span><span class="nf">grep</span><span class="w"> </span><span class="no">fish</span><span class="w"> </span><span class="no">myanimallist2</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">psub</span><span class="o">)</span>
</pre></div>
</div>
<p>This creates a temporary file, stores the output of the command in that file and prints the filename, so it is given to the outer command.</p>
<p>Fish has a default limit of 1 GiB on the data it will read in a command substitution. If that limit is reached the command (all of it, not just the command substitution - the outer command won’t be executed at all) fails and <code class="docutils literal notranslate"><span class="pre">$status</span></code> is set to 122. This is so command substitutions can’t cause the system to go out of memory, because typically your operating system has a much lower limit, so reading more than that would be useless and harmful. This limit can be adjusted with the <code class="docutils literal notranslate"><span class="pre">fish_read_limit</span></code> variable (<cite>0</cite> meaning no limit). This limit also affects the <a class="reference internal" href="cmds/read.html"><span class="doc">read</span></a> command.</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id10" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id9">4</a><span class="fn-bracket">]</span></span>
<p>One exception: Setting <code class="docutils literal notranslate"><span class="pre">$IFS</span></code> to empty will disable line splitting. This is deprecated, use <a class="reference internal" href="cmds/string-split.html"><span class="doc">string split</span></a> instead.</p>
</aside>
</aside>
</section>
<section id="brace-expansion">
<span id="expand-brace"></span><h3>Brace expansion<a class="headerlink" href="#brace-expansion" title="Link to this heading">¶</a></h3>
<p>Curly braces can be used to write comma-separated lists. They will be expanded with each element becoming a new parameter, with the surrounding string attached. This is useful to save on typing, and to separate a variable name from surrounding text.</p>
<p>Examples:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="no">input.</span><span class="o">{</span><span class="no">c</span><span class="o">,</span><span class="no">h</span><span class="o">,</span><span class="no">txt</span><span class="o">}</span>
<span class="go">input.c input.h input.txt</span>
<span class="go"># Move all files with the suffix '.c' or '.h' to the subdirectory src.</span>
<span class="gp">> </span><span class="nf">mv</span><span class="w"> </span><span class="o">*</span><span class="no">.</span><span class="o">{</span><span class="no">c</span><span class="o">,</span><span class="no">h</span><span class="o">}</span><span class="w"> </span><span class="no">src/</span>
<span class="go"># Make a copy of `file` at `file.bak`.</span>
<span class="gp">> </span><span class="nf">cp</span><span class="w"> </span><span class="no">file</span><span class="o">{,</span><span class="no">.bak</span><span class="o">}</span>
<span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">dogs</span><span class="w"> </span><span class="no">hot</span><span class="w"> </span><span class="no">cool</span><span class="w"> </span><span class="no">cute</span><span class="w"> </span><span class="s2">"good "</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">{$dogs}</span><span class="no">dog</span>
<span class="go">hotdog cooldog cutedog good dog</span>
</pre></div>
</div>
<p>If there is no “,” or variable expansion between the curly braces, they will not be expanded:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="go"># This {} isn't special</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="no">foo-</span><span class="o">{}</span>
<span class="go">foo-{}</span>
<span class="go"># This passes "HEAD@{2}" to git</span>
<span class="gp">> </span><span class="nf">git</span><span class="w"> </span><span class="no">reset</span><span class="w"> </span><span class="no">--hard</span><span class="w"> </span><span class="no">HEAD@</span><span class="o">{</span><span class="no">2</span><span class="o">}</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">{{</span><span class="no">a</span><span class="o">,</span><span class="no">b</span><span class="o">}}</span>
<span class="go">{a} {b} # because the inner brace pair is expanded, but the outer isn't.</span>
</pre></div>
</div>
<p>If after expansion there is nothing between the braces, the argument will be removed (see <a class="reference internal" href="#cartesian-product"><span class="std std-ref">the Combining Lists</span></a> section):</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="no">foo-</span><span class="o">{$undefinedvar}</span>
<span class="go"># Output is an empty line, like a bare `echo`.</span>
</pre></div>
</div>
<p>If there is nothing between a brace and a comma or two commas, it’s interpreted as an empty element:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">{,,</span><span class="no">/usr</span><span class="o">}</span><span class="no">/bin</span>
<span class="go">/bin /bin /usr/bin</span>
</pre></div>
</div>
<p>To use a “,” as an element, <a class="reference internal" href="#quotes"><span class="std std-ref">quote</span></a> or <a class="reference internal" href="#escapes"><span class="std std-ref">escape</span></a> it.</p>
<p>The very first character of a command token is never interpreted as expanding brace, because it’s the beginning of a <a class="reference internal" href="cmds/begin.html"><span class="doc">compound statement</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">{echo</span><span class="w"> </span><span class="no">hello,</span><span class="w"> </span><span class="o">&&</span><span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">world</span><span class="nf">}</span>
<span class="go">hello,</span>
<span class="go">world</span>
</pre></div>
</div>
</section>
<section id="combining-lists">
<span id="cartesian-product"></span><h3>Combining lists<a class="headerlink" href="#combining-lists" title="Link to this heading">¶</a></h3>
<p>Fish expands lists like <a class="reference internal" href="#expand-brace"><span class="std std-ref">brace expansions</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">x</span><span class="w"> </span><span class="no">y</span><span class="w"> </span><span class="no">z</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="no">1</span><span class="o">$foo</span>
<span class="go"># Any element of $foo is combined with the "1":</span>
<span class="go">1x 1y 1z</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">{</span><span class="no">good</span><span class="o">,</span><span class="no">bad</span><span class="o">}</span><span class="s2">" apples"</span>
<span class="go"># Any element of the {} is combined with the " apples":</span>
<span class="go">good apples bad apples</span>
<span class="go"># Or we can mix the two:</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">{</span><span class="no">good</span><span class="o">,</span><span class="no">bad</span><span class="o">}</span><span class="s2">" "</span><span class="o">$foo</span>
<span class="go">good x bad x good y bad y good z bad z</span>
</pre></div>
</div>
<p>Any string attached to a list will be concatenated to each element.</p>
<p>Two lists will be expanded in all combinations - every element of the first with every element of the second:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">x</span><span class="w"> </span><span class="no">y</span><span class="w"> </span><span class="no">z</span><span class="p">;</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">$a$b</span><span class="w"> </span><span class="c"># same as {x,y,z}{1,2,3}</span>
<span class="go">x1 y1 z1 x2 y2 z2 x3 y3 z3</span>
</pre></div>
</div>
<p>A result of this is that, if a list has no elements, this combines the string with no elements, which means the entire token is removed!</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">c</span><span class="w"> </span><span class="c"># <- this list is empty!</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">{$c}</span><span class="no">word</span>
<span class="go"># Output is an empty line - the "word" part is gone</span>
</pre></div>
</div>
<p>This can be quite useful. For example, if you want to go through all the files in all the directories in <span class="target" id="index-1"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>, use</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">for</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">$PATH</span><span class="no">/</span><span class="o">*</span>
</pre></div>
</div>
<p>Because <span class="target" id="index-2"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a> is a list, this expands to all the files in all the directories in it. And if there are no directories in <span class="target" id="index-3"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>, the right answer here is to expand to no files.</p>
<p>Sometimes this may be unwanted, especially that tokens can disappear after expansion. In those cases, you should double-quote variables - <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">"$c"word</span></code>.</p>
<p>This also happens after <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitution</span></a>. To avoid tokens disappearing there, make the inner command return a trailing newline, or double-quote it:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">>_ </span><span class="nf">set</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">echo</span><span class="w"> </span><span class="no">x</span><span class="o">)$b</span>
<span class="go">x1 x2 x3</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">printf</span><span class="w"> </span><span class="s1">'%s'</span><span class="w"> </span><span class="s1">''</span><span class="o">)</span><span class="no">banana</span>
<span class="go"># the printf prints nothing, so this is nothing times "banana",</span>
<span class="go"># which is nothing.</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">printf</span><span class="w"> </span><span class="s1">'%s\n'</span><span class="w"> </span><span class="s1">''</span><span class="o">)</span><span class="no">banana</span>
<span class="go"># the printf prints a newline,</span>
<span class="go"># so the command substitution expands to an empty string,</span>
<span class="go"># so this is `''banana`</span>
<span class="go">banana</span>
<span class="gp">>_ </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"</span><span class="o">$(</span><span class="nf">printf</span><span class="w"> </span><span class="s1">'%s'</span><span class="w"> </span><span class="s1">''</span><span class="o">)</span><span class="s2">"</span><span class="no">banana</span>
<span class="go"># quotes mean this is one argument, the banana stays</span>
</pre></div>
</div>
</section>
<section id="slices">
<span id="expand-slices"></span><h3>Slices<a class="headerlink" href="#slices" title="Link to this heading">¶</a></h3>
<p>Sometimes it’s necessary to access only some of the elements of a <a class="reference internal" href="#variables-lists"><span class="std std-ref">list</span></a> (all fish variables are lists), or some of the lines a <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitution</span></a> outputs. Both are possible in fish by writing a set of indices in brackets, like:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Make $var a list of four elements</span>
<span class="nf">set</span><span class="w"> </span><span class="no">var</span><span class="w"> </span><span class="no">one</span><span class="w"> </span><span class="no">two</span><span class="w"> </span><span class="no">three</span><span class="w"> </span><span class="no">four</span>
<span class="c"># Print the second:</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$var[</span><span class="no">2</span><span class="o">]</span>
<span class="c"># prints "two"</span>
<span class="c"># or print the first three:</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$var[</span><span class="no">1..3</span><span class="o">]</span>
<span class="c"># prints "one two three"</span>
</pre></div>
</div>
<p>In index brackets, fish understands ranges written like <code class="docutils literal notranslate"><span class="pre">a..b</span></code> (‘a’ and ‘b’ being indices). They are expanded into a sequence of indices from a to b (so <code class="docutils literal notranslate"><span class="pre">a</span> <span class="pre">a+1</span> <span class="pre">a+2</span> <span class="pre">...</span> <span class="pre">b</span></code>), going up if b is larger and going down if a is larger. Negative indices can also be used - they are taken from the end of the list, so <code class="docutils literal notranslate"><span class="pre">-1</span></code> is the last element, and <code class="docutils literal notranslate"><span class="pre">-2</span></code> the one before it. If an index doesn’t exist the range is clamped to the next possible index.</p>
<p>If a list has 5 elements the indices go from 1 to 5, so a range of <code class="docutils literal notranslate"><span class="pre">2..16</span></code> will only go from element 2 to element 5.</p>
<p>If the end is negative the range always goes up, so <code class="docutils literal notranslate"><span class="pre">2..-2</span></code> will go from element 2 to 4, and <code class="docutils literal notranslate"><span class="pre">2..-16</span></code> won’t go anywhere because there is no way to go from the second element to one that doesn’t exist, while going up.
If the start is negative the range always goes down, so <code class="docutils literal notranslate"><span class="pre">-2..1</span></code> will go from element 4 to 1, and <code class="docutils literal notranslate"><span class="pre">-16..2</span></code> won’t go anywhere because there is no way to go from an element that doesn’t exist to the second element, while going down.</p>
<p>A missing starting index in a range defaults to 1. This is allowed if the range is the first index expression of the sequence. Similarly, a missing ending index, defaulting to -1 is allowed for the last index in the sequence.</p>
<p>Multiple ranges are also possible, separated with a space.</p>
<p>Some examples:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">10</span><span class="o">)</span><span class="no">[1 2 3]</span>
<span class="c"># Prints: 1 2 3</span>
<span class="c"># Limit the command substitution output</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">10</span><span class="o">)</span><span class="no">[2..5]</span>
<span class="c"># Uses elements from 2 to 5</span>
<span class="c"># Output is: 2 3 4 5</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">10</span><span class="o">)</span><span class="no">[7..]</span>
<span class="c"># Prints: 7 8 9 10</span>
<span class="c"># Use overlapping ranges:</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">10</span><span class="o">)</span><span class="no">[2..5 1..3]</span>
<span class="c"># Takes elements from 2 to 5 and then elements from 1 to 3</span>
<span class="c"># Output is: 2 3 4 5 1 2 3</span>
<span class="c"># Reverse output</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">10</span><span class="o">)</span><span class="no">[-1..1]</span>
<span class="c"># Uses elements from the last output line to</span>
<span class="c"># the first one in reverse direction</span>
<span class="c"># Output is: 10 9 8 7 6 5 4 3 2 1</span>
<span class="c"># The command substitution has only one line,</span>
<span class="c"># so these will result in empty output:</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">echo</span><span class="w"> </span><span class="no">one</span><span class="o">)</span><span class="no">[2..-1]</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">echo</span><span class="w"> </span><span class="no">one</span><span class="o">)</span><span class="no">[-3..1]</span>
</pre></div>
</div>
<p>The same works when setting or expanding variables:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Reverse path variable</span>
<span class="nf">set</span><span class="w"> </span><span class="no">PATH</span><span class="w"> </span><span class="o">$PATH[</span><span class="no">-1..1</span><span class="o">]</span>
<span class="c"># or</span>
<span class="nf">set</span><span class="w"> </span><span class="no">PATH[-1..1]</span><span class="w"> </span><span class="o">$PATH</span>
<span class="c"># Use only n last items of the PATH</span>
<span class="nf">set</span><span class="w"> </span><span class="no">n</span><span class="w"> </span><span class="no">-3</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$PATH[</span><span class="no">$n..-1</span><span class="o">]</span>
</pre></div>
</div>
<p>Variables can be used as indices for expansion of variables, like so:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">index</span><span class="w"> </span><span class="no">2</span>
<span class="nf">set</span><span class="w"> </span><span class="no">letters</span><span class="w"> </span><span class="no">a</span><span class="w"> </span><span class="no">b</span><span class="w"> </span><span class="no">c</span><span class="w"> </span><span class="no">d</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$letters[</span><span class="no">$index</span><span class="o">]</span><span class="w"> </span><span class="c"># returns 'b'</span>
</pre></div>
</div>
<p>However using variables as indices for command substitution is currently not supported, so:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">5</span><span class="o">)</span><span class="no">[</span><span class="o">$index</span><span class="no">]</span><span class="w"> </span><span class="c"># This won't work</span>
<span class="nf">set</span><span class="w"> </span><span class="no">sequence</span><span class="w"> </span><span class="o">(</span><span class="nf">seq</span><span class="w"> </span><span class="no">5</span><span class="o">)</span><span class="w"> </span><span class="c"># It needs to be written on two lines like this.</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$sequence[</span><span class="no">$index</span><span class="o">]</span><span class="w"> </span><span class="c"># returns '2'</span>
</pre></div>
</div>
<p>When using indirect variable expansion with multiple <code class="docutils literal notranslate"><span class="pre">$</span></code> (<code class="docutils literal notranslate"><span class="pre">$$name</span></code>), you have to give all indices up to the variable you want to slice:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">list</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span><span class="w"> </span><span class="no">4</span><span class="w"> </span><span class="no">5</span>
<span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">name</span><span class="w"> </span><span class="no">list</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$$name[</span><span class="no">1</span><span class="o">]</span>
<span class="go">1 2 3 4 5</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$$name[</span><span class="no">1..-1</span><span class="o">][</span><span class="no">1..3</span><span class="o">]</span><span class="w"> </span><span class="c"># or $$name[1][1..3], since $name only has one element.</span>
<span class="go">1 2 3</span>
</pre></div>
</div>
</section>
<section id="home-directory-expansion">
<span id="expand-home"></span><h3>Home directory expansion<a class="headerlink" href="#home-directory-expansion" title="Link to this heading">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">~</span></code> (tilde) character at the beginning of a parameter, followed by a username, is expanded into the home directory of the specified user. A lone <code class="docutils literal notranslate"><span class="pre">~</span></code>, or a <code class="docutils literal notranslate"><span class="pre">~</span></code> followed by a slash, is expanded into the home directory of the process owner:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">ls</span><span class="w"> </span><span class="o">~</span><span class="no">/Music</span><span class="w"> </span><span class="c"># lists my music directory</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">~</span><span class="no">root</span><span class="w"> </span><span class="c"># prints root's home directory, probably "/root"</span>
</pre></div>
</div>
</section>
<section id="combining-different-expansions">
<h3>Combining different expansions<a class="headerlink" href="#combining-different-expansions" title="Link to this heading">¶</a></h3>
<p>All of the above expansions can be combined. If several expansions result in more than one parameter, all possible combinations are created.</p>
<p>When combining multiple parameter expansions, expansions are performed in the following order:</p>
<ul class="simple">
<li><p>Command substitutions</p></li>
<li><p>Variable expansions</p></li>
<li><p>Bracket expansion</p></li>
<li><p>Wildcard expansion</p></li>
</ul>
<p>Expansions are performed from right to left, nested bracket expansions and command substitutions are performed from the inside and out.</p>
<p>Example:</p>
<p>If the current directory contains the files ‘foo’ and ‘bar’, the command <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">a(ls){1,2,3}</span></code> will output <code class="docutils literal notranslate"><span class="pre">abar1</span> <span class="pre">abar2</span> <span class="pre">abar3</span> <span class="pre">afoo1</span> <span class="pre">afoo2</span> <span class="pre">afoo3</span></code>.</p>
</section>
</section>
<section id="table-of-operators">
<h2>Table Of Operators<a class="headerlink" href="#table-of-operators" title="Link to this heading">¶</a></h2>
<p>Putting it together, here is a quick reference to fish’s operators, all of the special symbols it uses:</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Symbol</p></th>
<th class="head"><p>Meaning</p></th>
<th class="head"><p>Example</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">$</span></code></p></td>
<td><p><a class="reference internal" href="#expand-variable"><span class="std std-ref">Variable expansion</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">$foo</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">$()</span></code> and <code class="docutils literal notranslate"><span class="pre">()</span></code></p></td>
<td><p><a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">Command substitution</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cat</span> <span class="pre">(grep</span> <span class="pre">foo</span> <span class="pre">bar)</span></code> or <code class="docutils literal notranslate"><span class="pre">cat</span> <span class="pre">$(grep</span> <span class="pre">foo</span> <span class="pre">bar)</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre"><</span></code> and <code class="docutils literal notranslate"><span class="pre">></span></code></p></td>
<td><p><a class="reference internal" href="#redirects"><span class="std std-ref">Redirection</span></a>, like <code class="docutils literal notranslate"><span class="pre">command</span> <span class="pre">></span> <span class="pre">file</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">shortlog</span> <span class="pre">-nse</span> <span class="pre">.</span> <span class="pre">></span> <span class="pre">authors</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">|</span></code></p></td>
<td><p><a class="reference internal" href="#pipes"><span class="std std-ref">Pipe</span></a>, connect two or more commands</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre">|</span> <span class="pre">grep</span> <span class="pre">bar</span> <span class="pre">|</span> <span class="pre">grep</span> <span class="pre">baz</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">;</span></code></p></td>
<td><p>End of the command, instead of a newline</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">command1;</span> <span class="pre">command2</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">&</span></code></p></td>
<td><p><a class="reference internal" href="#syntax-job-control"><span class="std std-ref">Backgrounding</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">sleep</span> <span class="pre">5m</span> <span class="pre">&</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">{}</span></code></p></td>
<td><p><a class="reference internal" href="#expand-brace"><span class="std std-ref">Brace expansion</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">{/usr,}/bin</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">&&</span></code> and <code class="docutils literal notranslate"><span class="pre">||</span></code></p></td>
<td><p><a class="reference internal" href="#syntax-combiners"><span class="std std-ref">Combiners</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">mkdir</span> <span class="pre">foo</span> <span class="pre">&&</span> <span class="pre">cd</span> <span class="pre">foo</span></code> or <code class="docutils literal notranslate"><span class="pre">rm</span> <span class="pre">foo</span> <span class="pre">||</span> <span class="pre">exit</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">*</span></code> and <code class="docutils literal notranslate"><span class="pre">**</span></code></p></td>
<td><p><a class="reference internal" href="#expand-wildcard"><span class="std std-ref">Wildcards</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">cat</span> <span class="pre">*.fish</span></code> or <code class="docutils literal notranslate"><span class="pre">count</span> <span class="pre">**.jpg</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">\\</span></code></p></td>
<td><p><a class="reference internal" href="#escapes"><span class="std std-ref">Escaping</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">foo\nbar</span></code> or <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">\$foo</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">''</span></code> and <code class="docutils literal notranslate"><span class="pre">""</span></code></p></td>
<td><p><a class="reference internal" href="#quotes"><span class="std std-ref">Quoting</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">rm</span> <span class="pre">"file</span> <span class="pre">with</span> <span class="pre">spaces"</span></code> or <code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">'$foo'</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">~</span></code></p></td>
<td><p><a class="reference internal" href="#expand-home"><span class="std std-ref">Home directory expansion</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">~/</span></code> or <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">~root/</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">#</span></code></p></td>
<td><p><a class="reference internal" href="#comments"><span class="std std-ref">Comments</span></a></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">echo</span> <span class="pre">Hello</span> <span class="pre">#</span> <span class="pre">this</span> <span class="pre">isn't</span> <span class="pre">printed</span></code></p></td>
</tr>
</tbody>
</table>
</section>
<section id="shell-variables">
<span id="variables"></span><h2>Shell variables<a class="headerlink" href="#shell-variables" title="Link to this heading">¶</a></h2>
<p>Variables are a way to save data and pass it around. They can be used just by the shell, or they can be “<a class="reference internal" href="#variables-export"><span class="std std-ref">exported</span></a>”, so that a copy of the variable is available to any external command the shell starts. An exported variable is referred to as an “environment variable”.</p>
<p>To set a variable value, use the <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a> command. A variable name can not be empty and can contain only letters, digits, and underscores. It may begin and end with any of those characters.</p>
<p>Example:</p>
<p>To set the variable <code class="docutils literal notranslate"><span class="pre">smurf_color</span></code> to the value <code class="docutils literal notranslate"><span class="pre">blue</span></code>, use the command <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">smurf_color</span> <span class="pre">blue</span></code>.</p>
<p>After a variable has been set, you can use the value of a variable in the shell through <a class="reference internal" href="#expand-variable"><span class="std std-ref">variable expansion</span></a>.</p>
<p>Example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">smurf_color</span><span class="w"> </span><span class="no">blue</span>
<span class="nf">echo</span><span class="w"> </span><span class="no">Smurfs</span><span class="w"> </span><span class="no">are</span><span class="w"> </span><span class="no">usually</span><span class="w"> </span><span class="o">$smurf_color</span>
<span class="nf">set</span><span class="w"> </span><span class="no">pants_color</span><span class="w"> </span><span class="no">red</span>
<span class="nf">echo</span><span class="w"> </span><span class="no">Papa</span><span class="w"> </span><span class="no">smurf,</span><span class="w"> </span><span class="no">who</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$smurf_color</span><span class="no">,</span><span class="w"> </span><span class="no">wears</span><span class="w"> </span><span class="o">$pants_color</span><span class="w"> </span><span class="no">pants</span>
</pre></div>
</div>
<p>So you set a variable with <code class="docutils literal notranslate"><span class="pre">set</span></code>, and use it with a <code class="docutils literal notranslate"><span class="pre">$</span></code> and the name.</p>
<section id="variable-scope">
<span id="variables-scope"></span><h3>Variable Scope<a class="headerlink" href="#variable-scope" title="Link to this heading">¶</a></h3>
<p>All variables in fish have a scope. For example they can be global or local to a function or block:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># This variable is global, we can use it everywhere.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">--global</span><span class="w"> </span><span class="no">name</span><span class="w"> </span><span class="no">Patrick</span>
<span class="c"># This variable is local, it will not be visible in a function we call from here.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">--local</span><span class="w"> </span><span class="no">place</span><span class="w"> </span><span class="s2">"at the Krusty Krab"</span>
<span class="nf">function</span><span class="w"> </span><span class="no">local</span>
<span class="w"> </span><span class="c"># This can find $name, but not $place</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Hello</span><span class="w"> </span><span class="no">this</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$name</span><span class="w"> </span><span class="o">$place</span>
<span class="w"> </span><span class="c"># This variable is local, it will not be available</span>
<span class="w"> </span><span class="c"># outside of this function</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">--local</span><span class="w"> </span><span class="no">instrument</span><span class="w"> </span><span class="no">mayonnaise</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">My</span><span class="w"> </span><span class="no">favorite</span><span class="w"> </span><span class="no">instrument</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$instrument</span>
<span class="w"> </span><span class="c"># This creates a local $name, and won't touch the global one</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">--local</span><span class="w"> </span><span class="no">name</span><span class="w"> </span><span class="no">Spongebob</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">My</span><span class="w"> </span><span class="no">best</span><span class="w"> </span><span class="no">friend</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$name</span>
<span class="nf">end</span>
<span class="nf">local</span>
<span class="c"># Will print:</span>
<span class="c"># Hello this is Patrick</span>
<span class="c"># My favorite instrument is mayonnaise</span>
<span class="c"># My best friend is Spongebob</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$name</span><span class="no">,</span><span class="w"> </span><span class="no">I</span><span class="w"> </span><span class="no">am</span><span class="w"> </span><span class="o">$place</span><span class="w"> </span><span class="no">and</span><span class="w"> </span><span class="no">my</span><span class="w"> </span><span class="no">instrument</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$instrument</span>
<span class="c"># Will print:</span>
<span class="c"># Patrick, I am at the Krusty Krab and my instrument is</span>
</pre></div>
</div>
<p>There are four kinds of variable scopes in fish: universal, global, function and local variables.</p>
<ul class="simple">
<li><p>Universal variables are shared between all fish sessions a user is running on one computer. They are stored on disk and persist even after reboot.</p></li>
<li><p>Global variables are specific to the current fish session. They can be erased by explicitly requesting <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">-e</span></code>.</p></li>
<li><p>Function variables are specific to the currently executing function. They are erased (“go out of scope”) when the current function ends. Outside of a function, they don’t go out of scope.</p></li>
<li><p>Local variables are specific to the current block of commands, and automatically erased when a specific block goes out of scope. A block of commands is a series of commands that begins with one of the commands <code class="docutils literal notranslate"><span class="pre">for</span></code>, <code class="docutils literal notranslate"><span class="pre">while</span></code> , <code class="docutils literal notranslate"><span class="pre">if</span></code>, <code class="docutils literal notranslate"><span class="pre">function</span></code>, <code class="docutils literal notranslate"><span class="pre">begin</span></code> or <code class="docutils literal notranslate"><span class="pre">switch</span></code>, and ends with the command <code class="docutils literal notranslate"><span class="pre">end</span></code>. Outside of a block, this is the same as the function scope.</p></li>
</ul>
<p>Variables can be explicitly set to be universal with the <code class="docutils literal notranslate"><span class="pre">-U</span></code> or <code class="docutils literal notranslate"><span class="pre">--universal</span></code> switch, global with <code class="docutils literal notranslate"><span class="pre">-g</span></code> or <code class="docutils literal notranslate"><span class="pre">--global</span></code>, function-scoped with <code class="docutils literal notranslate"><span class="pre">-f</span></code> or <code class="docutils literal notranslate"><span class="pre">--function</span></code> and local to the current block with <code class="docutils literal notranslate"><span class="pre">-l</span></code> or <code class="docutils literal notranslate"><span class="pre">--local</span></code>. The scoping rules when creating or updating a variable are:</p>
<ul class="simple">
<li><p>When a scope is explicitly given, it will be used. If a variable of the same name exists in a different scope, that variable will not be changed.</p></li>
<li><p>When no scope is given, but a variable of that name exists, the variable of the smallest scope will be modified. The scope will not be changed.</p></li>
<li><p>When no scope is given and no variable of that name exists, the variable is created in function scope if inside a function, or global scope if no function is executing.</p></li>
</ul>
<p>There can be many variables with the same name, but different scopes. When you <a class="reference internal" href="#expand-variable"><span class="std std-ref">use a variable</span></a>, the smallest scoped variable of that name will be used. If a local variable exists, it will be used instead of the global or universal variable of the same name.</p>
<p>Example:</p>
<p>There are a few possible uses for different scopes.</p>
<p>Typically inside functions you should use local scope:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">something</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="no">/path/to/my/file</span>
<span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="o">not</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="s2">"</span><span class="o">$file</span><span class="s2">"</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="no">/path/to/my/otherfile</span>
<span class="w"> </span><span class="nf">end</span>
<span class="nf">end</span>
<span class="c"># or</span>
<span class="nf">function</span><span class="w"> </span><span class="no">something</span>
<span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">/path/to/my/file</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-f</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="no">/path/to/my/file</span>
<span class="w"> </span><span class="nf">else</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-f</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="no">/path/to/my/otherfile</span>
<span class="w"> </span><span class="nf">end</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>If you want to set something in config.fish, or set something in a function and have it available for the rest of the session, global scope is a good choice:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Don't shorten the working directory in the prompt</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">fish_prompt_pwd_dir_length</span><span class="w"> </span><span class="no">0</span>
<span class="c"># Set my preferred cursor style:</span>
<span class="nf">function</span><span class="w"> </span><span class="no">setcursors</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">fish_cursor_default</span><span class="w"> </span><span class="no">block</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">fish_cursor_insert</span><span class="w"> </span><span class="no">line</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-g</span><span class="w"> </span><span class="no">fish_cursor_visual</span><span class="w"> </span><span class="no">underscore</span>
<span class="nf">end</span>
<span class="c"># Set my language</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">LANG</span><span class="w"> </span><span class="no">de_DE.UTF-8</span>
</pre></div>
</div>
<p>If you want to set some personal customization, universal variables are nice:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Typically you'd run this interactively, fish takes care of keeping it.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-U</span><span class="w"> </span><span class="no">fish_color_autosuggestion</span><span class="w"> </span><span class="no">555</span>
</pre></div>
</div>
<p>Here is an example of local vs function-scoped variables:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">test-scopes</span>
<span class="w"> </span><span class="nf">begin</span>
<span class="w"> </span><span class="c"># This is a nice local scope where all variables will die</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">pirate</span><span class="w"> </span><span class="s1">'There be treasure in them thar hills'</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-f</span><span class="w"> </span><span class="no">captain</span><span class="w"> </span><span class="no">Space,</span><span class="w"> </span><span class="no">the</span><span class="w"> </span><span class="no">final</span><span class="w"> </span><span class="no">frontier</span>
<span class="w"> </span><span class="c"># If no variable of that name was defined, it is function-local.</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">gnu</span><span class="w"> </span><span class="s2">"In the beginning there was nothing, which exploded"</span>
<span class="w"> </span><span class="nf">end</span>
<span class="w"> </span><span class="c"># This will not output anything, since the pirate was local</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$pirate</span>
<span class="w"> </span><span class="c"># This will output the good Captain's speech</span>
<span class="w"> </span><span class="c"># since $captain had function-scope.</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$captain</span>
<span class="w"> </span><span class="c"># This will output Sir Terry's wisdom.</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$gnu</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>When a function calls another, local variables aren’t visible:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">shiver</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">phrase</span><span class="w"> </span><span class="s1">'Shiver me timbers'</span>
<span class="nf">end</span>
<span class="nf">function</span><span class="w"> </span><span class="no">avast</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">--local</span><span class="w"> </span><span class="no">phrase</span><span class="w"> </span><span class="s1">'Avast, mateys'</span>
<span class="w"> </span><span class="c"># Calling the shiver function here can not</span>
<span class="w"> </span><span class="c"># change any variables in the local scope</span>
<span class="w"> </span><span class="c"># so phrase remains as we set it here.</span>
<span class="w"> </span><span class="nf">shiver</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$phrase</span>
<span class="nf">end</span>
<span class="nf">avast</span>
<span class="c"># Outputs "Avast, mateys"</span>
</pre></div>
</div>
<p>When in doubt, use function-scoped variables. When you need to make a variable accessible everywhere, make it global. When you need to persistently store configuration, make it universal. When you want to use a variable only in a short block, make it local.</p>
</section>
<section id="overriding-variables-for-a-single-command">
<span id="variables-override"></span><h3>Overriding variables for a single command<a class="headerlink" href="#overriding-variables-for-a-single-command" title="Link to this heading">¶</a></h3>
<p>If you want to override a variable for a single command, you can use “var=val” statements before the command:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Call git status on another directory</span>
<span class="c"># (can also be done via `git -C somerepo status`)</span>
<span class="no">GIT_DIR</span><span class="o">=</span><span class="no">somerepo</span><span class="w"> </span><span class="nf">git</span><span class="w"> </span><span class="no">status</span>
</pre></div>
</div>
<p>Unlike other shells, fish will first set the variable and then perform other expansions on the line, so:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">foo</span><span class="w"> </span><span class="no">banana</span>
<span class="no">foo</span><span class="o">=</span><span class="no">gagaga</span><span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$foo</span>
<span class="c"># prints gagaga, while in other shells it might print "banana"</span>
</pre></div>
</div>
<p>Multiple elements can be given in a <a class="reference internal" href="#expand-brace"><span class="std std-ref">brace expansion</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Call bash with a reasonable default path.</span>
<span class="no">PATH</span><span class="o">={</span><span class="no">/usr</span><span class="o">,}</span><span class="no">/</span><span class="o">{</span><span class="no">s</span><span class="o">,}</span><span class="no">bin</span><span class="w"> </span><span class="nf">bash</span>
</pre></div>
</div>
<p>Or with a <a class="reference internal" href="#expand-wildcard"><span class="std std-ref">glob</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Run vlc on all mp3 files in the current directory</span>
<span class="c"># If no file exists it will still be run with no arguments</span>
<span class="no">mp3s</span><span class="o">=*</span><span class="no">.mp3</span><span class="w"> </span><span class="nf">vlc</span><span class="w"> </span><span class="o">$mp3s</span>
</pre></div>
</div>
<p>Unlike other shells, this does <em>not</em> inhibit any lookup (aliases or similar). Calling a command after setting a variable override will result in the exact same command being run.</p>
<p>This syntax is supported since fish 3.1.</p>
</section>
<section id="universal-variables">
<span id="variables-universal"></span><h3>Universal Variables<a class="headerlink" href="#universal-variables" title="Link to this heading">¶</a></h3>
<p>Universal variables are variables that are shared between all the user’s fish sessions on the computer. Fish stores many of its configuration options as universal variables. This means that in order to change fish settings, all you have to do is change the variable value once, and it will be automatically updated for all sessions, and preserved across computer reboots and login/logout.</p>
<p>To see universal variables in action, start two fish sessions side by side, and issue the following command in one of them <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">fish_color_cwd</span> <span class="pre">blue</span></code>. Since <code class="docutils literal notranslate"><span class="pre">fish_color_cwd</span></code> is a universal variable, the color of the current working directory listing in the prompt will instantly change to blue on both terminals.</p>
<p><a class="reference internal" href="#variables-universal"><span class="std std-ref">Universal variables</span></a> are stored in the file <code class="docutils literal notranslate"><span class="pre">.config/fish/fish_variables</span></code>. Do not edit this file directly, as your edits may be overwritten. Edit the variables through fish scripts or by using fish interactively instead.</p>
<p>Do not append to universal variables in <a class="reference internal" href="#configuration"><span class="std std-ref">config.fish</span></a>, because these variables will then get longer with each new shell instance. Instead, set them once at the command line.</p>
</section>
<section id="exporting-variables">
<span id="variables-export"></span><h3>Exporting variables<a class="headerlink" href="#exporting-variables" title="Link to this heading">¶</a></h3>
<p>Variables in fish can be exported, so they will be inherited by any commands started by fish. In particular, this is necessary for variables used to configure external commands like <code class="docutils literal notranslate"><span class="pre">PAGER</span></code> or <code class="docutils literal notranslate"><span class="pre">GOPATH</span></code>, but also for variables that contain general system settings like <code class="docutils literal notranslate"><span class="pre">PATH</span></code> or <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code>. If an external command needs to know a variable, it needs to be exported. Exported variables are also often called “environment variables”.</p>
<p>This also applies to fish - when it starts up, it receives environment variables from its parent (usually the terminal). These typically include system configuration like <span class="target" id="index-4"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a> and <a class="reference internal" href="#variables-locale"><span class="std std-ref">locale variables</span></a>.</p>
<p>Variables can be explicitly set to be exported with the <code class="docutils literal notranslate"><span class="pre">-x</span></code> or <code class="docutils literal notranslate"><span class="pre">--export</span></code> switch, or not exported with the <code class="docutils literal notranslate"><span class="pre">-u</span></code> or <code class="docutils literal notranslate"><span class="pre">--unexport</span></code> switch. The exporting rules when setting a variable are similar to the scoping rules for variables - when an option is passed it is respected, otherwise the variable’s existing state is used. If no option is passed and the variable didn’t exist yet it is not exported.</p>
<p>As a naming convention, exported variables are in uppercase and unexported variables are in lowercase.</p>
<p>For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">ANDROID_HOME</span><span class="w"> </span><span class="o">~</span><span class="no">/.android</span><span class="w"> </span><span class="c"># /opt/android-sdk</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">CDPATH</span><span class="w"> </span><span class="no">.</span><span class="w"> </span><span class="o">~</span><span class="w"> </span><span class="o">(</span><span class="nf">test</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="o">~</span><span class="no">/Videos</span><span class="p">;</span><span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">~</span><span class="no">/Videos</span><span class="o">)</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">EDITOR</span><span class="w"> </span><span class="no">emacs</span><span class="w"> </span><span class="no">-nw</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">GOPATH</span><span class="w"> </span><span class="o">~</span><span class="no">/dev/go</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">GTK2_RC_FILES</span><span class="w"> </span><span class="s2">"</span><span class="o">$XDG_CONFIG_HOME</span><span class="s2">/gtk-2.0/gtkrc"</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">LESSHISTFILE</span><span class="w"> </span><span class="s2">"-"</span>
</pre></div>
</div>
<p>Note: Exporting is not a <a class="reference internal" href="#variables-scope"><span class="std std-ref">scope</span></a>, but an additional state. It typically makes sense to make exported variables global as well, but local-exported variables can be useful if you need something more specific than <a class="reference internal" href="#variables-override"><span class="std std-ref">Overrides</span></a>. They are <em>copied</em> to functions so the function can’t alter them outside, and still available to commands. Global variables are accessible to functions whether they are exported or not.</p>
</section>
<section id="lists">
<span id="variables-lists"></span><h3>Lists<a class="headerlink" href="#lists" title="Link to this heading">¶</a></h3>
<p>Fish can store a list (or an “array” if you wish) of multiple strings inside of a variable:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">mylist</span><span class="w"> </span><span class="no">first</span><span class="w"> </span><span class="no">second</span><span class="w"> </span><span class="no">third</span>
<span class="gp">> </span><span class="nf">printf</span><span class="w"> </span><span class="s1">'%s\n'</span><span class="w"> </span><span class="o">$mylist</span><span class="w"> </span><span class="c"># prints each element on its own line</span>
<span class="go">first</span>
<span class="go">second</span>
<span class="go">third</span>
</pre></div>
</div>
<p>To access one element of a list, use the index of the element inside of square brackets, like this:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">echo</span><span class="w"> </span><span class="o">$PATH[</span><span class="no">3</span><span class="o">]</span>
</pre></div>
</div>
<p>List indices start at 1 in fish, not 0 like in other languages. This is because it requires less subtracting of 1 and many common Unix tools like <code class="docutils literal notranslate"><span class="pre">seq</span></code> work better with it (<code class="docutils literal notranslate"><span class="pre">seq</span> <span class="pre">5</span></code> prints 1 to 5, not 0 to 5). An invalid index is silently ignored resulting in no value (not even an empty string, no argument at all).</p>
<p>If you don’t use any brackets, all the elements of the list will be passed to the command as separate items. This means you can iterate over a list with <code class="docutils literal notranslate"><span class="pre">for</span></code>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">for</span><span class="w"> </span><span class="no">i</span><span class="w"> </span><span class="nf">in</span><span class="w"> </span><span class="o">$PATH</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$i</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="no">in</span><span class="w"> </span><span class="no">the</span><span class="w"> </span><span class="no">path</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>This goes over every directory in <span class="target" id="index-5"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a> separately and prints a line saying it is in the path.</p>
<p>To create a variable <code class="docutils literal notranslate"><span class="pre">smurf</span></code>, containing the items <code class="docutils literal notranslate"><span class="pre">blue</span></code> and <code class="docutils literal notranslate"><span class="pre">small</span></code>, write:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">smurf</span><span class="w"> </span><span class="no">blue</span><span class="w"> </span><span class="no">small</span>
</pre></div>
</div>
<p>It is also possible to set or erase individual elements of a list:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Set smurf to be a list with the elements 'blue' and 'small'</span>
<span class="nf">set</span><span class="w"> </span><span class="no">smurf</span><span class="w"> </span><span class="no">blue</span><span class="w"> </span><span class="no">small</span>
<span class="c"># Change the second element of smurf to 'evil'</span>
<span class="nf">set</span><span class="w"> </span><span class="no">smurf[2]</span><span class="w"> </span><span class="no">evil</span>
<span class="c"># Erase the first element</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-e</span><span class="w"> </span><span class="no">smurf[1]</span>
<span class="c"># Output 'evil'</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$smurf</span>
</pre></div>
</div>
<p>If you specify a negative index when expanding or assigning to a list variable, the index will be taken from the <em>end</em> of the list. For example, the index -1 is the last element of the list:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">fruit</span><span class="w"> </span><span class="no">apple</span><span class="w"> </span><span class="no">orange</span><span class="w"> </span><span class="no">banana</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$fruit[</span><span class="no">-1</span><span class="o">]</span>
<span class="go">banana</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$fruit[</span><span class="no">-2..-1</span><span class="o">]</span>
<span class="go">orange</span>
<span class="go">banana</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$fruit[</span><span class="no">-1..1</span><span class="o">]</span><span class="w"> </span><span class="c"># reverses the list</span>
<span class="go">banana</span>
<span class="go">orange</span>
<span class="go">apple</span>
</pre></div>
</div>
<p>As you see, you can use a range of indices, see <a class="reference internal" href="#expand-slices"><span class="std std-ref">slices</span></a> for details.</p>
<p>All lists are one-dimensional and can’t contain other lists, although it is possible to fake nested lists using dereferencing - see <a class="reference internal" href="#expand-variable"><span class="std std-ref">variable expansion</span></a>.</p>
<p>When a list is exported as an environment variable, it is either space or colon delimited, depending on whether it is a <a class="reference internal" href="#variables-path"><span class="std std-ref">path variable</span></a>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-x</span><span class="w"> </span><span class="no">smurf</span><span class="w"> </span><span class="no">blue</span><span class="w"> </span><span class="no">small</span>
<span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-x</span><span class="w"> </span><span class="no">smurf_PATH</span><span class="w"> </span><span class="no">forest</span><span class="w"> </span><span class="no">mushroom</span>
<span class="gp">> </span><span class="nf">env</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">grep</span><span class="w"> </span><span class="no">smurf</span>
<span class="go">smurf=blue small</span>
<span class="go">smurf_PATH=forest:mushroom</span>
</pre></div>
</div>
<p>Fish automatically creates lists from all environment variables whose name ends in <code class="docutils literal notranslate"><span class="pre">PATH</span></code> (like <span class="target" id="index-6"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>, <span class="target" id="index-7"></span><a class="reference internal" href="#envvar-CDPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">CDPATH</span></code></a> or <span class="target" id="index-8"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">MANPATH</span></code>), by splitting them on colons. Other variables are not automatically split.</p>
<p>Lists can be inspected with the <a class="reference internal" href="cmds/count.html"><span class="doc">count</span></a> or the <a class="reference internal" href="cmds/contains.html"><span class="doc">contains</span></a> commands:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">count</span><span class="w"> </span><span class="o">$smurf</span>
<span class="go">2</span>
<span class="gp">> </span><span class="nf">contains</span><span class="w"> </span><span class="no">blue</span><span class="w"> </span><span class="o">$smurf</span>
<span class="go"># blue was found, so it exits with status 0</span>
<span class="go"># (without printing anything)</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$status</span>
<span class="go">0</span>
<span class="gp">> </span><span class="nf">contains</span><span class="w"> </span><span class="no">-i</span><span class="w"> </span><span class="no">blue</span><span class="w"> </span><span class="o">$smurf</span>
<span class="go">1</span>
</pre></div>
</div>
<p>A nice thing about lists is that they are passed to commands one element as one argument, so once you’ve set your list, you can pass it:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">grep_args</span><span class="w"> </span><span class="no">-r</span><span class="w"> </span><span class="s2">"my string"</span>
<span class="nf">grep</span><span class="w"> </span><span class="o">$grep_args</span><span class="w"> </span><span class="no">.</span><span class="w"> </span><span class="c"># will run the same as `grep -r "my string"` .</span>
</pre></div>
</div>
<p>Unlike other shells, fish does not do “word splitting” - elements in a list stay as they are, even if they contain spaces or tabs.</p>
</section>
<section id="argument-handling">
<span id="variables-argv"></span><h3>Argument Handling<a class="headerlink" href="#argument-handling" title="Link to this heading">¶</a></h3>
<p>An important list is <code class="docutils literal notranslate"><span class="pre">$argv</span></code>, which contains the arguments to a function or script. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">myfunction</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$argv[</span><span class="no">1</span><span class="o">]</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$argv[</span><span class="no">3</span><span class="o">]</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>This function takes whatever arguments it gets and prints the first and third:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">myfunction</span><span class="w"> </span><span class="no">first</span><span class="w"> </span><span class="no">second</span><span class="w"> </span><span class="no">third</span>
<span class="go">first</span>
<span class="go">third</span>
<span class="gp">> </span><span class="nf">myfunction</span><span class="w"> </span><span class="no">apple</span><span class="w"> </span><span class="no">cucumber</span><span class="w"> </span><span class="no">banana</span>
<span class="go">apple</span>
<span class="go">banana</span>
</pre></div>
</div>
<p>That covers the positional arguments, but commandline tools often get various options and flags, and $argv would contain them intermingled with the positional arguments. Typical unix argument handling allows short options (<code class="docutils literal notranslate"><span class="pre">-h</span></code>, also grouped like in <code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">-lah</span></code>), long options (<code class="docutils literal notranslate"><span class="pre">--help</span></code>) and allows those options to take arguments (<code class="docutils literal notranslate"><span class="pre">--color=auto</span></code> or <code class="docutils literal notranslate"><span class="pre">--position</span> <span class="pre">anywhere</span></code> or <code class="docutils literal notranslate"><span class="pre">complete</span> <span class="pre">-C"git</span> <span class="pre">"</span></code>) as well as a <code class="docutils literal notranslate"><span class="pre">--</span></code> separator to signal the end of options. Handling all of these manually is tricky and error-prone.</p>
<p>A more robust approach to option handling is <a class="reference internal" href="cmds/argparse.html"><span class="doc">argparse</span></a>, which checks the defined options and puts them into various variables, leaving only the positional arguments in $argv. Here’s a simple example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">mybetterfunction</span>
<span class="w"> </span><span class="c"># We tell argparse about -h/--help and -s/--second</span>
<span class="w"> </span><span class="c"># - these are short and long forms of the same option.</span>
<span class="w"> </span><span class="c"># The "--" here is mandatory,</span>
<span class="w"> </span><span class="c"># it tells it from where to read the arguments.</span>
<span class="w"> </span><span class="nf">argparse</span><span class="w"> </span><span class="no">h/help</span><span class="w"> </span><span class="no">s/second</span><span class="w"> </span><span class="no">--</span><span class="w"> </span><span class="o">$argv</span>
<span class="w"> </span><span class="c"># exit if argparse failed because</span>
<span class="w"> </span><span class="c"># it found an option it didn't recognize</span>
<span class="w"> </span><span class="c"># - it will print an error</span>
<span class="w"> </span><span class="o">or</span><span class="w"> </span><span class="nf">return</span>
<span class="w"> </span><span class="c"># If -h or --help is given, we print a little help text and return</span>
<span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-ql</span><span class="w"> </span><span class="no">_flag_help</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="s2">"mybetterfunction [-h|--help] [-s|--second] [ARGUMENT ...]"</span>
<span class="w"> </span><span class="nf">return</span><span class="w"> </span><span class="no">0</span>
<span class="w"> </span><span class="nf">end</span>
<span class="w"> </span><span class="c"># If -s or --second is given, we print the second argument,</span>
<span class="w"> </span><span class="c"># not the first and third.</span>
<span class="w"> </span><span class="c"># (this is also available as _flag_s because of the short version)</span>
<span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-ql</span><span class="w"> </span><span class="no">_flag_second</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$argv[</span><span class="no">2</span><span class="o">]</span>
<span class="w"> </span><span class="nf">else</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$argv[</span><span class="no">1</span><span class="o">]</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$argv[</span><span class="no">3</span><span class="o">]</span>
<span class="w"> </span><span class="nf">end</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>The options will be <em>removed</em> from $argv, so $argv[2] is the second <em>positional</em> argument now:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">mybetterfunction</span><span class="w"> </span><span class="no">first</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">second</span><span class="w"> </span><span class="no">third</span>
<span class="go">second</span>
</pre></div>
</div>
<p>For more information on argparse, like how to handle option arguments, see <a class="reference internal" href="cmds/argparse.html"><span class="doc">the argparse documentation</span></a>.</p>
</section>
<section id="path-variables">
<span id="variables-path"></span><h3>PATH variables<a class="headerlink" href="#path-variables" title="Link to this heading">¶</a></h3>
<p>Path variables are a special kind of variable used to support colon-delimited path lists including <span class="target" id="index-9"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>, <span class="target" id="index-10"></span><a class="reference internal" href="#envvar-CDPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">CDPATH</span></code></a>, <span class="target" id="index-11"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">MANPATH</span></code>, <span class="target" id="index-12"></span><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONPATH</span></code>, <span class="target" id="index-13"></span><a class="reference internal" href="#envvar-LANGUAGE"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LANGUAGE</span></code></a> (for <a class="reference internal" href="cmds/_.html"><span class="doc">localization</span></a>) etc. All variables that end in “PATH” (case-sensitive) become PATH variables by default.</p>
<p>PATH variables act as normal lists, except they are implicitly joined and split on colons.</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">MYPATH</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">2</span><span class="w"> </span><span class="no">3</span>
<span class="nf">echo</span><span class="w"> </span><span class="s2">"</span><span class="o">$MYPATH</span><span class="s2">"</span>
<span class="c"># 1:2:3</span>
<span class="nf">set</span><span class="w"> </span><span class="no">MYPATH</span><span class="w"> </span><span class="s2">"</span><span class="o">$MYPATH</span><span class="s2">:4:5"</span>
<span class="nf">echo</span><span class="w"> </span><span class="o">$MYPATH</span>
<span class="c"># 1 2 3 4 5</span>
<span class="nf">echo</span><span class="w"> </span><span class="s2">"</span><span class="o">$MYPATH</span><span class="s2">"</span>
<span class="c"># 1:2:3:4:5</span>
</pre></div>
</div>
<p>Path variables will also be exported in the colon form, so <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">-x</span> <span class="pre">MYPATH</span> <span class="pre">1</span> <span class="pre">2</span> <span class="pre">3</span></code> will have external commands see it as <code class="docutils literal notranslate"><span class="pre">1:2:3</span></code>.</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-gx</span><span class="w"> </span><span class="no">MYPATH</span><span class="w"> </span><span class="no">/bin</span><span class="w"> </span><span class="no">/usr/bin</span><span class="w"> </span><span class="no">/sbin</span>
<span class="gp">> </span><span class="nf">env</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">grep</span><span class="w"> </span><span class="no">MYPATH</span>
<span class="go">MYPATH=/bin:/usr/bin:/sbin</span>
</pre></div>
</div>
<p>This is for compatibility with other tools. Unix doesn’t have variables with multiple elements, the closest thing it has are colon-lists like <span class="target" id="index-14"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>. For obvious reasons this means no element can contain a <code class="docutils literal notranslate"><span class="pre">:</span></code>.</p>
<p>Variables can be marked or unmarked as PATH variables via the <code class="docutils literal notranslate"><span class="pre">--path</span></code> and <code class="docutils literal notranslate"><span class="pre">--unpath</span></code> options to <code class="docutils literal notranslate"><span class="pre">set</span></code>.</p>
</section>
<section id="special-variables">
<span id="variables-special"></span><h3>Special variables<a class="headerlink" href="#special-variables" title="Link to this heading">¶</a></h3>
<p>You can change the settings of fish by changing the values of certain variables.</p>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-PATH">
<span class="sig-name descname"><span class="pre">PATH</span></span><a class="headerlink" href="#envvar-PATH" title="Link to this definition">¶</a></dt>
<dd><p>A list of directories in which to search for commands. This is a common unix variable also used by other tools.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-CDPATH">
<span class="sig-name descname"><span class="pre">CDPATH</span></span><a class="headerlink" href="#envvar-CDPATH" title="Link to this definition">¶</a></dt>
<dd><p>A list of directories in which the <a class="reference internal" href="cmds/cd.html"><span class="doc">cd</span></a> builtin looks for a new directory.</p>
</dd></dl>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">Locale</span> <span class="pre">Variables</span></span></dt>
<dd><p>Locale variables such as <span class="target" id="index-15"></span><a class="reference internal" href="#envvar-LANG"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LANG</span></code></a>, <span class="target" id="index-16"></span><a class="reference internal" href="#envvar-LC_ALL"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LC_ALL</span></code></a>, <span class="target" id="index-17"></span><a class="reference internal" href="#envvar-LC_MESSAGES"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LC_MESSAGES</span></code></a>, <span class="target" id="index-18"></span><a class="reference internal" href="#envvar-LC_NUMERIC"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LC_NUMERIC</span></code></a> and <span class="target" id="index-19"></span><a class="reference internal" href="#envvar-LC_TIME"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LC_TIME</span></code></a> set the language option for the shell and subprograms. See the section <a class="reference internal" href="#variables-locale"><span class="std std-ref">Locale variables</span></a> for more information.</p>
</dd></dl>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">Color</span> <span class="pre">variables</span></span></dt>
<dd><p>A number of variable starting with the prefixes <code class="docutils literal notranslate"><span class="pre">fish_color</span></code> and <code class="docutils literal notranslate"><span class="pre">fish_pager_color</span></code>. See <a class="reference internal" href="interactive.html#variables-color"><span class="std std-ref">Variables for changing highlighting colors</span></a> for more information.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_term24bit">
<span class="sig-name descname"><span class="pre">fish_term24bit</span></span><a class="headerlink" href="#envvar-fish_term24bit" title="Link to this definition">¶</a></dt>
<dd><p>If this is set to 0, fish will not output 24-bit RGB true-color sequences but the nearest color on the 256 color palette (or the 16 color palette, if <span class="target" id="index-20"></span><a class="reference internal" href="#envvar-fish_term256"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_term256</span></code></a> is 0).
See also <a class="reference internal" href="cmds/set_color.html"><span class="doc">set_color</span></a>.
The default is 1 but for historical reasons, fish defaults to behaving as if it was 0 on some terminals that are known to not support true-color sequences.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_term256">
<span class="sig-name descname"><span class="pre">fish_term256</span></span><a class="headerlink" href="#envvar-fish_term256" title="Link to this definition">¶</a></dt>
<dd><p>If this is set to 0 and <span class="target" id="index-21"></span><a class="reference internal" href="#envvar-fish_term24bit"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_term24bit</span></code></a> is 0, translate RGB colors down to the 16 color palette.
Also, if this is set to 0, <a class="reference internal" href="cmds/set_color.html"><span class="doc">set_color</span></a> commands such as <code class="docutils literal notranslate"><span class="pre">set_color</span> <span class="pre">ff0000</span> <span class="pre">red</span></code> will prefer the named color.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_ambiguous_width">
<span class="sig-name descname"><span class="pre">fish_ambiguous_width</span></span><a class="headerlink" href="#envvar-fish_ambiguous_width" title="Link to this definition">¶</a></dt>
<dd><p>controls the computed width of ambiguous-width characters. This should be set to 1 if your terminal renders these characters as single-width (typical), or 2 if double-width.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_emoji_width">
<span class="sig-name descname"><span class="pre">fish_emoji_width</span></span><a class="headerlink" href="#envvar-fish_emoji_width" title="Link to this definition">¶</a></dt>
<dd><p>controls whether fish assumes emoji render as 2 cells or 1 cell wide. This is necessary because the correct value changed from 1 to 2 in Unicode 9, and some terminals may not be aware. Set this if you see graphical glitching related to emoji (or other “special” characters). It should usually be auto-detected.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_autosuggestion_enabled">
<span class="sig-name descname"><span class="pre">fish_autosuggestion_enabled</span></span><a class="headerlink" href="#envvar-fish_autosuggestion_enabled" title="Link to this definition">¶</a></dt>
<dd><p>controls if <a class="reference internal" href="interactive.html#autosuggestions"><span class="std std-ref">Autosuggestions</span></a> are enabled. Set it to 0 to disable, anything else to enable. By default they are on.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_transient_prompt">
<span class="sig-name descname"><span class="pre">fish_transient_prompt</span></span><a class="headerlink" href="#envvar-fish_transient_prompt" title="Link to this definition">¶</a></dt>
<dd><p>If this is set to 1, fish will redraw prompts with a <code class="docutils literal notranslate"><span class="pre">--final-rendering</span></code> argument before running a commandline, allowing you to change it before pushing it to the scrollback. This enables <a class="reference internal" href="prompt.html#transient-prompt"><span class="std std-ref">transient prompts</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_handle_reflow">
<span class="sig-name descname"><span class="pre">fish_handle_reflow</span></span><a class="headerlink" href="#envvar-fish_handle_reflow" title="Link to this definition">¶</a></dt>
<dd><p>determines whether fish should try to repaint the commandline when the terminal resizes. In terminals that reflow text this should be disabled. Set it to 1 to enable, anything else to disable.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_key_bindings">
<span class="sig-name descname"><span class="pre">fish_key_bindings</span></span><a class="headerlink" href="#envvar-fish_key_bindings" title="Link to this definition">¶</a></dt>
<dd><p>the name of the function that sets up the keyboard shortcuts for the <a class="reference internal" href="interactive.html#editor"><span class="std std-ref">command-line editor</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_escape_delay_ms">
<span class="sig-name descname"><span class="pre">fish_escape_delay_ms</span></span><a class="headerlink" href="#envvar-fish_escape_delay_ms" title="Link to this definition">¶</a></dt>
<dd><p>sets how long fish waits for another key after seeing an escape, to distinguish pressing the escape key from the start of an escape sequence. The default is 30ms. Increasing it increases the latency but allows pressing escape instead of alt for alt+character bindings. For more information, see <a class="reference internal" href="cmds/bind.html#cmd-bind-escape"><span class="std std-ref">the chapter in the bind documentation</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_sequence_key_delay_ms">
<span class="sig-name descname"><span class="pre">fish_sequence_key_delay_ms</span></span><a class="headerlink" href="#envvar-fish_sequence_key_delay_ms" title="Link to this definition">¶</a></dt>
<dd><p>sets how long fish waits for another key after seeing a key that is part of a longer sequence, to disambiguate. For instance if you had bound <code class="docutils literal notranslate"><span class="pre">\cx\ce</span></code> to open an editor, fish would wait for this long in milliseconds to see a ctrl-e after a ctrl-x. If the time elapses, it will handle it as a ctrl-x (by default this would copy the current commandline to the clipboard). See also <a class="reference internal" href="interactive.html#interactive-key-sequences"><span class="std std-ref">Key sequences</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_complete_path">
<span class="sig-name descname"><span class="pre">fish_complete_path</span></span><a class="headerlink" href="#envvar-fish_complete_path" title="Link to this definition">¶</a></dt>
<dd><p>determines where fish looks for completion. When trying to complete for a command, fish looks for files in the directories in this variable.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_cursor_selection_mode">
<span class="sig-name descname"><span class="pre">fish_cursor_selection_mode</span></span><a class="headerlink" href="#envvar-fish_cursor_selection_mode" title="Link to this definition">¶</a></dt>
<dd><p>controls whether the selection is inclusive or exclusive of the character under the cursor (see <a class="reference internal" href="interactive.html#killring"><span class="std std-ref">Copy and Paste</span></a>).</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_function_path">
<span class="sig-name descname"><span class="pre">fish_function_path</span></span><a class="headerlink" href="#envvar-fish_function_path" title="Link to this definition">¶</a></dt>
<dd><p>determines where fish looks for functions. When fish <a class="reference internal" href="#syntax-function-autoloading"><span class="std std-ref">autoloads</span></a> a function, it will look for files in these directories.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_greeting">
<span class="sig-name descname"><span class="pre">fish_greeting</span></span><a class="headerlink" href="#envvar-fish_greeting" title="Link to this definition">¶</a></dt>
<dd><p>the greeting message printed on startup. This is printed by a function of the same name that can be overridden for more complicated changes (see <a class="reference internal" href="cmds/funced.html"><span class="doc">funced</span></a>)</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_history">
<span class="sig-name descname"><span class="pre">fish_history</span></span><a class="headerlink" href="#envvar-fish_history" title="Link to this definition">¶</a></dt>
<dd><p>the current history session name. If set, all subsequent commands within an
interactive fish session will be logged to a separate file identified by the value of the
variable. If unset, the default session name “fish” is used. If set to an
empty string, history is not saved to disk (but is still available within the interactive
session).</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_trace">
<span class="sig-name descname"><span class="pre">fish_trace</span></span><a class="headerlink" href="#envvar-fish_trace" title="Link to this definition">¶</a></dt>
<dd><p>if set and not empty, will cause fish to print commands before they execute, similar to <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">-x</span></code>
in bash. The trace is printed to the path given by the <cite>--debug-output</cite> option to fish or the <span class="target" id="index-22"></span><a class="reference internal" href="#envvar-FISH_DEBUG_OUTPUT"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">FISH_DEBUG_OUTPUT</span></code></a> variable. It goes to stderr by default.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-FISH_DEBUG">
<span class="sig-name descname"><span class="pre">FISH_DEBUG</span></span><a class="headerlink" href="#envvar-FISH_DEBUG" title="Link to this definition">¶</a></dt>
<dd><p>Controls which debug categories <strong class="command">fish</strong> enables for output, analogous to the <code class="docutils literal notranslate"><span class="pre">--debug</span></code> option.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-FISH_DEBUG_OUTPUT">
<span class="sig-name descname"><span class="pre">FISH_DEBUG_OUTPUT</span></span><a class="headerlink" href="#envvar-FISH_DEBUG_OUTPUT" title="Link to this definition">¶</a></dt>
<dd><p>Specifies a file to direct debug output to.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_user_paths">
<span class="sig-name descname"><span class="pre">fish_user_paths</span></span><a class="headerlink" href="#envvar-fish_user_paths" title="Link to this definition">¶</a></dt>
<dd><p>a list of directories that are prepended to <span class="target" id="index-23"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>. This can be a universal variable.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-umask">
<span class="sig-name descname"><span class="pre">umask</span></span><a class="headerlink" href="#envvar-umask" title="Link to this definition">¶</a></dt>
<dd><p>the current file creation mask. The preferred way to change the umask variable is through the <a class="reference internal" href="cmds/umask.html"><span class="doc">umask</span></a> function. An attempt to set umask to an invalid value will always fail.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-BROWSER">
<span class="sig-name descname"><span class="pre">BROWSER</span></span><a class="headerlink" href="#envvar-BROWSER" title="Link to this definition">¶</a></dt>
<dd><p>your preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.</p>
</dd></dl>
<p>Fish also provides additional information through the values of certain environment variables. Most of these variables are read-only and their value can’t be changed with <code class="docutils literal notranslate"><span class="pre">set</span></code>.</p>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-_">
<span class="sig-name descname"><span class="pre">_</span></span><a class="headerlink" href="#envvar-_" title="Link to this definition">¶</a></dt>
<dd><p>the name of the currently running command (though this is deprecated, and the use of <code class="docutils literal notranslate"><span class="pre">status</span> <span class="pre">current-command</span></code> is preferred).</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-argv">
<span class="sig-name descname"><span class="pre">argv</span></span><a class="headerlink" href="#envvar-argv" title="Link to this definition">¶</a></dt>
<dd><p>a list of arguments to the shell or function. <code class="docutils literal notranslate"><span class="pre">argv</span></code> is only defined when inside a function call, or if fish was invoked with a list of arguments, like <code class="docutils literal notranslate"><span class="pre">fish</span> <span class="pre">myscript.fish</span> <span class="pre">foo</span> <span class="pre">bar</span></code>. This variable can be changed.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-argv_opts">
<span class="sig-name descname"><span class="pre">argv_opts</span></span><a class="headerlink" href="#envvar-argv_opts" title="Link to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="cmds/argparse.html"><span class="doc">argparse</span></a> sets this to the list of successfully parsed options, including option-arguments. This variable can be changed.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-CMD_DURATION">
<span class="sig-name descname"><span class="pre">CMD_DURATION</span></span><a class="headerlink" href="#envvar-CMD_DURATION" title="Link to this definition">¶</a></dt>
<dd><p>the runtime of the last command in milliseconds.</p>
</dd></dl>
<dl class="describe">
<dt class="sig sig-object">
<span class="sig-name descname"><span class="pre">COLUMNS</span> <span class="pre">and</span> <span class="pre">LINES</span></span></dt>
<dd><p>the current size of the terminal in height and width. These values are only used by fish if the operating system does not report the size of the terminal. Both variables must be set in that case otherwise a default of 80x24 will be used. They are updated when the window size changes.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_kill_signal">
<span class="sig-name descname"><span class="pre">fish_kill_signal</span></span><a class="headerlink" href="#envvar-fish_kill_signal" title="Link to this definition">¶</a></dt>
<dd><p>the signal that terminated the last foreground job, or 0 if the job exited normally.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_killring">
<span class="sig-name descname"><span class="pre">fish_killring</span></span><a class="headerlink" href="#envvar-fish_killring" title="Link to this definition">¶</a></dt>
<dd><p>a list of entries in fish’s <a class="reference internal" href="interactive.html#killring"><span class="std std-ref">kill ring</span></a> of cut text.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_read_limit">
<span class="sig-name descname"><span class="pre">fish_read_limit</span></span><a class="headerlink" href="#envvar-fish_read_limit" title="Link to this definition">¶</a></dt>
<dd><p>how many bytes fish will process with <a class="reference internal" href="cmds/read.html"><span class="doc">read</span></a> or in a <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitution</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-fish_pid">
<span class="sig-name descname"><span class="pre">fish_pid</span></span><a class="headerlink" href="#envvar-fish_pid" title="Link to this definition">¶</a></dt>
<dd><p>the process ID (PID) of the shell.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-history">
<span class="sig-name descname"><span class="pre">history</span></span><a class="headerlink" href="#envvar-history" title="Link to this definition">¶</a></dt>
<dd><p>a list containing the last commands that were entered.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-HOME">
<span class="sig-name descname"><span class="pre">HOME</span></span><a class="headerlink" href="#envvar-HOME" title="Link to this definition">¶</a></dt>
<dd><p>the user’s home directory. This variable can be changed.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-hostname">
<span class="sig-name descname"><span class="pre">hostname</span></span><a class="headerlink" href="#envvar-hostname" title="Link to this definition">¶</a></dt>
<dd><p>the machine’s hostname.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-IFS">
<span class="sig-name descname"><span class="pre">IFS</span></span><a class="headerlink" href="#envvar-IFS" title="Link to this definition">¶</a></dt>
<dd><p>the internal field separator that is used for word splitting with the <a class="reference internal" href="cmds/read.html"><span class="doc">read</span></a> builtin. Setting this to the empty string will also disable line splitting in <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitution</span></a>. This variable can be changed.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-last_pid">
<span class="sig-name descname"><span class="pre">last_pid</span></span><a class="headerlink" href="#envvar-last_pid" title="Link to this definition">¶</a></dt>
<dd><p>the process ID (PID) of the last background process.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-PWD">
<span class="sig-name descname"><span class="pre">PWD</span></span><a class="headerlink" href="#envvar-PWD" title="Link to this definition">¶</a></dt>
<dd><p>the current working directory.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-pipestatus">
<span class="sig-name descname"><span class="pre">pipestatus</span></span><a class="headerlink" href="#envvar-pipestatus" title="Link to this definition">¶</a></dt>
<dd><p>a list of exit statuses of all processes that made up the last executed pipe. See <a class="reference internal" href="#variables-status"><span class="std std-ref">exit status</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-SHLVL">
<span class="sig-name descname"><span class="pre">SHLVL</span></span><a class="headerlink" href="#envvar-SHLVL" title="Link to this definition">¶</a></dt>
<dd><p>the level of nesting of shells. Fish increments this in interactive shells, otherwise it only passes it along.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-status">
<span class="sig-name descname"><span class="pre">status</span></span><a class="headerlink" href="#envvar-status" title="Link to this definition">¶</a></dt>
<dd><p>the <a class="reference internal" href="#variables-status"><span class="std std-ref">exit status</span></a> of the last foreground job to exit. If the job was terminated through a signal, the exit status will be 128 plus the signal number.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-status_generation">
<span class="sig-name descname"><span class="pre">status_generation</span></span><a class="headerlink" href="#envvar-status_generation" title="Link to this definition">¶</a></dt>
<dd><p>the “generation” count of <code class="docutils literal notranslate"><span class="pre">$status</span></code>. This will be incremented only when the previous command produced an explicit status. (For example, background jobs will not increment this).</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-USER">
<span class="sig-name descname"><span class="pre">USER</span></span><a class="headerlink" href="#envvar-USER" title="Link to this definition">¶</a></dt>
<dd><p>the current username. This variable can be changed.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-EUID">
<span class="sig-name descname"><span class="pre">EUID</span></span><a class="headerlink" href="#envvar-EUID" title="Link to this definition">¶</a></dt>
<dd><p>the current effective user id, set by fish at startup. This variable can be changed.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-version">
<span class="sig-name descname"><span class="pre">version</span></span><a class="headerlink" href="#envvar-version" title="Link to this definition">¶</a></dt>
<dd><p>the version of the currently running fish (also available as <code class="docutils literal notranslate"><span class="pre">FISH_VERSION</span></code> for backward compatibility).</p>
</dd></dl>
<p>As a convention, an uppercase name is usually used for exported variables, while lowercase variables are not exported. (<code class="docutils literal notranslate"><span class="pre">CMD_DURATION</span></code> is an exception for historical reasons). This rule is not enforced by fish, but it is good coding practice to use casing to distinguish between exported and unexported variables.</p>
<p>Fish also uses some variables internally, their name usually starting with <code class="docutils literal notranslate"><span class="pre">__fish</span></code>. These are internal and should not typically be modified directly.</p>
</section>
<section id="the-status-variable">
<span id="variables-status"></span><h3>The status variable<a class="headerlink" href="#the-status-variable" title="Link to this heading">¶</a></h3>
<p>Whenever a process exits, an exit status is returned to the program that started it (usually the shell). This exit status is an integer number, which tells the calling application how the execution of the command went. In general, a zero exit status means that the command executed without problem, but a non-zero exit status means there was some form of problem.</p>
<p>Fish stores the exit status of the last process in the last job to exit in the <code class="docutils literal notranslate"><span class="pre">status</span></code> variable.</p>
<p>If fish encounters a problem while executing a command, the status variable may also be set to a specific value:</p>
<ul class="simple">
<li><p>0 is generally the exit status of commands if they successfully performed the requested operation.</p></li>
<li><p>1 is generally the exit status of commands if they failed to perform the requested operation.</p></li>
<li><p>121 is generally the exit status of commands if they were supplied with invalid arguments.</p></li>
<li><p>123 means that the command was not executed because the command name contained invalid characters.</p></li>
<li><p>124 means that the command was not executed because none of the wildcards in the command produced any matches.</p></li>
<li><p>125 means that while an executable with the specified name was located, the operating system could not actually execute the command.</p></li>
<li><p>126 means that while a file with the specified name was located, it was not executable.</p></li>
<li><p>127 means that no function, builtin or command with the given name could be located.</p></li>
</ul>
<p>If a process exits through a signal, the exit status will be 128 plus the number of the signal.</p>
<p>The status can be negated with <a class="reference internal" href="cmds/not.html"><span class="doc">not</span></a> (or <code class="docutils literal notranslate"><span class="pre">!</span></code>), which is useful in a <a class="reference internal" href="#syntax-conditional"><span class="std std-ref">condition</span></a>. This turns a status of 0 into 1 and any non-zero status into 0.</p>
<p>There is also <code class="docutils literal notranslate"><span class="pre">$pipestatus</span></code>, which is a list of all <code class="docutils literal notranslate"><span class="pre">status</span></code> values of processes in a pipe. One difference is that <a class="reference internal" href="cmds/not.html"><span class="doc">not</span></a> applies to <code class="docutils literal notranslate"><span class="pre">$status</span></code>, but not <code class="docutils literal notranslate"><span class="pre">$pipestatus</span></code>, because it loses information.</p>
<p>For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="o">not</span><span class="w"> </span><span class="nf">cat</span><span class="w"> </span><span class="no">file</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">grep</span><span class="w"> </span><span class="no">-q</span><span class="w"> </span><span class="no">fish</span>
<span class="nf">echo</span><span class="w"> </span><span class="no">status</span><span class="w"> </span><span class="no">is:</span><span class="w"> </span><span class="o">$status</span><span class="w"> </span><span class="no">pipestatus</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="o">$pipestatus</span>
</pre></div>
</div>
<p>Here <code class="docutils literal notranslate"><span class="pre">$status</span></code> reflects the status of <code class="docutils literal notranslate"><span class="pre">grep</span></code>, which returns 0 if it found something, negated with <code class="docutils literal notranslate"><span class="pre">not</span></code> (so 1 if it found something, 0 otherwise). <code class="docutils literal notranslate"><span class="pre">$pipestatus</span></code> reflects the status of <code class="docutils literal notranslate"><span class="pre">cat</span></code> (which returns non-zero for example when it couldn’t find the file) and <code class="docutils literal notranslate"><span class="pre">grep</span></code>, without the negation.</p>
<p>So if both <code class="docutils literal notranslate"><span class="pre">cat</span></code> and <code class="docutils literal notranslate"><span class="pre">grep</span></code> succeeded, <code class="docutils literal notranslate"><span class="pre">$status</span></code> would be 1 because of the <code class="docutils literal notranslate"><span class="pre">not</span></code>, and <code class="docutils literal notranslate"><span class="pre">$pipestatus</span></code> would be 0 and 0.</p>
<p>It’s possible for the first command to fail while the second succeeds. One common example is when the second program quits early.</p>
<p>For example, if you have a pipeline like:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">cat</span><span class="w"> </span><span class="no">file1</span><span class="w"> </span><span class="no">file2</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">head</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">50</span>
</pre></div>
</div>
<p>This will tell <code class="docutils literal notranslate"><span class="pre">cat</span></code> to print two files, “file1” and “file2”, one after the other, and the <code class="docutils literal notranslate"><span class="pre">head</span></code> will then only print the first 50 lines. In this case you might often see this constellation:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">cat</span><span class="w"> </span><span class="no">file1</span><span class="w"> </span><span class="no">file2</span><span class="w"> </span><span class="p">|</span><span class="w"> </span><span class="nf">head</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="no">50</span>
<span class="go"># 50 lines of output</span>
<span class="gp">> </span><span class="nf">echo</span><span class="w"> </span><span class="o">$pipestatus</span>
<span class="go">141 0</span>
</pre></div>
</div>
<p>Here, the “141” signifies that <code class="docutils literal notranslate"><span class="pre">cat</span></code> was killed by signal number 13 (128 + 13 == 141) - a <code class="docutils literal notranslate"><span class="pre">SIGPIPE</span></code>. You can also use <span class="target" id="index-24"></span><a class="reference internal" href="#envvar-fish_kill_signal"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_kill_signal</span></code></a> to see the signal number. This happens because it was still working, and then <code class="docutils literal notranslate"><span class="pre">head</span></code> closed the pipe, so <code class="docutils literal notranslate"><span class="pre">cat</span></code> received a signal that it didn’t ignore and so it died.</p>
<p>Whether <code class="docutils literal notranslate"><span class="pre">cat</span></code> here will see a SIGPIPE depends on how long the file is and how much it writes at once, so you might see a pipestatus of “0 0”, depending on the implementation. This is a general unix issue and not specific to fish. Some shells feature a “pipefail” feature that will call a pipeline failed if one of the processes in it failed, and this is a big problem with it.</p>
</section>
<section id="locale-variables">
<span id="variables-locale"></span><h3>Locale Variables<a class="headerlink" href="#locale-variables" title="Link to this heading">¶</a></h3>
<p>The “locale” of a program is its set of language and regional settings.
In UNIX, these are made up of several categories. The categories used by fish are:</p>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-LANG">
<span class="sig-name descname"><span class="pre">LANG</span></span><a class="headerlink" href="#envvar-LANG" title="Link to this definition">¶</a></dt>
<dd><p>This is the typical environment variable for specifying a locale.
A user may set this variable to express the language they speak, their region, and a character encoding.
The encoding part is ignored, fish always assumes UTF-8. The actual values are specific to their platform, except for special values like <code class="docutils literal notranslate"><span class="pre">C</span></code> or <code class="docutils literal notranslate"><span class="pre">POSIX</span></code>.</p>
<p>The value of <code class="docutils literal notranslate"><span class="pre">LANG</span></code> is used for each category unless the variable for that category was set or <code class="docutils literal notranslate"><span class="pre">LC_ALL</span></code> is set. So typically you only need to set LANG.</p>
<p>Example values are <code class="docutils literal notranslate"><span class="pre">en_US.UTF-8</span></code> for the American English or <code class="docutils literal notranslate"><span class="pre">de_AT.UTF-8</span></code> for Austrian German.
Your operating system might have a <code class="docutils literal notranslate"><span class="pre">locale</span></code> command that you can call as <code class="docutils literal notranslate"><span class="pre">locale</span> <span class="pre">-a</span></code> to see a list of defined locales.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-LANGUAGE">
<span class="sig-name descname"><span class="pre">LANGUAGE</span></span><a class="headerlink" href="#envvar-LANGUAGE" title="Link to this definition">¶</a></dt>
<dd><p>This is treated like <span class="target" id="index-25"></span><a class="reference internal" href="#envvar-LC_MESSAGES"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LC_MESSAGES</span></code></a> except that it can hold multiple values,
which allows to specify a priority list of languages for translation.
It’s a <a class="reference internal" href="#variables-path"><span class="std std-ref">PATH variable</span></a>, like in <a class="reference external" href="https://www.gnu.org/software/gettext/manual/html_node/The-LANGUAGE-variable.html">GNU gettext</a>.</p>
<p>Language identifiers without a region specified (e.g. <code class="docutils literal notranslate"><span class="pre">zh</span></code>) result in all available variants of this language being tried in arbitrary order.
In this example, we might first look for messages in the <code class="docutils literal notranslate"><span class="pre">zh_CN</span></code> catalog, followed by <code class="docutils literal notranslate"><span class="pre">zh_TW</span></code>, or the other way around.
This is different from GNU gettext, which uses a “default” variant of the language instead.
If you prefer a certain variant, specify it earlier in the list,
e.g. <code class="docutils literal notranslate"><span class="pre">zh_TW:zh</span></code> if your preferred language is <code class="docutils literal notranslate"><span class="pre">zh_TW</span></code>, and you prefer any other variants of <code class="docutils literal notranslate"><span class="pre">zh</span></code> over the English default.
If <code class="docutils literal notranslate"><span class="pre">zh_TW</span></code> is the only variant of <code class="docutils literal notranslate"><span class="pre">zh</span></code> you want,
specifying <code class="docutils literal notranslate"><span class="pre">zh_TW</span></code> in the <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> variable will result in messages which are not available in <code class="docutils literal notranslate"><span class="pre">zh_TW</span></code> being displayed in English.</p>
<p>See also <a class="reference internal" href="cmds/_.html"><span class="doc">builtin _ (underscore)</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-LC_ALL">
<span class="sig-name descname"><span class="pre">LC_ALL</span></span><a class="headerlink" href="#envvar-LC_ALL" title="Link to this definition">¶</a></dt>
<dd><p>Overrides the <span class="target" id="index-26"></span><a class="reference internal" href="#envvar-LANG"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">LANG</span></code></a> and all other <code class="docutils literal notranslate"><span class="pre">LC_*</span></code> variables.
Please use <code class="docutils literal notranslate"><span class="pre">LC_ALL</span></code> only as a temporary override.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-LC_MESSAGES">
<span class="sig-name descname"><span class="pre">LC_MESSAGES</span></span><a class="headerlink" href="#envvar-LC_MESSAGES" title="Link to this definition">¶</a></dt>
<dd><p>Determines the language in which messages are displayed, see <a class="reference internal" href="cmds/_.html"><span class="doc">builtin _ (underscore)</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-LC_NUMERIC">
<span class="sig-name descname"><span class="pre">LC_NUMERIC</span></span><a class="headerlink" href="#envvar-LC_NUMERIC" title="Link to this definition">¶</a></dt>
<dd><p>Sets the locale for <a class="reference internal" href="cmds/printf.html"><span class="doc">formatting numbers</span></a>.</p>
</dd></dl>
<dl class="std envvar">
<dt class="sig sig-object std" id="envvar-LC_TIME">
<span class="sig-name descname"><span class="pre">LC_TIME</span></span><a class="headerlink" href="#envvar-LC_TIME" title="Link to this definition">¶</a></dt>
<dd><p>Determines how date and time are displayed.
Used in the <a class="reference internal" href="cmds/history.html#history-show-time"><span class="std std-ref">history</span></a> builtin.</p>
</dd></dl>
</section>
</section>
<section id="builtin-commands">
<span id="builtin-overview"></span><h2>Builtin commands<a class="headerlink" href="#builtin-commands" title="Link to this heading">¶</a></h2>
<p>Fish includes a number of commands in the shell directly. We call these “builtins”. These include:</p>
<ul class="simple">
<li><p>Builtins that manipulate the shell state - <a class="reference internal" href="cmds/cd.html"><span class="doc">cd</span></a> changes directory, <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a> sets variables</p></li>
<li><p>Builtins for dealing with data, like <a class="reference internal" href="cmds/string.html"><span class="doc">string</span></a> for strings and <a class="reference internal" href="cmds/math.html"><span class="doc">math</span></a> for numbers, <a class="reference internal" href="cmds/count.html"><span class="doc">count</span></a> for counting lines or arguments, <a class="reference internal" href="cmds/path.html"><span class="doc">path</span></a> for dealing with path</p></li>
<li><p><a class="reference internal" href="cmds/status.html"><span class="doc">status</span></a> for asking about the shell’s status</p></li>
<li><p><a class="reference internal" href="cmds/printf.html"><span class="doc">printf</span></a> and <a class="reference internal" href="cmds/echo.html"><span class="doc">echo</span></a> for creating output</p></li>
<li><p><a class="reference internal" href="cmds/test.html"><span class="doc">test</span></a> for checking conditions</p></li>
<li><p><a class="reference internal" href="cmds/argparse.html"><span class="doc">argparse</span></a> for parsing function arguments</p></li>
<li><p><a class="reference internal" href="cmds/source.html"><span class="doc">source</span></a> to read a script in the current shell (so changes to variables stay) and <a class="reference internal" href="cmds/eval.html"><span class="doc">eval</span></a> to execute a string as script</p></li>
<li><p><a class="reference internal" href="cmds/random.html"><span class="doc">random</span></a> to get random numbers or pick a random element from a list</p></li>
<li><p><a class="reference internal" href="cmds/read.html"><span class="doc">read</span></a> for reading from a pipe or the terminal</p></li>
</ul>
<p>For a list of all builtins, use <code class="docutils literal notranslate"><span class="pre">builtin</span> <span class="pre">-n</span></code>.</p>
<p>For a list of all builtins, functions and commands shipped with fish, see the <a class="reference internal" href="commands.html"><span class="doc">list of commands</span></a>. The documentation is also available by using the <code class="docutils literal notranslate"><span class="pre">--help</span></code> switch.</p>
</section>
<section id="command-lookup">
<h2>Command lookup<a class="headerlink" href="#command-lookup" title="Link to this heading">¶</a></h2>
<p>When fish is told to run something, it goes through multiple steps to find it.</p>
<p>If it contains a <code class="docutils literal notranslate"><span class="pre">/</span></code>, fish tries to execute the given file, from the current directory on.</p>
<p>If it doesn’t contain a <code class="docutils literal notranslate"><span class="pre">/</span></code>, it could be a function, builtin, or external command, and so fish goes through the full lookup.</p>
<p>In order:</p>
<ol class="arabic simple">
<li><p>It tries to resolve it as a <a class="reference internal" href="#syntax-function"><span class="std std-ref">function</span></a>.</p>
<ul class="simple">
<li><p>If the function is already known, it uses that</p></li>
<li><p>If there is a file of the name with a “.fish” suffix in <span class="target" id="index-27"></span><a class="reference internal" href="#envvar-fish_function_path"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_function_path</span></code></a>, it <a class="reference internal" href="#syntax-function-autoloading"><span class="std std-ref">loads that</span></a>. (If there is more than one file only the first is used)</p></li>
<li><p>If the function is now defined it uses that</p></li>
</ul>
</li>
<li><p>It tries to resolve it as a <a class="reference internal" href="#builtin-overview"><span class="std std-ref">builtin</span></a>.</p></li>
<li><p>It tries to find an executable file in <span class="target" id="index-28"></span><a class="reference internal" href="#envvar-PATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PATH</span></code></a>.</p>
<ul class="simple">
<li><p>If it finds a file, it tells the kernel to run it.</p></li>
<li><p>If the kernel knows how to run the file (e.g. via a <code class="docutils literal notranslate"><span class="pre">#!</span></code> line - <code class="docutils literal notranslate"><span class="pre">#!/bin/sh</span></code> or <code class="docutils literal notranslate"><span class="pre">#!/usr/bin/python</span></code>), it does it.</p></li>
<li><p>If the kernel reports that it couldn’t run it because of a missing interpreter, and the file passes a rudimentary check, fish tells <code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code> to run it.</p></li>
</ul>
</li>
</ol>
<p>If none of these work, fish runs the function <a class="reference internal" href="cmds/fish_command_not_found.html"><span class="doc">fish_command_not_found</span></a> and sets <span class="target" id="index-29"></span><a class="reference internal" href="#envvar-status"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">status</span></code></a> to 127.</p>
<p>You can use <a class="reference internal" href="cmds/type.html"><span class="doc">type</span></a> to see how fish resolved something:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">type</span><span class="w"> </span><span class="no">--short</span><span class="w"> </span><span class="no">--all</span><span class="w"> </span><span class="no">echo</span>
<span class="go">echo is a builtin</span>
<span class="go">echo is /usr/bin/echo</span>
</pre></div>
</div>
</section>
<section id="querying-for-user-input">
<span id="user-input"></span><h2>Querying for user input<a class="headerlink" href="#querying-for-user-input" title="Link to this heading">¶</a></h2>
<p>Sometimes, you want to ask the user for input, for instance to confirm something. This can be done with the <a class="reference internal" href="cmds/read.html"><span class="doc">read</span></a> builtin.</p>
<p>Let’s make up an example. This function will <a class="reference internal" href="#expand-wildcard"><span class="std std-ref">glob</span></a> the files in all the directories it gets as <a class="reference internal" href="#variables-argv"><span class="std std-ref">arguments</span></a>, and <a class="reference internal" href="#syntax-conditional"><span class="std std-ref">if</span></a> there are <a class="reference internal" href="cmds/test.html"><span class="doc">more than five</span></a> it will ask the user if it is supposed to show them, but only if it is connected to a terminal:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">show_files</span>
<span class="w"> </span><span class="c"># This will glob on all arguments. Any non-directories will be ignored.</span>
<span class="w"> </span><span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">files</span><span class="w"> </span><span class="o">$argv</span><span class="no">/</span><span class="o">*</span>
<span class="w"> </span><span class="c"># If there are more than 5 files</span>
<span class="w"> </span><span class="nf">if</span><span class="w"> </span><span class="nf">test</span><span class="w"> </span><span class="o">(</span><span class="nf">count</span><span class="w"> </span><span class="o">$files)</span><span class="w"> </span><span class="no">-gt</span><span class="w"> </span><span class="no">5</span>
<span class="w"> </span><span class="c"># and both stdin (for reading input)</span>
<span class="w"> </span><span class="c"># and stdout (for writing the prompt)</span>
<span class="w"> </span><span class="c"># are terminals</span>
<span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">isatty</span><span class="w"> </span><span class="no">stdin</span>
<span class="w"> </span><span class="o">and</span><span class="w"> </span><span class="nf">isatty</span><span class="w"> </span><span class="no">stdout</span>
<span class="w"> </span><span class="c"># Keep asking until we get a valid response</span>
<span class="w"> </span><span class="nf">while</span><span class="w"> </span><span class="nf">read</span><span class="w"> </span><span class="no">--nchars</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">response</span><span class="w"> </span><span class="no">--prompt-str=</span><span class="s2">"Are you sure? (y/n)"</span>
<span class="w"> </span><span class="o">or</span><span class="w"> </span><span class="nf">return</span><span class="w"> </span><span class="no">1</span><span class="w"> </span><span class="c"># if the read was aborted with ctrl-c/ctrl-d</span>
<span class="w"> </span><span class="nf">switch</span><span class="w"> </span><span class="o">$response</span>
<span class="w"> </span><span class="nf">case</span><span class="w"> </span><span class="no">y</span><span class="w"> </span><span class="no">Y</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Okay</span>
<span class="w"> </span><span class="c"># We break out of the while and go on with the function</span>
<span class="w"> </span><span class="nf">break</span>
<span class="w"> </span><span class="nf">case</span><span class="w"> </span><span class="no">n</span><span class="w"> </span><span class="no">N</span>
<span class="w"> </span><span class="c"># We return from the function without printing</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Not</span><span class="w"> </span><span class="no">showing</span>
<span class="w"> </span><span class="nf">return</span><span class="w"> </span><span class="no">1</span>
<span class="w"> </span><span class="nf">case</span><span class="w"> </span><span class="s1">'*'</span>
<span class="w"> </span><span class="c"># We go through the while loop and ask again</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Not</span><span class="w"> </span><span class="no">valid</span><span class="w"> </span><span class="no">input</span>
<span class="w"> </span><span class="nf">continue</span>
<span class="w"> </span><span class="nf">end</span>
<span class="w"> </span><span class="nf">end</span>
<span class="w"> </span><span class="nf">end</span>
<span class="w"> </span><span class="c"># And now we print the files</span>
<span class="w"> </span><span class="nf">printf</span><span class="w"> </span><span class="s1">'%s\n'</span><span class="w"> </span><span class="o">$files</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>If you run this as <code class="docutils literal notranslate"><span class="pre">show_files</span> <span class="pre">/</span></code>, it will most likely ask you until you press Y/y or N/n. If you run this as <code class="docutils literal notranslate"><span class="pre">show_files</span> <span class="pre">/</span> <span class="pre">|</span> <span class="pre">cat</span></code>, it will print the files without asking. If you run this as <code class="docutils literal notranslate"><span class="pre">show_files</span> <span class="pre">.</span></code>, it might print something without asking because there are fewer than five files.</p>
</section>
<section id="shell-variable-and-function-names">
<h2>Shell variable and function names<a class="headerlink" href="#shell-variable-and-function-names" title="Link to this heading">¶</a></h2>
<p>The names given to variables and functions (so-called “identifiers”) have to follow certain rules:</p>
<ul class="simple">
<li><p>A variable name cannot be empty. It can contain only letters, digits, and underscores. It may begin and end with any of those characters.</p></li>
<li><p>A function name cannot be empty. It may not begin with a hyphen (“-”) and may not contain a slash (“/”). All other characters, including a space, are valid. A function name also can’t be the same as a reserved keyword or essential builtin like <code class="docutils literal notranslate"><span class="pre">if</span></code> or <code class="docutils literal notranslate"><span class="pre">set</span></code>.</p></li>
<li><p>A bind mode name (e.g., <code class="docutils literal notranslate"><span class="pre">bind</span> <span class="pre">-m</span> <span class="pre">abc</span> <span class="pre">...</span></code>) must be a valid variable name.</p></li>
</ul>
<p>Other things have other restrictions. For instance what is allowed for file names depends on your system, but at the very least they cannot contain a “/” (because that is the path separator) or NULL byte (because that is how UNIX ends strings).</p>
</section>
<section id="configuration-files">
<span id="configuration"></span><h2>Configuration files<a class="headerlink" href="#configuration-files" title="Link to this heading">¶</a></h2>
<p>When fish is started, it reads and runs its configuration files. Where these are depends on build configuration and environment variables.</p>
<p>The main file is <code class="docutils literal notranslate"><span class="pre">~/.config/fish/config.fish</span></code> (or more precisely <code class="docutils literal notranslate"><span class="pre">$XDG_CONFIG_HOME/fish/config.fish</span></code>).</p>
<p>Configuration files are run in the following order:</p>
<ul>
<li><p>Configuration snippets (named <code class="docutils literal notranslate"><span class="pre">*.fish</span></code>) in the directories:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">$__fish_config_dir/conf.d</span></code> (by default, <code class="docutils literal notranslate"><span class="pre">~/.config/fish/conf.d/</span></code>)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$__fish_sysconf_dir/conf.d</span></code> (by default, <code class="docutils literal notranslate"><span class="pre">/etc/fish/conf.d/</span></code>)</p></li>
<li><p>Directories for others to ship configuration snippets for their software:</p>
<ul class="simple">
<li><p>the directories under <code class="docutils literal notranslate"><span class="pre">$__fish_user_data_dir</span></code> (usually <code class="docutils literal notranslate"><span class="pre">~/.local/share/fish</span></code>, controlled by the <code class="docutils literal notranslate"><span class="pre">XDG_DATA_HOME</span></code> environment variable)</p></li>
<li><p>a <code class="docutils literal notranslate"><span class="pre">fish/vendor_conf.d</span></code> directory in the directories listed in <code class="docutils literal notranslate"><span class="pre">$XDG_DATA_DIRS</span></code> (default <code class="docutils literal notranslate"><span class="pre">/usr/share/fish/vendor_conf.d</span></code> and <code class="docutils literal notranslate"><span class="pre">/usr/local/share/fish/vendor_conf.d</span></code>)</p></li>
</ul>
<p>These directories are also accessible in <code class="docutils literal notranslate"><span class="pre">$__fish_vendor_confdirs</span></code>.
Note that changing that in a running fish won’t do anything as by that point the directories have already been read.</p>
</li>
</ul>
<p>If there are multiple files with the same name in these directories, only the first will be executed.
They are executed in order of their filename, sorted (like globs) in a natural order (i.e. “01” sorts before “2”).</p>
</li>
<li><p>System-wide configuration files, where administrators can include initialization for all users on the system - similar to <code class="docutils literal notranslate"><span class="pre">/etc/profile</span></code> for POSIX-style shells - in <code class="docutils literal notranslate"><span class="pre">$__fish_sysconf_dir</span></code> (usually <code class="docutils literal notranslate"><span class="pre">/etc/fish/config.fish</span></code>).</p></li>
<li><p>User configuration, usually in <code class="docutils literal notranslate"><span class="pre">~/.config/fish/config.fish</span></code> (controlled by the <code class="docutils literal notranslate"><span class="pre">XDG_CONFIG_HOME</span></code> environment variable, and accessible as <code class="docutils literal notranslate"><span class="pre">$__fish_config_dir</span></code>).</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">~/.config/fish/config.fish</span></code> is sourced <em>after</em> the snippets. This is so you can copy snippets and override some of their behavior.</p>
<p>These files are all executed on the startup of every shell. If you want to run a command only on starting an interactive shell, use the exit status of the command <code class="docutils literal notranslate"><span class="pre">status</span> <span class="pre">--is-interactive</span></code> to determine if the shell is interactive. If you want to run a command only when using a login shell, use <code class="docutils literal notranslate"><span class="pre">status</span> <span class="pre">--is-login</span></code> instead. This will speed up the starting of non-interactive or non-login shells.</p>
<p>If you are developing another program, you may want to add configuration for all users of fish on a system. This is discouraged; if not carefully written, they may have side-effects or slow the startup of the shell. Additionally, users of other shells won’t benefit from the fish-specific configuration. However, if they are required, you can install them to the “vendor” configuration directory. As this path may vary from system to system, <code class="docutils literal notranslate"><span class="pre">pkg-config</span></code> should be used to discover it: <code class="docutils literal notranslate"><span class="pre">pkg-config</span> <span class="pre">--variable</span> <span class="pre">confdir</span> <span class="pre">fish</span></code>.</p>
<p>For system integration, fish also ships a file called <code class="docutils literal notranslate"><span class="pre">__fish_build_paths.fish</span></code>. This can be customized during build, for instance because your system requires special paths to be used.</p>
</section>
<section id="future-feature-flags">
<span id="featureflags"></span><h2>Future feature flags<a class="headerlink" href="#future-feature-flags" title="Link to this heading">¶</a></h2>
<p>Feature flags are how fish stages changes that might break scripts. Breaking changes are introduced as opt-in, in a few releases they become opt-out, and eventually the old behavior is removed.</p>
<p>You can see the current list of features via <code class="docutils literal notranslate"><span class="pre">status</span> <span class="pre">features</span></code>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">status</span><span class="w"> </span><span class="no">features</span>
<span class="go">stderr-nocaret on 3.0 ^ no longer redirects stderr</span>
<span class="go">qmark-noglob on 3.0 ? no longer globs</span>
<span class="go">regex-easyesc on 3.1 string replace -r needs fewer \\'s</span>
<span class="go">ampersand-nobg-in-token on 3.4 & only backgrounds if followed by a separating character</span>
<span class="go">remove-percent-self off 4.0 %self is no longer expanded (use $fish_pid)</span>
<span class="go">test-require-arg off 4.0 builtin test requires an argument</span>
<span class="go">mark-prompt on 4.0 write OSC 133 prompt markers to the terminal</span>
<span class="go">ignore-terminfo on 4.1 do not look up $TERM in terminfo database</span>
<span class="go">query-term on 4.1 query the TTY to enable extra functionality</span>
</pre></div>
</div>
<p>Here is what they mean:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">stderr-nocaret</span></code> was introduced in fish 3.0 and cannot be turned off since fish 3.5. It can still be tested for compatibility, but a <code class="docutils literal notranslate"><span class="pre">no-stderr-nocaret</span></code> value will be ignored. The flag made <code class="docutils literal notranslate"><span class="pre">^</span></code> an ordinary character instead of denoting an stderr redirection. Use <code class="docutils literal notranslate"><span class="pre">2></span></code> instead.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">qmark-noglob</span></code> was also introduced in fish 3.0 (and made the default in 4.0). It makes <code class="docutils literal notranslate"><span class="pre">?</span></code> an ordinary character instead of a single-character glob. Use a <code class="docutils literal notranslate"><span class="pre">*</span></code> instead (which will match multiple characters) or find other ways to match files like <code class="docutils literal notranslate"><span class="pre">find</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">regex-easyesc</span></code> was introduced in 3.1 (and made the default in 3.5). It makes it so the replacement expression in <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span> <span class="pre">-r</span></code> does one fewer round of escaping. Before, to escape a backslash you would have to use <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span> <span class="pre">-ra</span> <span class="pre">'([ab])'</span> <span class="pre">'\\\\\\\\$1'</span></code>. After, just <code class="docutils literal notranslate"><span class="pre">'\\\\$1'</span></code> is enough. Check your <code class="docutils literal notranslate"><span class="pre">string</span> <span class="pre">replace</span></code> calls if you use this anywhere.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ampersand-nobg-in-token</span></code> was introduced in fish 3.4 (and made the default in 3.5). It makes it so a <code class="docutils literal notranslate"><span class="pre">&</span></code> i no longer interpreted as the backgrounding operator in the middle of a token, so dealing with URLs becomes easier. Either put spaces or a semicolon after the <code class="docutils literal notranslate"><span class="pre">&</span></code>. This is recommended formatting anyway, and <code class="docutils literal notranslate"><span class="pre">fish_indent</span></code> will have done it for you already.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">remove-percent-self</span></code> turns off the special <code class="docutils literal notranslate"><span class="pre">%self</span></code> expansion. It was introduced in 4.0. To get fish’s pid, you can use the <span class="target" id="index-30"></span><a class="reference internal" href="#envvar-fish_pid"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_pid</span></code></a> variable.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">test-require-arg</span></code> removes <a class="reference internal" href="cmds/test.html"><span class="doc">builtin test</span></a>’s one-argument form (<code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">"string"</span></code>. It was introduced in 4.0. To test if a string is non-empty, use <code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">-n</span> <span class="pre">"string"</span></code>. If disabled, any call to <code class="docutils literal notranslate"><span class="pre">test</span></code> that would change sends a <a class="reference internal" href="cmds/fish.html#debugging-fish"><span class="std std-ref">debug message</span></a> of category “deprecated-test”, so starting fish with <code class="docutils literal notranslate"><span class="pre">fish</span> <span class="pre">--debug=deprecated-test</span></code> can be used to find offending calls.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mark-prompt</span></code> makes fish report to the terminal the beginning and and of both shell prompts and command output.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ignore-terminfo</span></code> disables lookup of $TERM in the terminfo database. Use <code class="docutils literal notranslate"><span class="pre">no-ignore-terminfo</span></code> to turn it back on.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">query-term</span></code> allows fish to query the terminal by writing escape sequences and reading the terminal’s response.
This enables features such as <a class="reference internal" href="terminal-compatibility.html#term-compat-cursor-position-report"><span class="std std-ref">scrolling</span></a>.
If you use an incompatible terminal, you can -- for the time being -- work around it by running (once) <code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">-Ua</span> <span class="pre">fish_features</span> <span class="pre">no-query-term</span></code>.</p></li>
</ul>
<p>These changes are introduced off by default. They can be enabled on a per session basis:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">fish</span><span class="w"> </span><span class="no">--features</span><span class="w"> </span><span class="no">qmark-noglob,regex-easyesc</span>
</pre></div>
</div>
<p>or opted into globally for a user:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">set</span><span class="w"> </span><span class="no">-U</span><span class="w"> </span><span class="no">fish_features</span><span class="w"> </span><span class="no">regex-easyesc</span><span class="w"> </span><span class="no">qmark-noglob</span>
</pre></div>
</div>
<p>Features will only be set on startup, so this variable will only take effect if it is universal or exported.</p>
<p>You can also use the version as a group, so <code class="docutils literal notranslate"><span class="pre">3.0</span></code> is equivalent to “stderr-nocaret” and “qmark-noglob”. Instead of a version, the special group <code class="docutils literal notranslate"><span class="pre">all</span></code> enables all features.</p>
<p>Prefixing a feature with <code class="docutils literal notranslate"><span class="pre">no-</span></code> turns it off instead. E.g. to reenable the <code class="docutils literal notranslate"><span class="pre">?</span></code> single-character glob:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">set</span><span class="w"> </span><span class="no">-Ua</span><span class="w"> </span><span class="no">fish_features</span><span class="w"> </span><span class="no">no-qmark-noglob</span>
</pre></div>
</div>
</section>
<section id="event-handlers">
<span id="event"></span><h2>Event handlers<a class="headerlink" href="#event-handlers" title="Link to this heading">¶</a></h2>
<p>When defining a new function in fish, it is possible to make it into an event handler, i.e. a function that is automatically run when a specific event takes place. Events that can trigger a handler currently are:</p>
<ul class="simple">
<li><p>When a signal is delivered</p></li>
<li><p>When a job exits</p></li>
<li><p>When the value of a variable is updated</p></li>
<li><p>When the prompt is about to be shown</p></li>
</ul>
<p>Example:</p>
<p>To specify a signal handler for the WINCH signal, write:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">my_signal_handler</span><span class="w"> </span><span class="no">--on-signal</span><span class="w"> </span><span class="no">WINCH</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">Got</span><span class="w"> </span><span class="no">WINCH</span><span class="w"> </span><span class="no">signal!</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>Fish already has the following named events for the <code class="docutils literal notranslate"><span class="pre">--on-event</span></code> switch:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">fish_prompt</span></code> is emitted whenever a new fish prompt is about to be displayed.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_preexec</span></code> is emitted right before executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_posterror</span></code> is emitted right after executing a command with syntax errors. The commandline is passed as the first parameter.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_postexec</span></code> is emitted right after executing an interactive command. The commandline is passed as the first parameter. Not emitted if command is empty.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_exit</span></code> is emitted right before fish exits.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_cancel</span></code> is emitted when a commandline is cleared.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_focus_in</span></code> is emitted when fish’s terminal gains focus.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">fish_focus_out</span></code> is emitted when fish’s terminal loses focus.</p></li>
</ul>
<p>Events can be fired with the <a class="reference internal" href="cmds/emit.html"><span class="doc">emit</span></a> command, and do not have to be defined before. The names just need to match. For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">function</span><span class="w"> </span><span class="no">handler</span><span class="w"> </span><span class="no">--on-event</span><span class="w"> </span><span class="no">imdone</span>
<span class="w"> </span><span class="nf">echo</span><span class="w"> </span><span class="no">generator</span><span class="w"> </span><span class="no">is</span><span class="w"> </span><span class="no">done</span><span class="w"> </span><span class="o">$argv</span>
<span class="nf">end</span>
<span class="nf">function</span><span class="w"> </span><span class="no">generator</span>
<span class="w"> </span><span class="nf">sleep</span><span class="w"> </span><span class="no">1</span>
<span class="w"> </span><span class="c"># The "imdone" is the name of the event</span>
<span class="w"> </span><span class="c"># the rest is the arguments to pass to the handler</span>
<span class="w"> </span><span class="nf">emit</span><span class="w"> </span><span class="no">imdone</span><span class="w"> </span><span class="no">with</span><span class="w"> </span><span class="o">$argv</span>
<span class="nf">end</span>
</pre></div>
</div>
<p>If there are multiple handlers for an event, they will all be run, but the order might change between fish releases, so you should not rely on it.</p>
<p>Please note that event handlers only become active when a function is loaded, which means you need to otherwise <a class="reference internal" href="cmds/source.html"><span class="doc">source</span></a> or execute a function instead of relying on <a class="reference internal" href="#syntax-function-autoloading"><span class="std std-ref">autoloading</span></a>. One approach is to put it into your <a class="reference internal" href="#configuration"><span class="std std-ref">configuration file</span></a>.</p>
<p>For more information on how to define new event handlers, see the documentation for the <a class="reference internal" href="cmds/function.html"><span class="doc">function</span></a> command.</p>
</section>
<section id="debugging-fish-scripts">
<span id="debugging"></span><h2>Debugging fish scripts<a class="headerlink" href="#debugging-fish-scripts" title="Link to this heading">¶</a></h2>
<p>Fish includes basic built-in debugging facilities that allow you to stop execution of a script at an arbitrary point. When this happens you are presented with an interactive prompt where you can execute any fish command to inspect or change state (there are no debug commands as such). For example, you can check or change the value of any variables using <a class="reference internal" href="cmds/printf.html"><span class="doc">printf</span></a> and <a class="reference internal" href="cmds/set.html"><span class="doc">set</span></a>. As another example, you can run <a class="reference internal" href="cmds/status.html"><span class="doc">status print-stack-trace</span></a> to see how the current breakpoint was reached. To resume normal execution of the script, type <a class="reference internal" href="cmds/exit.html"><span class="doc">exit</span></a> or <kbd class="kbd docutils literal notranslate">ctrl</kbd>-<kbd class="kbd docutils literal notranslate">d</kbd>.</p>
<p>To start a debug session insert the <a class="reference internal" href="cmds/breakpoint.html"><span class="doc">builtin command</span></a> <code class="docutils literal notranslate"><span class="pre">breakpoint</span></code> at the point in a function or script where you wish to gain control, then run the function or script. Also, the default action of the <code class="docutils literal notranslate"><span class="pre">TRAP</span></code> signal is to call this builtin, meaning a running script can be actively debugged by sending it the <code class="docutils literal notranslate"><span class="pre">TRAP</span></code> signal (<code class="docutils literal notranslate"><span class="pre">kill</span> <span class="pre">-s</span> <span class="pre">TRAP</span> <span class="pre"><PID></span></code>). There is limited support for interactively setting or modifying breakpoints from this debug prompt: it is possible to insert new breakpoints in (or remove old ones from) other functions by using the <code class="docutils literal notranslate"><span class="pre">funced</span></code> function to edit the definition of a function, but it is not possible to add or remove a breakpoint from the function/script currently loaded and being executed.</p>
<p>Another way to debug script issues is to set the <span class="target" id="index-31"></span><a class="reference internal" href="#envvar-fish_trace"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">fish_trace</span></code></a> variable, e.g. <code class="docutils literal notranslate"><span class="pre">fish_trace=1</span> <span class="pre">fish_prompt</span></code> to see which commands fish executes when running the <a class="reference internal" href="cmds/fish_prompt.html"><span class="doc">fish_prompt</span></a> function.</p>
<section id="profiling-fish-scripts">
<span id="profiling"></span><h3>Profiling fish scripts<a class="headerlink" href="#profiling-fish-scripts" title="Link to this heading">¶</a></h3>
<p>If you specifically want to debug performance issues, <strong class="program">fish</strong> can be run with the <code class="docutils literal notranslate"><span class="pre">--profile</span> <span class="pre">/path/to/profile.log</span></code> option to save a profile to the specified path. This profile log includes a breakdown of how long each step in the execution took.</p>
<p>For example:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">fish</span><span class="w"> </span><span class="no">--profile</span><span class="w"> </span><span class="no">/tmp/sleep.prof</span><span class="w"> </span><span class="no">-ic</span><span class="w"> </span><span class="s1">'sleep 3s'</span>
<span class="gp">> </span><span class="nf">cat</span><span class="w"> </span><span class="no">/tmp/sleep.prof</span>
<span class="go">Time Sum Command</span>
<span class="go">3003419 3003419 > sleep 3s</span>
</pre></div>
</div>
<p>This will show the time for each command itself in the first column, the time for the command and every subcommand (like any commands inside of a <a class="reference internal" href="#syntax-function"><span class="std std-ref">function</span></a> or <a class="reference internal" href="#expand-command-substitution"><span class="std std-ref">command substitutions</span></a>) in the second and the command itself in the third, separated with tabs.</p>
<p>The time is given in microseconds.</p>
<p>To see the slowest commands last, <code class="docutils literal notranslate"><span class="pre">sort</span> <span class="pre">-nk2</span> <span class="pre">/path/to/logfile</span></code> is useful.</p>
<p>For profiling fish’s startup there is also <code class="docutils literal notranslate"><span class="pre">--profile-startup</span> <span class="pre">/path/to/logfile</span></code>.</p>
<p>See <a class="reference internal" href="cmds/fish.html"><span class="doc">fish</span></a> for more information.</p>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li><img src="_static/fish.png" alt=""
style="width: 80px; height: 80px; vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://fishshell.com/">fish-shell</a> »</li>
<a href="index.html">fish-shell 4.2.1 documentation</a> »
<li class="nav-item nav-item-this"><a href="">The fish language</a></li>
<li class="right">
<div class="inline-search" role="search">
<form class="inline-search" action="search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</li>
<div id="old-docs-notice" style="display: none">
This documents an old version of fish.
<a href="../current/">See the latest release.</a>
</div>
</ul>
</div>
<div class="footer">
© Copyright fish-shell developers.
<br />
<a href="https://github.com/fish-shell/fish-shell/issues">Found a bug</a>?
<br />
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</div>
<script type="text/javascript">
FISH_DOCS_VERSION = "4.2";
function copy_to_clipboard(it) {
// Find the pre tag we're interested in.
var pre = it.target;
while (pre.tagName != "PRE") pre = pre.parentNode;
var txt = "";
// Cheesy: If we have a prompt,
// we only copy prompted lines,
// by splitting and matching and stuff
if (pre.querySelector('span.gp')) {
var texts= [];
for (var line of pre.innerText.split('\n')) {
if (line.match(/^>_?.*/)) {
texts.push(line.replace(/^>_?/, ""));
}
}
txt = texts.join("\n");
} else {
// Even cheesier: If we don't have a prompt, we remove the button text from the end.
var txt = pre.innerText.substring(0, pre.innerText.length - it.target.innerText.length).trim();
}
navigator.clipboard.writeText(txt).then(function() {
// Success - set the text to indicate it,
// then set it back after 2 seconds.
var span = pre.querySelector("button span");
if (span) {
var oldText = span.innerText;
span.innerText = "COPIED!";
setTimeout(function() {
span.innerText = oldText;
}, 2000);
}
}, function() {
});
}
(function () {
// Add copy buttons to all the codeblocks.
var codeblocks = document.querySelectorAll('div > pre');
var button = document.createElement('button');
var span = document.createElement('span');
span.innerText = "COPY";
button.appendChild(span);
for (var i of codeblocks) {
var newButton = button.cloneNode(true);
newButton.addEventListener('click', copy_to_clipboard);
i.appendChild(newButton);
}
})();
</script>
</body>
</html>
|
