Split an mbox into numbered messages with git-mailsplit

You will finish with one file per message, named 0001, 0002 and so on, ready for another program to process. This guide uses the git mailsplit command from Git 2.43.0, supplied here by the git-man package version 1:2.43.0-1ubuntu7.3.

Allow about ten minutes. You need Git installed, a readable mbox or Maildir, and a separate output directory. The command writes new files, so check the destination before running it. It does not require elevated privileges when you own the input and output paths.

1. Create an empty output directory

Choose a temporary or dedicated directory. Do not point -o at a directory containing files you need to keep: the generated names are predictable and existing names may be replaced.

mkdir -p ./split-mail
find ./split-mail -maxdepth 1 -type f -print

Expected output is empty. If the find command prints files, stop and choose another directory or move those files somewhere safe. This is a normal user command; sudo is not a fix for an unsafe destination.

2. Split an mbox file

Pass the mbox after the output option. The compact option syntax is part of this command's interface: use -oDIRECTORY, as shown here.

$ git mailsplit -o./split-mail ./inbox.mbox
2

The number printed is the number of messages written. The example creates ./split-mail/0001 and ./split-mail/0002. Inspect both the names and the first lines before handing them to a later step:

find ./split-mail -maxdepth 1 -type f -printf '%f\n' | sort
sed -n '1,8p' ./split-mail/0001

Checkpoint: you should see four-digit names with leading zeroes, and the first file should contain the first message's headers. The default numbering is four digits. It is not a message identifier from the mail system.

3. Read an mbox from standard input

If you omit the input path, git mailsplit reads the mbox from standard input. This is useful when another command produces an mbox stream, but keep the output directory check from step 1.

$ git mailsplit -o./split-mail < ./inbox.mbox
2

Do not combine an input redirection with a second mbox argument unless you deliberately want to supply multiple inputs. For a repeatable job, record the exit status immediately after the command:

git mailsplit -o./split-mail < ./inbox.mbox
status=$?
printf 'git-mailsplit status: %s\n' "$status"
test "$status" -eq 0

A zero status means the split completed. A non-zero status means the output needs investigation before it is processed. The command may have written some files before an error, so use a fresh empty directory for a retry rather than mixing two attempts.

4. Split a Maildir

A Maildir is a directory containing cur, tmp and new subdirectories. Pass its root instead of an mbox file:

$ git mailsplit -o./split-mail ./Maildir
2

Maildir filenames are sorted to determine output order. That makes names and timestamps in the source directory operational data, not incidental decoration. If the order matters, inspect the source names and test the resulting sequence before applying patches or importing messages.

Checkpoint: verify the count and inspect a representative output file:

find ./split-mail -maxdepth 1 -type f -printf '%f\n' | sort
sed -n '1,12p' ./split-mail/0001

5. Handle the format options deliberately

Most ordinary mbox files need no extra option. Use -b only when a file that does not begin with a From line should be accepted as one complete message instead of rejected. This relaxes input checking, so do not add it just to silence an error you have not understood.

Use -fNN to skip the first NN numbers. For example, -f3 starts at 0004. Use -dN to choose a different filename precision. These options change names, not the order or content of messages, and are useful when combining output with an existing numbering scheme.

Use --keep-cr when carriage returns at the ends of CRLF lines must remain. Without it, those carriage returns are removed. Use --mboxrd only for mboxrd input, where escaped From lines need the format-specific unescaping rules. Choosing the wrong format can change how message boundaries or body lines are interpreted, so confirm the source format first.

6. Recover from a bad split

Stop downstream processing if the count is unexpected, a message starts in the wrong place, or the command exits non-zero. Preserve the output as evidence, then retry into a new directory with the correct input option. Do not casually delete the only copy of the split: the files may be the easiest way to identify whether the source was malformed.

If the output is disposable and you have confirmed the source mbox or Maildir is intact, remove only that dedicated output directory using your normal file-management procedure, recreate it, and run the command again. No service restart or elevated privilege is needed for this recovery.