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
|
<!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>Writing your own completions — 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="Writing your own prompt" href="prompt.html" />
<link rel="prev" title="Tutorial" href="tutorial.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="">Writing your own completions</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"><a class="reference internal" href="language.html">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 current"><a class="current reference internal" href="#">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="#">Writing your own completions</a><ul>
<li><a class="reference internal" href="#useful-functions-for-writing-completions">Useful functions for writing completions</a></li>
<li><a class="reference internal" href="#where-to-put-completions">Where to put completions</a></li>
</ul>
</li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="writing-your-own-completions">
<h1>Writing your own completions<a class="headerlink" href="#writing-your-own-completions" title="Link to this heading">¶</a></h1>
<p>To specify a completion, use the <code class="docutils literal notranslate"><span class="pre">complete</span></code> command. <code class="docutils literal notranslate"><span class="pre">complete</span></code> takes as a parameter the name of the command to specify a completion for. For example, to add a completion for the program <code class="docutils literal notranslate"><span class="pre">myprog</span></code>, start the completion command with <code class="docutils literal notranslate"><span class="pre">complete</span> <span class="pre">-c</span> <span class="pre">myprog</span> <span class="pre">...</span></code></p>
<p>For a complete description of the various switches accepted by the <code class="docutils literal notranslate"><span class="pre">complete</span></code> command, see the documentation for the <a class="reference internal" href="cmds/complete.html"><span class="doc">complete</span></a> builtin, or write <code class="docutils literal notranslate"><span class="pre">complete</span> <span class="pre">--help</span></code> inside the <code class="docutils literal notranslate"><span class="pre">fish</span></code> shell.</p>
<p>To provide a list of possible completions for myprog, use the <code class="docutils literal notranslate"><span class="pre">-a</span></code> switch. If <code class="docutils literal notranslate"><span class="pre">myprog</span></code> accepts the arguments start and stop, this can be specified as <code class="docutils literal notranslate"><span class="pre">complete</span> <span class="pre">-c</span> <span class="pre">myprog</span> <span class="pre">-a</span> <span class="pre">'start</span> <span class="pre">stop'</span></code>. The argument to the <code class="docutils literal notranslate"><span class="pre">-a</span></code> switch is always a single string. At completion time, it will be tokenized on spaces and tabs, and variable expansion, command substitution and other forms of parameter expansion will take place:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># If myprog can list the valid outputs with the list-outputs subcommand:</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">output</span><span class="w"> </span><span class="no">-a</span><span class="w"> </span><span class="s1">'(myprog list-outputs)'</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">fish</span></code> has a special syntax to support specifying switches accepted by a command. The switches <code class="docutils literal notranslate"><span class="pre">-s</span></code>, <code class="docutils literal notranslate"><span class="pre">-l</span></code> and <code class="docutils literal notranslate"><span class="pre">-o</span></code> are used to specify a short switch (single character, such as <code class="docutils literal notranslate"><span class="pre">-l</span></code>), a gnu style long switch (such as <code class="docutils literal notranslate"><span class="pre">--color</span></code>) and an old-style long switch (with one <code class="docutils literal notranslate"><span class="pre">-</span></code>, like <code class="docutils literal notranslate"><span class="pre">-shuffle</span></code>), respectively. If the command ‘myprog’ has an option that can be written as <code class="docutils literal notranslate"><span class="pre">-o</span></code> or <code class="docutils literal notranslate"><span class="pre">--output</span></code>, that is:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">o</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">output</span>
</pre></div>
</div>
<p>If this option takes an optional argument, you would also add <code class="docutils literal notranslate"><span class="pre">--argument</span></code> or <code class="docutils literal notranslate"><span class="pre">-a</span></code>, and give that the possible arguments:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">o</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">output</span><span class="w"> </span><span class="no">-a</span><span class="w"> </span><span class="s2">"yes no"</span>
</pre></div>
</div>
<p>This offers the arguments “yes” and “no” for:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">-o</span><span class="p"><TAB></span>
<span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">--output=</span><span class="p"><TAB></span>
</pre></div>
</div>
<p>By default, option arguments are <em>optional</em>, so the candidates are only offered directly attached like that, so they aren’t given in this case:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">-o</span><span class="w"> </span><span class="p"><TAB></span>
</pre></div>
</div>
<p>Usually options <em>require</em> a parameter, so you would give <code class="docutils literal notranslate"><span class="pre">--require-parameter</span></code> / <code class="docutils literal notranslate"><span class="pre">-r</span></code>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">o</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">output</span><span class="w"> </span><span class="no">-ra</span><span class="w"> </span><span class="s2">"yes no"</span>
</pre></div>
</div>
<p>which offers yes/no in these cases:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">-o</span><span class="p"><TAB></span>
<span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">--output=</span><span class="p"><TAB></span>
<span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">-o</span><span class="w"> </span><span class="p"><TAB></span>
<span class="gp">> </span><span class="nf">myprog</span><span class="w"> </span><span class="no">--output</span><span class="w"> </span><span class="p"><TAB></span>
</pre></div>
</div>
<p>Fish will also offer files by default, in addition to the arguments you specified. You would either inhibit file completion for a single option:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">o</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">output</span><span class="w"> </span><span class="no">--no-files</span><span class="w"> </span><span class="no">-ra</span><span class="w"> </span><span class="s2">"yes no"</span>
</pre></div>
</div>
<p>or with a specific condition:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-f</span><span class="w"> </span><span class="no">--condition</span><span class="w"> </span><span class="s1">'__fish_seen_subcommand_from somesubcommand'</span>
</pre></div>
</div>
<p>or you can disable file completions globally for the command:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-f</span>
</pre></div>
</div>
<p>If you have disabled them globally, you can enable them just for a specific condition or option with the <code class="docutils literal notranslate"><span class="pre">--force-files</span></code> / <code class="docutils literal notranslate"><span class="pre">-F</span></code> option:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># Disable files by default</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-f</span>
<span class="c"># but reenable them for --config-file</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">myprog</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">config-file</span><span class="w"> </span><span class="no">--force-files</span><span class="w"> </span><span class="no">-r</span>
</pre></div>
</div>
<p>As a more comprehensive example, here’s a commented excerpt of the completions for systemd’s <code class="docutils literal notranslate"><span class="pre">timedatectl</span></code>:</p>
<div class="highlight-fish-docs-samples notranslate"><div class="highlight"><pre><span></span><span class="c"># All subcommands that timedatectl knows - this is useful for later.</span>
<span class="nf">set</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">commands</span><span class="w"> </span><span class="no">status</span><span class="w"> </span><span class="no">set-time</span><span class="w"> </span><span class="no">set-timezone</span><span class="w"> </span><span class="no">list-timezones</span><span class="w"> </span><span class="no">set-local-rtc</span><span class="w"> </span><span class="no">set-ntp</span>
<span class="c"># Disable file completions for the entire command</span>
<span class="c"># because it does not take files anywhere</span>
<span class="c"># Note that this can be undone by using "-F".</span>
<span class="c">#</span>
<span class="c"># File completions also need to be disabled</span>
<span class="c"># if you want to have more control over what files are offered</span>
<span class="c"># (e.g. just directories, or just files ending in ".mp3").</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-f</span>
<span class="c"># This line offers the subcommands</span>
<span class="c"># -"status",</span>
<span class="c"># -"set-timezone",</span>
<span class="c"># -"set-time"</span>
<span class="c"># -"list-timezones"</span>
<span class="c"># if no subcommand has been given so far.</span>
<span class="c">#</span>
<span class="c"># The `-n`/`--condition` option takes script as a string, which it executes.</span>
<span class="c"># If it returns true, the completion is offered.</span>
<span class="c"># Here the condition is the `__fish_seen_subcommand_from` helper function.</span>
<span class="c"># It returns true if any of the given commands is used on the commandline,</span>
<span class="c"># as determined by a simple heuristic.</span>
<span class="c"># For more complex uses, you can write your own function.</span>
<span class="c"># See e.g. the git completions for an example.</span>
<span class="c">#</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="s2">"not __fish_seen_subcommand_from </span><span class="o">$commands</span><span class="s2">"</span><span class="nv"> \</span>
<span class="nv"> </span><span class="no">-a</span><span class="w"> </span><span class="s2">"status set-time set-timezone list-timezones"</span>
<span class="c"># If the "set-timezone" subcommand is used,</span>
<span class="c"># offer the output of `timedatectl list-timezones` as completions.</span>
<span class="c"># Each line of output is used as a separate candidate,</span>
<span class="c"># and anything after a tab is taken as the description.</span>
<span class="c"># It's often useful to transform command output with `string` into that form.</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="s2">"__fish_seen_subcommand_from set-timezone"</span><span class="nv"> \</span>
<span class="nv"> </span><span class="no">-a</span><span class="w"> </span><span class="s2">"(timedatectl list-timezones)"</span>
<span class="c"># Completion candidates can also be described via `-d`,</span>
<span class="c"># which is useful if the description is constant.</span>
<span class="c"># Try to keep these short, because that means the user gets to see more at once.</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="s2">"not __fish_seen_subcommand_from </span><span class="o">$commands</span><span class="s2">"</span><span class="nv"> \</span>
<span class="nv"> </span><span class="no">-a</span><span class="w"> </span><span class="s2">"set-local-rtc"</span><span class="w"> </span><span class="no">-d</span><span class="w"> </span><span class="s2">"Maintain RTC in local time"</span>
<span class="c"># We can also limit options to certain subcommands by using conditions.</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-n</span><span class="w"> </span><span class="s2">"__fish_seen_subcommand_from set-local-rtc"</span><span class="nv"> \</span>
<span class="nv"> </span><span class="no">-l</span><span class="w"> </span><span class="no">adjust-system-clock</span><span class="w"> </span><span class="no">-d</span><span class="w"> </span><span class="s1">'Synchronize system clock from the RTC'</span>
<span class="c"># These are simple options that can be used everywhere.</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-s</span><span class="w"> </span><span class="no">h</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">help</span><span class="w"> </span><span class="no">-d</span><span class="w"> </span><span class="s1">'Print a short help text and exit'</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">version</span><span class="w"> </span><span class="no">-d</span><span class="w"> </span><span class="s1">'Print a short version string and exit'</span>
<span class="nf">complete</span><span class="w"> </span><span class="no">-c</span><span class="w"> </span><span class="no">timedatectl</span><span class="w"> </span><span class="no">-l</span><span class="w"> </span><span class="no">no-pager</span><span class="w"> </span><span class="no">-d</span><span class="w"> </span><span class="s1">'Do not pipe output into a pager'</span>
</pre></div>
</div>
<p>For examples of how to write your own complex completions, study the completions in <code class="docutils literal notranslate"><span class="pre">/usr/share/fish/completions</span></code>. (The exact path depends on your chosen installation prefix and may be slightly different)</p>
<section id="useful-functions-for-writing-completions">
<h2>Useful functions for writing completions<a class="headerlink" href="#useful-functions-for-writing-completions" title="Link to this heading">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">fish</span></code> ships with several functions that may be useful when writing command-specific completions. Most of these function names begin with the string <code class="docutils literal notranslate"><span class="pre">__fish_</span></code>. Such functions are internal to <code class="docutils literal notranslate"><span class="pre">fish</span></code> and their name and interface may change in future fish versions. A few of these functions are described here.</p>
<p>Functions beginning with the string <code class="docutils literal notranslate"><span class="pre">__fish_print_</span></code> print a newline separated list of strings. For example, <code class="docutils literal notranslate"><span class="pre">__fish_print_filesystems</span></code> prints a list of all known file systems. Functions beginning with <code class="docutils literal notranslate"><span class="pre">__fish_complete_</span></code> print out a newline separated list of completions with descriptions. The description is separated from the completion by a tab character.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_complete_directories</span> <span class="pre">STRING</span> <span class="pre">DESCRIPTION</span></code> performs path completion on STRING, allowing only directories, and giving them the description DESCRIPTION.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_complete_path</span> <span class="pre">STRING</span> <span class="pre">DESCRIPTION</span></code> performs path completion on STRING, giving them the description DESCRIPTION.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_complete_groups</span></code> prints a list of all user groups with the groups members as description.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_complete_pids</span></code> prints a list of all processes IDs with the command name as description.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_complete_suffix</span> <span class="pre">SUFFIX</span></code> performs file completion but sorts files ending in SUFFIX first. This is useful in conjunction with <code class="docutils literal notranslate"><span class="pre">complete</span> <span class="pre">--keep-order</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_complete_users</span></code> prints a list of all users with their full name as description.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_print_filesystems</span></code> prints a list of all known file systems. Currently, this is a static list, and not dependent on what file systems the host operating system actually understands.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_print_hostnames</span></code> prints a list of all known hostnames. This function searches the fstab for nfs servers, ssh for known hosts and checks the <code class="docutils literal notranslate"><span class="pre">/etc/hosts</span></code> file.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">__fish_print_interfaces</span></code> prints a list of all known network interfaces.</p></li>
</ul>
</section>
<section id="where-to-put-completions">
<h2>Where to put completions<a class="headerlink" href="#where-to-put-completions" title="Link to this heading">¶</a></h2>
<p>Completions can be defined on the commandline or in a configuration file, but they can also be automatically loaded. Fish automatically searches through any directories in the list variable <code class="docutils literal notranslate"><span class="pre">$fish_complete_path</span></code>, and any completions defined are automatically loaded when needed. A completion file must have a filename consisting of the name of the command to complete and the suffix <code class="docutils literal notranslate"><span class="pre">.fish</span></code>.</p>
<p>By default, Fish searches the following for completions, using the first available file that it finds:</p>
<ul class="simple">
<li><p>A directory for end-users to keep their own completions, usually <code class="docutils literal notranslate"><span class="pre">~/.config/fish/completions</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 systems administrators to install completions for all users on the system, usually <code class="docutils literal notranslate"><span class="pre">/etc/fish/completions</span></code>;</p></li>
<li><p>A user-specified directory for third-party vendor completions, usually <code class="docutils literal notranslate"><span class="pre">~/.local/share/fish/vendor_completions.d</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 directory for third-party software vendors to ship their own completions for their software, usually <code class="docutils literal notranslate"><span class="pre">/usr/share/fish/vendor_completions.d</span></code>;</p></li>
<li><p>The completions shipped with fish, usually installed in <code class="docutils literal notranslate"><span class="pre">/usr/share/fish/completions</span></code>; and</p></li>
<li><p>Completions automatically generated from the operating system’s manual, usually stored in <code class="docutils literal notranslate"><span class="pre">~/.cache/fish/generated_completions</span></code> (controlled by <code class="docutils literal notranslate"><span class="pre">XDG_CACHE_HOME</span></code> environment variable).</p></li>
</ul>
<p>These paths are controlled by parameters set at build, install, or run time, and may vary from the defaults listed above.</p>
<p>This wide search may be confusing. If you are unsure, your completions probably belong in <code class="docutils literal notranslate"><span class="pre">~/.config/fish/completions</span></code>.</p>
<p>If you have written new completions for a common Unix command, please consider sharing your work by submitting it via the instructions in <a class="reference internal" href="index.html#more-help"><span class="std std-ref">Further help and development</span></a>.</p>
<p>If you are developing another program and would like to ship completions with your program, install them to the “vendor” completions directory. As this path may vary from system to system, the <code class="docutils literal notranslate"><span class="pre">pkgconfig</span></code> framework should be used to discover this path with the output of <code class="docutils literal notranslate"><span class="pre">pkg-config</span> <span class="pre">--variable</span> <span class="pre">completionsdir</span> <span class="pre">fish</span></code>.</p>
</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="">Writing your own completions</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>
|
