STRING-SPLIT(1)

🎀 string-split(1) — the fish-shell bestie era 🎀

okay so bestie, welcome to the fish-shell manual page for string-split. It's giving “split strings by delimiter” and honestly? iconic. Let's get into it 💅

---

🌸 NAME 🌸

string-split — split strings by delimiter. That's the whole name, no cap.

---

✨ SYNOPSIS ✨

peep the two forms, bestie:

       string split [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
                    [-q | --quiet] [-r | --right] SEP [STRING ...]
       string split0 [(-f | --fields) FIELDS [-a | --allow-empty]] [(-m | --max) MAX] [-n | --no-empty]
                     [-q | --quiet] [-r | --right] [STRING ...]

---

💅 DESCRIPTION 💅

string split splits each STRING on the separator SEP, and yes, SEP can be an empty string. Lowkey powerful.

If -m or --max is specified, at most MAX splits are done on each STRING. If -r or --right is given, splitting is performed right-to-left. That right-to-left thing is only useful in combination with -m or --max, so don't be out here using it alone and expecting magic ✨

With -n or --no-empty, empty results are excluded from consideration. For example, hello\n\nworld would expand to two strings and not three. Periodt.

Exit status: 0 if at least one split was performed, or 1 otherwise.

Use -f or --fields to print out specific fields. FIELDS is a comma-separated string of field numbers and/or spans. Each field is one-indexed, and will be printed on separate lines. If a given field does not exist, then the command exits with status 1 and does not print anything, unless --allow-empty is used.

okay so here's the flag tea:

• -f, --fields FIELDS — print out specific fields. FIELDS is comma-separated field numbers and/or spans, one-indexed, each printed on its own line. Missing field? status 1, nothing printed, unless --allow-empty is in the chat.
• -a, --allow-empty — the permission slip for -f/--fields: if a field you asked for doesn't exist, this keeps it from exiting with status 1 and printing nothing. 🫶
• -m, --max MAX — do at most MAX splits on each STRING.
• -n, --no-empty — exclude empty results from consideration, so hello\n\nworld expands to two strings, not three.
• -q, --quiet — listed in the synopsis as -q, --quiet; the page doesn't give extra detail here, so I'm not inventing lore, bestie.
• -r, --right — split right-to-left. Only useful with -m or --max, fr fr.
• SEP — the separator for string split, and it can be an empty string.
• STRING ... — the strings getting split.

See also the --delimiter option of the read <> command.

string split0 splits each STRING on the zero byte (NUL). Options are the same as string split except that no separator is given.

split0 has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as find -print0 or sort -z. See split0 examples below.

Be aware that commandline arguments cannot include NULs, so you likely want to pass to string split0 via a pipe, not a command substitution. That's the safety girlie move 💀

---

🔥 EXAMPLES 🔥

okay these are iconic, no notes:

>_ string split . example.com
example
com

>_ string split -r -m1 / /usr/local/bin/fish
/usr/local/bin
fish

>_ string split '' abc
a
b
c

>_ string split --allow-empty -f1,3-4,5 '' abcd
a
c
d

🧚 NUL Delimited Examples 🧚

>_ # Count files in a directory, without being confused by newlines.
>_ # Note: Don't use `string split0 (find . -print0)`, because arguments cannot include NUL.
>_ count (find . -print0 | string split0)
42

>_ # Sort a list of elements which may contain newlines
>_ set foo beta alpha\ngamma
>_ set foo (string join0 $foo | sort -z | string split0)
>_ string escape $foo[1]
alpha\ngamma

---

🫶 Copyright 🫶

fish-shell developers

---

mwah 💋 this was the STRING-SPLIT(1) page from fish-shell, version 4.9, dated Sep 08, 2026. go split something cute, bestie 💖