git-mailsplit

git mailsplit [-b] [-d dir] [-o file] [-q] [-f N] [-k] [-s] [-p] [-v] [--encoding=encoding] [--detect-encoding] [--[no-]decode-header] [--[no-]base64-decode-body] [--[no-]quopri-decode-body] [ < mbox ]

-b, --bare
    Store individual messages in msgNNNN files directly in the target directory, without creating a mbox subdirectory.

-d dir, --directory dir
    Specify the directory where the split messages should be written. Defaults to mbox in the current working directory.

-o file, --output file
    Specify the template for output file names. The default is msg%04d, which creates files like msg0001, msg0002.

-q, --quiet
    Suppress progress messages.

-f N, --first-number N
    Start numbering the output files from N instead of 1.

-k, --keep-cr
    Do not remove carriage return (CR) characters from the end of lines. By default, git-mailsplit removes CRs.

-s, --no-mboxrd
    Do not attempt to parse the mboxrd format, which escapes 'From ' lines. Treat all 'From ' lines as message separators, even if they are quoted.

-p, --patch-file
    In addition to splitting messages, also store the patch parts of the messages in separate files named msgNNNN.patch in the output directory.

-v, --verbose
    Show verbose progress messages during splitting.

--encoding=encoding
    Specify the input character encoding for the mailbox file (e.g., UTF-8, ISO-8859-1).

--detect-encoding
    Attempt to automatically detect the character encoding of the input mailbox file.

--[no-]decode-header
    Control whether MIME-encoded headers (e.g., Subject, From) are decoded. Default is to decode.

--[no-]base64-decode-body
    Control whether base64-encoded parts of the email body are decoded. Default is to decode.

--[no-]quopri-decode-body
    Control whether quoted-printable encoded parts of the email body are decoded. Default is to decode.

The git-mailsplit command reads a standard Unix mailbox file (mbox) from standard input and splits it into individual email messages. Each message is then written to a separate file in a designated output directory, typically named in a sequential fashion like msg0001, msg0002, etc. This utility is primarily used as a pre-processor for git am (apply a series of patches from a mailbox) when developers receive patch series via email in a single mbox file. It ensures that git am can process each patch individually, maintaining the integrity of the patch series workflow.

Handling of various mbox formats and their subtle differences (e.g., mboxo, mboxrd) can sometimes lead to issues. While git-mailsplit tries to be robust, malformed or non-standard mbox files might not be processed correctly. Encoding detection and decoding also depend on the input quality and declared MIME types within the emails. Users should verify the output, especially for complex or multi-part messages.

A common usage of git-mailsplit is piping the content of an mbox file directly into it. For example, to split an mbox file named patches.mbox into a directory named my-patches, you would use: cat patches.mbox | git mailsplit -d my-patches. After splitting, you can then navigate into my-patches and use git am * to apply all the patches.

By default, git-mailsplit creates a directory named mbox/ (or the directory specified by -d) in the current working directory. Inside this directory, it places the split email messages, typically named msg0001, msg0002, and so on. If the --patch-file option is used, corresponding patch files (e.g., msg0001.patch) will also be created for messages containing patch content.

git-mailsplit is an integral part of Git's robust email-based patch workflow, which has been a core feature of Git since its early days. It was designed to facilitate the common practice of sending and receiving software patches via email, allowing developers to consume a series of patches received in a single mailbox file, often generated by mailing list archives or email clients. Its development has focused on improving robustness in handling various mbox formats and character encodings to ensure seamless integration with the git am command.

git-am(1), git-apply(1), git-format-patch(1), git-send-email(1)