Drupal Config

Drupal Configuration Management

Safety: Avoid Accidental Remote Imports

Remote drush may default to --yes and auto-confirm cim. Always use safe patterns:

# SAFE — preview only
ssh user@remote "drush cim --no --diff"
ssh user@remote "drush config:get config.name"
ssh user@remote "drush config:status"

# DANGEROUS — may auto-import
ssh user@remote "drush cim --diff"

Import / Export

ddev drush cex               # Export active config → YAML files
ddev drush cim               # Import YAML files → active config
ddev drush cim --no --diff   # Preview only (no import)
ddev drush config:status     # Show pending changes (read-only)

Config Splits

Complete vs Partial — CRITICAL distinction

| Type | Behavior | Use for | |---|---|---| | Complete | Config exists ONLY in that environment | Modules on/off (devel, stagefileproxy) | | Partial | Base config everywhere, different VALUES | API keys, SMTP, search server URLs |

Complete split: config is removed from config/sync/ and lives only in config/{split}/. Partial split: config stays in config/sync/, overrides live in config/{split}/config_split.patch.*.yml.

Split Commands

ddev drush config-split:status            # List splits and active state
ddev drush csex {split-name}              # Export specific split
ddev drush csim {split-name}              # Import specific split
ddev drush config-split:activate {name}
ddev drush config-split:deactivate {name}

Updating a Split Definition

Changes must be in active config (DB), not just YAML files:

# Edit YAML, then import to activate
ddev drush config:import --partial
# OR set via PHP eval
ddev drush php:eval "\$c = \Drupal::configFactory()->getEditable('config_split.config_split.local'); \$c->set('partial_list', ['config.name']); \$c->save();"
ddev drush cex

Troubleshooting

Config deleted from config/sync/ on export

Root cause: Config is in complete_list instead of partial_list.

# Diagnose
grep -A10 "complete_list:" config/sync/config_split.config_split.local.yml
grep -A10 "partial_list:" config/sync/config_split.config_split.local.yml

Fix: move the item from complete_list to partial_list in the split YAML, then import and re-export.

Config won't import

ddev drush config:import --skip-config=system.site   # Skip specific locked config
ddev drush config:import --skip-modules=config_split  # Ignore splits

Split not activating

ddev drush config-split:status
ddev drush config-split:activate {split-name}
ddev drush cex

Intent → Command Mapping

| User Intent | Command | |---|---| | Preview config changes | drush cim --no --diff | | Import config | drush cim | | Export config | drush cex |

Related Commands

Read-only: config:get, config:status Export: cex / config:export Import: cim --no --diff (preview), cim (apply) Splits: config-split:status, csex, csim, config-split:activate

Deep Dive

• [full-guide.md](references/full-guide.md) — Extended reference on Config Split 2.0, patch files, export/import internals

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: edutrul
• Source: edutrul/drupal-ai
• License: MIT
• Homepage: https://eduardotelaya.com/drupal-ai/

Install and usage instructions live in the source repository linked above.