FPART(1)

🦋 fpart(1) — sort & pack files into partitions 🦋

okay bestie, welcome to FPART(1), General Commands Manual edition 💖 this is the girl who sorts your file trees and packs them into lil bags. let's go.

---

✨ NAME ✨

fpart — sort and pack files into partitions 🎀

---

✨ SYNOPSIS ✨

fpart [-h] [-V] -n num | -f files | -s size [-i infile] [-a]
      [-o outfile] [-0] [-e] [-P] [-v] [-l] [-b] [-y pattern]
      [-Y pattern] [-x pattern] [-X pattern] [-z] [-zz] [-zzz] [-Z]
      [-d depth] [-D] [-E] [-L] [-S] [-w cmd] [-W cmd] [-R cmd] [-p num]
      [-q num] [-r num] [FILE or DIR...]

---

✨ DESCRIPTION ✨

The fpart utility helps you sort file trees and pack them into bags — which we're calling "partitions" 👜✨ that's the whole vibe. it takes your messy pile of files and gives it structure. iconic behavior honestly.

---

✨ GENERAL OPTIONS ✨

• -h, --help — print help 🫶 she'll tell you what's up.
• -V, --version — print version 💅 show me the number.

---

✨ PARTITION CONTROL ✨

• -n num, --parts num — create exactly num partitions, and try to make them all the same size and hold the same number of files. balance is the moment ✨. this option cannot be used together with -f, -s or -L. no cap.
• -f files, --files files — create partitions holding at most files files or directories. this one can be used with -s and -L 🫶.
• -s size, --size size — create partitions with a max size of size bytes. when you use this, a special partition 0 may show up to handle files that just do not fit in a regular partition given your size limit (main character exception energy, we respect it). this can be used with -f and -L. also bestie you can use a human-friendly unit suffix here — k, m, g, t, p 🍓.

---

✨ INPUT CONTROL ✨

