hf branch

Review, plan and publish a cart branch. The subject of every verb is the branch name. The writes that put changes on a branch are the --branch forms of hf module, hf object and hf field.

Verbs

Verb	Request	Permission
diff <branch>	GET /v1/metadata@{branchId}/diff	admin.metadata.module.read
plan <branch> [--destructive] [--no-vault]	POST /v1/plan with branch in the body	admin.metadata.plan, plus global admin.metadata.object.read and admin.metadata.field.read
publish <branch> [--yes]	POST /v1/metadata@{branchId}/publish	admin.metadata.apply

A branch name containing / is sent as one path segment. main is not a branch these verbs take: every verb refuses it before sending anything, with MAIN_IS_NOT_A_CART_BRANCH. The server’s working tree is planned and applied with the top-level hf plan and hf apply.

Flags

Flag	Verb	Meaning
--destructive	plan	Plan destructive operations (drop column, narrow type) as DDL instead of as skipped changes.
--no-vault	plan	Plan without vaulting data before destructive operations.
--yes	publish	Publish without the confirmation prompt. Required when stdout is not a terminal or with --json; without it publish exits 1 with CONFIRMATION_REQUIRED and sends nothing.

Behavior

• diff lists the files the branch adds, modifies or deletes relative to main.
• plan computes the changes publishing the branch would make and runs nothing. It exits 0 whether or not the plan is empty. Each change carries a disposition: execute, skip or refuse.
• publish applies the branch and fast-forwards main onto it. On success the branch is deleted. An unknown branch answers 404 BRANCH_NOT_FOUND; a branch whose metadata fails to compile answers 422 and leaves main unmoved.

Output

Mode	Success	Failure
default	diff: one status path line per file, or No changes.; plan and publish: the source line, one line per change with its risk label and DDL, the summary line and any diagnostics	on stderr, one hf error: [scope:target] CODE: message line per server error, or hf error: and hf’s own message for a refusal it makes before sending anything; exit 1
--json	the server’s response body, verbatim, on stdout, exit 0	on stderr, exit 1: the server’s {"errors": [...]} envelope, verbatim, or the same envelope from hf for a refusal it makes before sending anything (see below)

In the default mode every string the server sends is printed without control characters, bidirectional controls, line separators or zero-width characters. --json output is not altered.

Refusals hf makes itself

hf checks some input before it sends a request, and refuses it with a registry code, in the same envelope under --json:

Code	Domain	When
MAIN_IS_NOT_A_CART_BRANCH	git	The branch is main.
CONFIRMATION_REQUIRED	api	publish runs without a terminal, or with --json, and without --yes.

Global flags

Every verb accepts --json, -t/--target <name> (run against a stored target other than the current one) and --no-color.

Examples

hf branch diff feat-sales
hf branch plan feat-sales
hf branch publish feat-sales --yes

Related

• Manage metadata with the hf CLI.
• Plan and publish a cart branch: the same routes over HTTP.
• HTTP API reference.