cwp widgets

cwp widgets [flags]

cwp widgets groups the commands below and takes no action of its own; run it alone and it prints its help.

Flag	What it does	Default
--with-agent	with —dry-run on a host with no shell: install and remove the PHP agent so the plan is real	off

Subcommand	What it does
cwp widgets pull	Read the declared widget areas into widgets/
cwp widgets push	Replace the contents of the widget areas the tree describes

What it does

Carries widget areas as files: one file per area, its widgets inlined in the order they are shown.

WordPress stores a widget area in two halves that mean nothing apart. sidebars_widgets maps each area to an ordered list of ids like nav_menu-2. The contents of nav_menu-2 is index 2 of the widget_nav_menu option, a row holding every nav-menu widget on the site. Committed as two settings entries that is technically complete and practically unreadable. Committed as one file per area it is the thing somebody reviews.

area: footer-3
name: Footer — Account
widgets:
  - type: nav_menu
    settings:
      title: My account
      nav_menu: {kind: term, taxonomy: nav_menu, slug: account}

Declared, never discovered

widgets: [footer-3, sidebar]   # or `true` for every area holding something

A measurement decided this. A live site’s only widget area held WordPress’s five default block widgets, and nobody had ever touched them. A feature that carried every non-empty area would commit those into every project. So false is the default, and cwp coverage says which areas hold anything.

An area is replaced whole

A widget has no identity of its own: no uid, no stable id, nothing but its position and its settings. There is nothing to reconcile widget by widget, and a mechanism that tried would mismatch two that look alike. So the comparison is the whole area in order, and the push replaces its contents. The confirmation says that in those words.

The instance number never travels: nav_menu-2 is database identity, and the push allocates its own on the target.

What it does not do

• It does not model block widgets. WordPress 5.8 stores a whole area’s block markup in widget_block entries, and that is a blob. It travels verbatim, diffable line by line and no more structured than that. The limit has a name here on purpose.
• It does not touch an area the tree does not describe.
• It does not invent an area. A file for an area this theme does not register is a refusal naming it, not a silent skip.