• -i infile — read the file list from infile. if infile is “-”, then the list gets read from stdin 📥.
• -a, --arbitrary — the input contains arbitrary values, so we just sort them (no filesystem crawling, we're staying in). the input has to follow the “size(blank)path” scheme. this option is incompatible with crawling-related options ⚠️.

---

✨ OUTPUT CONTROL ✨

• -o outfile — output partitions' contents to the outfile template. multiple files will get generated from that template. each outfile gets the partition number as a suffix 🔢. if outfile is “-”, then partitions get printed to stdout, with the partition number used as a prefix (so you can grep the partitions you care about, or do literally whatever you want 💅).
• -0 — end filenames with a null (’\0’) character when you're using option -o 🫧.
• -e — when adding directories (peep “DIRECTORY HANDLING”), add a trailing “/” to each directory entry 🎀.
• -P — add parent directories when closing partitions. this can be used together with -zzz to produce partitions that can be synchronized in parallel with tools like cpio(1), pax(1) or tar(1) ✨. adding parent directories at the end of each partition makes sure modification times get reapplied to directories, no matter what order the partitions get processed in. directories added that way are 0-sized and are not subject to partition counters (for example, a file limit given with option -f will be exceeded by n parent directories). also, they are not subject to inclusion/exclusion options (-y, -Y, -x, -X), and they always have a trailing “/” even if option -e hasn't been used (this simplifies symlinks handling, because we always want to add targets here, never the links themselves). heads up: this option may lead to creating duplicate directory entries when the next partition begins with a directory entry that was already added as a parent when closing the previous partition 😭. only intermediate partitions get parent directories added — not the very last one, which gets its parents through option -zzz when fts(3) crawling finishes. requires live mode (option -L) 👑.
• -v, --verbose — verbose mode (may be specified more than once) 🗣️ say it louder.

---

✨ FILESYSTEM CRAWLING CONTROL ✨

• -l — follow symbolic links (default: do not follow) 🔗.
• -b — do not cross filesystem boundaries (default: cross) 🚧.
• -y pattern, --include pattern — include files or directories matching pattern only (and discard all other files). this option may be specified several times. pattern may be a leaf (file or directory) name or a specific path. shell pattern matching characters (“[”, “]”, “*”, “?”) may be used. include patterns are ignored when computing the size of directories 👀.
• -Y pattern — same as -y but case insensitive. this option may not be available on your platform (at least FreeBSD and GNU/Linux support it, Solaris does not) ⚠️.
• -x pattern, --exclude pattern — exclude files or directories matching pattern. this can be used together with -y and -Y — in that case, exclusion is performed after. this option may be specified several times. pattern may be a leaf (file or directory) name or a specific path. shell pattern matching characters (“[”, “]”, “*”, “?”) may be used. exclude patterns also apply when computing the size of directories 🚫.
• -X pattern — same as -x but case insensitive. this option may not be available on your platform (at least FreeBSD and GNU/Linux support it, Solaris does not) ⚠️.

---

✨ DIRECTORY HANDLING ✨

• -z — pack empty directories. by default, fpart will pack files only (except when using the -d or -D options). this is useful for tools like rsync(1) so they can recreate a full file tree when used with fpart (e.g. using rsync's --files-from option) 🗂️. peep -zz if you also want to pack un-readable directories.
• -zz — treat un-readable or erroneous (partly-read) directories as empty, which causes them to get packed anyway. note that partly-read (non-empty) directories can end up being packed while some of their children have already been packed 😬.
• -zzz — pack all directories (as empty). useful when 3rd party tools need directory entries so they can update them (e.g. cpio(1), pax(1) or tar(1)) 🎀.
• -Z — pack un-readable/erroneous directories in dedicated partitions. this helps isolate erroneous parts of a filesystem 🧯. used together with the FPART_PARTERRNO variable, hooks can try to handle or work around the error. requires live mode (option -L) and option -zz (- or -zzz) 👑.
• -d depth — after a certain depth, pack directories instead of files (the directories themselves get added to partitions, instead of their content) 🕳️. you can force a specific file to be packed anyway by listing it on the command line explicitly 💅.
• -D, --leaf-dirs — implies -z. pack leaf directories: if a directory contains files only, it gets packed as a single entry 🍃. you can force a specific file to be packed anyway by listing it on the command line explicitly 💅.
• -E, --dirs-only — implies -D. pack directories only (work on a per-directory basis): in that mode, no file gets packed. instead, each directory gets packed as a single entry, with a size that is the sum of all top-level files' sizes 📁✨. you can force a specific file to be packed anyway by listing it on the command line explicitly 💅.

---

✨ LIVE MODE ✨

• -L, --live — live mode (default: disabled). when you use this, partitions get generated while crawling the filesystem 🔥. this saves time and memory, but it will never produce special partition 0 (see options -s and -S). as a consequence, it will generate partitions slightly larger than the size specified with option -s. this can be used with options -f and -s, but not with option -n ⚠️.
• -S — skip big files (default: disabled). in live mode, no special partition 0 can be produced, and big files get added to the current partition as they're found while crawling the filesystem — which can lead to huge partitions 😭. this option makes fpart skip files bigger than the specified maximum partition size (option -s) and print them to stdout (even when using option -o) as belonging to a pseudo-partition S (as in 'S'kipped). it lets a consumer handle them immediately through a separate process (no fpart hook will be executed for skipped files). this option can only be used in Live mode (option -L), when a maximum partition size has been given (option -s) 👑.
• -w cmd, --pre-part-cmd cmd — when using live mode, execute cmd when starting a new partition (before having opened the next output file, if any) 🎬. cmd runs in a specific environment that provides several variables describing the state of the program: FPART_HOOKTYPE ("pre-part", "post-part" or "post-run"), FPART_PARTFILENAME (current partition's output file name), FPART_PARTNUMBER (current partition number), FPART_PARTSIZE (current partition's size), FPART_TOTALSIZE (total partitions' size), FPART_PARTNUMFILES (number of files packed in current partition), FPART_TOTALNUMFILES (total number of files packed so far), FPART_PARTERRNO (0 if every single partition's entry has been read without error, else last erroneous entry's errno. For error detection to work properly, you may need to rebuild fpart using embedded fts(3) library, depending on the version shipped with your OS), FPART_PID (PID of fpart), FPART_TOTALNUMPARTS (total number of partitions generated so far). variables may or may not be defined, depending on requested options and the current partition's state when the hook is triggered 🤷. hooks are executed in a synchronous way while crawling the filesystem, so: 1) avoid executing commands that take a long time to return, because it slows down filesystem crawling, and 2) do not presume cwd (PWD) is the one fpart has been started in, as it is regularly changed to speed up crawling (i.e. use absolute paths within hooks) 🫶. size-related variables are affected by preloading, overloading and rounding options.
• -W cmd, --post-part-cmd cmd — same as -w, but executes cmd when finishing a partition (after having closed the last output file, if any) 🏁.
• -R cmd, --post-run-cmd cmd — same as -w and -W, but executes cmd just once before exiting 🎉. note that only the FPART_TOTALSIZE and FPART_TOTALNUMFILES environment variables are available in post-run hooks 👀.

✨ SIZE HANDLING ✨

okay bestie this is where you get to ✨control the numbers✨ — all three of these take a num and all three let you use a human-friendly unit suffix (k, m, g, t, p) 💅

• -p num — preload each partition with num bytes. Like, give it a lil head start 🫶. You can use a human-friendly unit suffix here (k, m, g, t, p).
• -q num — overload each file size with num bytes. You can use a human-friendly unit suffix here (k, m, g, t, p).
• -r num — round each file size up to the next num bytes multiple 🔥. This one can be used in conjunction with overloading, and here's the tea: overloading is done before rounding. You can use a human-friendly unit suffix here (k, m, g, t, p).

---

🌈 EXAMPLES 🌈

here are some examples, and honestly they ate:

fpart -n 3 -o var-parts /var

Produce 3 partitions, with (hopefully) the same size and number of files. Three files: var-parts.1, var-parts.2 and var-parts.3 are generated as output. so clean ✨

fpart -s 4724464025 -o music-parts /path/to/music ./*.mp3

Produce partitions of 4.4 GB, containing music files from /path/to/music as well as MP3 files from current directory; with such a partition size, each partition content will be ready to be burnt to a DVD 💿. Files music-parts.0 to music-parts.n, are generated as output. (yes bestie, .0 — it starts at zero, that's just how it is 🎀)

find /usr ! -type d | fpart -f 10000 -i - /home | grep '^1 '

Produce partitions containing 10000 files each by examining /usr first and then /home and display only partition 1 on stdout. the pipeline is giving main character energy fr fr 🔥

du * | fpart -n 2 -a

Produce two partitions by using du(1) output. Fpart will not examine the file system but instead use arbitrary values printed by du(1) and sort them. no filesystem crawling, we're just trusting the vibes (the du vibes, specifically) 💅

---

👀 SEE ALSO 👀

du(1), find(1), fpsync(1), grep(1), rsync(1)

like, go read those too, they're the friend group 🫶

---

💖 AUTHOR, AVAILABILITY 💖

Fpart has been written by Ganaël LAPLANCHE and is available under the BSD license on http://contribs.martymac.org — icon, legend, the moment 👑

---

💀 BUGS 💀

No bug known (yet). yet. not me side-eyeing this line 😭🙈

---

okay bestie that's the whole page, you're officially an fpart girlie now 🎀✨ This was the Debian build of FPART(1), dated November 18, 2011 — yeah she's a 2011 baby, vintage, lowkey iconic for it 💜. go partition something. slay. periodt. 🦋