libra format-patch

Generate mbox-formatted email patch files from commits.

Synopsis

libra format-patch [OPTIONS] [revision-range]

libra format-patch walks a revision range (A..B or a single commit treated as <commit>..HEAD), produces one patch file per non-merge commit (named with the --suffix, default .patch, unless --numbered-files is set, which uses bare sequence numbers), and formats each as an mbox message with RFC 2822 headers, a plain-text diffstat, and a unified diff. The output is compatible with git am.

Merge commits are skipped by default. When the revision range resolves to zero commits, the command exits with an error.

Options

Flag	Short	Description	Default
`[revision-range]`		`A..B` range or single commit; single commit means `<commit>..HEAD`	`HEAD`
`--output-directory <DIR>`	`-o`	Write patch files into `DIR`	current directory
`--stdout`		Print all patches to stdout	false
`--numbered`	`-n`	Name files with a leading sequence number (`0001-subject.patch`)	false
`--start-number <N>`		Start numbering at `N`	1
`--subject-prefix <PREFIX>`		Use `PREFIX` instead of `PATCH` in the Subject: line	`PATCH`
`--cover-letter`		Generate a cover-letter template (`0000-cover-letter<suffix>`, or `0` under `--numbered-files`)	false
`--thread`		Add `In-Reply-To` and `References` headers (default on)	true
`--no-thread`		Disable threading headers	false
`--in-reply-to <MESSAGE_ID>`		Make the first mail a reply to the given Message-ID	none
`--to <ADDRESS>`		Add a `To:` header (repeatable; multiple addresses fold like git). Placed after the MIME headers, on each patch and the cover letter	none
`--cc <ADDRESS>`		Add a `Cc:` header (repeatable; folds like git)	none
`--no-to` / `--no-cc`		Suppress the `To:` / `Cc:` headers (Libra has no `format.to`/`format.cc` config to reset)	false
`--from[=<IDENT>]`		Use `<IDENT>` in the `From:` header instead of the commit author (bare `--from` uses the committer's configured identity). When it differs from the author, the original author is preserved as an in-body `From:` line so `git am` can restore it	author
`--reroll-count <N>`	`-v`	Mark as version `N` (changes `[PATCH]` to `[PATCH vN]`)	none
`--signoff`	`-s`	Append a `Signed-off-by` trailer to each commit message	false
`--notes[=<REF>]`		Append each commit's notes after the `---` line, before the diffstat. Bare `--notes` uses the default ref (`refs/notes/commits`); `--notes=<ref>` reads `<ref>`. Rendered as `Notes:` (default ref) or `Notes (<ref>):`, each line indented four spaces; commits without a note are emitted unchanged	off
`--attach`		Emit each patch as a `multipart/mixed` MIME message: the log message + diffstat in a `text/plain` part, the diff in a `text/x-patch` part with `Content-Disposition: attachment`. Mutually exclusive with `--inline`	off
`--inline`		Like `--attach`, but the patch part uses `Content-Disposition: inline`	off
`--base <COMMIT>`		Record a `base-commit:` trailer (and a `prerequisite-patch-id:` line for each non-merge commit between the base and the series, oldest-first) so `git am --base` can verify the series applies. The trailer rides on the last patch, or the cover letter under `--cover-letter`. The base must be an ancestor of the series (otherwise exit 128). `--base=auto` is not supported (exit 129). Patch-ids match `git patch-id --stable` for text diffs; binary-file prerequisites are not guaranteed to match Git	off
`--full-index`		Show full object IDs in diff index header lines	false
`--no-stat`		Suppress the diffstat summary	false
`--keep-subject`		Keep the original `[PATCH]` prefix in the commit subject	false
`--suffix <SFX>`		Filename suffix for generated patches (e.g. `.txt`); ignored under `--numbered-files`	`.patch`
`--zero-commit`		Use an all-zero hash in each patch's `From <hash>` envelope line	false
`--signature <SIGNATURE>`		Text placed after the `--` line of each patch and the cover letter	libra version
`--no-signature`		Omit the `--` /signature footer entirely	false
`--signature-file <FILE>`		Read the signature footer text from a file (mutually exclusive with `--signature`)
`--encode-email-headers` / `--no-encode-email-headers`		RFC 2047 Q-encode `From`/`Subject` header values that contain non-ASCII characters	off
`--numbered-files`		Name output files by a bare sequence number (suffix not applied)	false

Examples

Basic range

# Generate patches for the last three commits
libra format-patch HEAD~3..HEAD

# Numbered patches in a directory
libra format-patch -n -o patches/ main..feature

# With cover letter and threading
libra format-patch --cover-letter --thread origin/main..

# Version 2, replying to a previous thread
libra format-patch -v 2 --in-reply-to '<msgid@example>' origin/main..

# Pipe to an external tool
libra format-patch --stdout origin/main.. | git am

# Record the base the series applies to (for `git am --base`)
libra format-patch --base=origin/main --stdout origin/main..HEAD

Output Format

Each patch file is an mbox message:

From <commit-oid> <unix-mbox-date>
From: Author Name <email>
Date: <RFC 2822 date>
Subject: [PATCH n/m] commit subject
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

commit message body
---
diffstat summary
unified diff
--
<libra-version>

The -- footer defaults to the libra version; --signature <text> replaces it with custom text, --signature-file <file> reads the footer text from a file, and --no-signature omits the footer entirely. --encode-email-headers RFC 2047 Q-encodes From/Subject header values that contain non-ASCII characters. It is off by default in Libra (which has no format.encodeEmailHeaders config knob); Git derives its default from that config, which is itself off unless set.

With --json or --machine, data.patches lists every generated output. When --cover-letter is set, the list includes the cover letter as record number 0 before the commit patch records. Its filename is 0000-cover-letter with the configured suffix (default .patch), or just 0 under --numbered-files.

Error Handling

Scenario	StableErrorCode
Not in a Libra repository	`LBR-REPO-001`
Unknown revision or empty range	`LBR-CLI-003`
`--base` is not an ancestor of the series	`LBR-CLI-003` (exit 128)
`--base=auto` (unsupported)	`LBR-CLI-002` (exit 129)
Output file write failure	`LBR-IO-002`
Output directory creation failure	`LBR-IO-002`

Generate mbox-formatted email patch files from commits.

Synopsis

libra format-patch [OPTIONS] [revision-range]

Description

Merge commits are skipped by default. When the revision range resolves to zero commits, the command exits with an error.

Options

Flag	Short	Description	Default
`[revision-range]`		`A..B` range or single commit; single commit means `<commit>..HEAD`	`HEAD`
`--output-directory <DIR>`	`-o`	Write patch files into `DIR`	current directory
`--stdout`		Print all patches to stdout	false
`--numbered`	`-n`	Name files with a leading sequence number (`0001-subject.patch`)	false
`--start-number <N>`		Start numbering at `N`	1
`--subject-prefix <PREFIX>`		Use `PREFIX` instead of `PATCH` in the Subject: line	`PATCH`
`--cover-letter`		Generate a cover-letter template (`0000-cover-letter<suffix>`, or `0` under `--numbered-files`)	false
`--thread`		Add `In-Reply-To` and `References` headers (default on)	true
`--no-thread`		Disable threading headers	false
`--in-reply-to <MESSAGE_ID>`		Make the first mail a reply to the given Message-ID	none
`--to <ADDRESS>`		Add a `To:` header (repeatable; multiple addresses fold like git). Placed after the MIME headers, on each patch and the cover letter	none
`--cc <ADDRESS>`		Add a `Cc:` header (repeatable; folds like git)	none
`--no-to` / `--no-cc`		Suppress the `To:` / `Cc:` headers (Libra has no `format.to`/`format.cc` config to reset)	false
`--from[=<IDENT>]`		Use `<IDENT>` in the `From:` header instead of the commit author (bare `--from` uses the committer's configured identity). When it differs from the author, the original author is preserved as an in-body `From:` line so `git am` can restore it	author
`--reroll-count <N>`	`-v`	Mark as version `N` (changes `[PATCH]` to `[PATCH vN]`)	none
`--signoff`	`-s`	Append a `Signed-off-by` trailer to each commit message	false
`--notes[=<REF>]`		Append each commit's notes after the `---` line, before the diffstat. Bare `--notes` uses the default ref (`refs/notes/commits`); `--notes=<ref>` reads `<ref>`. Rendered as `Notes:` (default ref) or `Notes (<ref>):`, each line indented four spaces; commits without a note are emitted unchanged	off
`--attach`		Emit each patch as a `multipart/mixed` MIME message: the log message + diffstat in a `text/plain` part, the diff in a `text/x-patch` part with `Content-Disposition: attachment`. Mutually exclusive with `--inline`	off
`--inline`		Like `--attach`, but the patch part uses `Content-Disposition: inline`	off
`--base <COMMIT>`		Record a `base-commit:` trailer (and a `prerequisite-patch-id:` line for each non-merge commit between the base and the series, oldest-first) so `git am --base` can verify the series applies. The trailer rides on the last patch, or the cover letter under `--cover-letter`. The base must be an ancestor of the series (otherwise exit 128). `--base=auto` is not supported (exit 129). Patch-ids match `git patch-id --stable` for text diffs; binary-file prerequisites are not guaranteed to match Git	off
`--full-index`		Show full object IDs in diff index header lines	false
`--no-stat`		Suppress the diffstat summary	false
`--keep-subject`		Keep the original `[PATCH]` prefix in the commit subject	false
`--suffix <SFX>`		Filename suffix for generated patches (e.g. `.txt`); ignored under `--numbered-files`	`.patch`
`--zero-commit`		Use an all-zero hash in each patch's `From <hash>` envelope line	false
`--signature <SIGNATURE>`		Text placed after the `--` line of each patch and the cover letter	libra version
`--no-signature`		Omit the `--` /signature footer entirely	false
`--signature-file <FILE>`		Read the signature footer text from a file (mutually exclusive with `--signature`)
`--encode-email-headers` / `--no-encode-email-headers`		RFC 2047 Q-encode `From`/`Subject` header values that contain non-ASCII characters	off
`--numbered-files`		Name output files by a bare sequence number (suffix not applied)	false

Examples

Basic range

# Generate patches for the last three commits
libra format-patch HEAD~3..HEAD

# Numbered patches in a directory
libra format-patch -n -o patches/ main..feature

# With cover letter and threading
libra format-patch --cover-letter --thread origin/main..

# Version 2, replying to a previous thread
libra format-patch -v 2 --in-reply-to '<msgid@example>' origin/main..

# Pipe to an external tool
libra format-patch --stdout origin/main.. | git am

# Record the base the series applies to (for `git am --base`)
libra format-patch --base=origin/main --stdout origin/main..HEAD

Output Format

Each patch file is an mbox message:

From <commit-oid> <unix-mbox-date>
From: Author Name <email>
Date: <RFC 2822 date>
Subject: [PATCH n/m] commit subject
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

commit message body
---
diffstat summary
unified diff
--
<libra-version>

Error Handling

Scenario	StableErrorCode
Not in a Libra repository	`LBR-REPO-001`
Unknown revision or empty range	`LBR-CLI-003`
`--base` is not an ancestor of the series	`LBR-CLI-003` (exit 128)
`--base=auto` (unsupported)	`LBR-CLI-002` (exit 129)
Output file write failure	`LBR-IO-002`
Output directory creation failure	`LBR-IO-002`

libra format-patch

Synopsis

Description

Options

Examples

Basic range

Output Format

Error Handling

On this page

libra format-patch

Synopsis

Description

Options

Examples

Basic range

Output Format

Error Handling

On this page