amateescu · amateescu · May 19, 2026 · May 19, 2026
diff --git a/drupal-dev/DRUPAL-DEV.md b/drupal-dev/DRUPAL-DEV.md
@@ -0,0 +1,57 @@
+<!-- #ddev-generated -->
+# ddev-drupal-dev cheat sheet
+
+Quick reference for the most common commands. See the [full README](https://github.com/amateescu/ddev-drupal-dev) for details.
+
+## Contrib modules
+
+```bash
+ddev auth ssh                          # forward SSH keys (once per session)
+ddev add-module token                  # clone + require token
+ddev add-module token 2.0.x            # specific branch
+ddev add-module --https token          # clone over HTTPS (no push access)
+ddev update-module token               # re-sync constraint after switching branches
+ddev remove-module token               # remove require, repo entry, and clone
+```
+
+Modules land in `modules/contrib/<name>` as git checkouts.
+
+## Composer overlay
+
+```bash
+ddev composer install                  # install everything (core + overlay)
+ddev composer require drupal/pathauto  # add a package without cloning
+ddev composer require --dev phpstan/phpstan
+ddev composer update                   # re-solve overlay
+```
+
+The overlay lives in `composer.local.json`; core's `composer.json` and `composer.lock` are never touched.
+
+## Tests
+
+```bash
+ddev phpunit core/modules/node                  # project database (default)
+ddev phpunit --db=sqlite core/modules/node      # SQLite
+ddev phpunit --db=pgsql core/modules/node       # PostgreSQL (needs ddev-postgres)
+ddev phpunit modules/contrib/token              # contrib module tests
+```
+
+## Pin core's exact dependency versions
+
+In `composer.local.json`:
+
+```json
+{ "extra": { "drupal-dev": { "pin-core-lock": true } } }
+```
+
+Then `ddev composer update` once to regenerate the lock with pinning applied.
+
+## Host-side shell helpers
+
+Add to `~/.bashrc` or `~/.zshrc` so bare `composer`, `drush`, `php`, `phpunit` auto-delegate to DDEV:
+
+```bash
+source /path/to/your/project/.ddev/drupal-dev/shell-helpers.sh
+```
+
+If you use `direnv`: run `direnv allow` in the project root.
diff --git a/drupal-dev/gitignore b/drupal-dev/gitignore
@@ -7,6 +7,7 @@
 
 # DDEV
 /.ddev
+/DRUPAL-DEV.md
 
 # Ignore files generated by the Finder in macOS
 .DS_Store

diff --git a/install.yaml b/install.yaml
@@ -7,6 +7,7 @@ project_files:
   - drupal-dev/envrc
   - drupal-dev/shell-helpers.sh
   - drupal-dev/gitignore
+  - drupal-dev/DRUPAL-DEV.md
   - drupal-dev/composer-plugin
   - commands/host/phpunit
   - commands/host/add-module
@@ -21,6 +22,9 @@ post_install_actions:
   - "[ -f ../composer.local.json ] || cp drupal-dev/composer.local.json ../composer.local.json"
   - "! [ -f ../.envrc ] || grep -q '#ddev-generated' ../.envrc && cp drupal-dev/envrc ../.envrc"
   - "! [ -f ../.gitignore ] || grep -q '#ddev-generated' ../.gitignore && cp drupal-dev/gitignore ../.gitignore"
+  # Copy the cheat sheet and ignore it in any existing .gitignore.
+  - "! [ -f ../DRUPAL-DEV.md ] || grep -q '#ddev-generated' ../DRUPAL-DEV.md && cp drupal-dev/DRUPAL-DEV.md ../DRUPAL-DEV.md"
+  - "! [ -f ../.gitignore ] || grep -qxF '/DRUPAL-DEV.md' ../.gitignore || printf '\\n# ddev-drupal-dev cheat sheet\\n/DRUPAL-DEV.md\\n' >> ../.gitignore"
   # Clean up web commands from a previous install now that these commands
   # have moved to commands/host/. Only remove files still marked as generated.
   - |
@@ -55,4 +59,6 @@ removal_actions:
   - "grep -q '#ddev-generated' ../composer.local.json 2>/dev/null && rm -f ../composer.local.json ../composer.local.lock || true"
   - "grep -q '#ddev-generated' ../.envrc 2>/dev/null && rm -f ../.envrc || true"
   - "grep -q '#ddev-generated' ../.gitignore 2>/dev/null && rm -f ../.gitignore || true"
+  - "grep -q '#ddev-generated' ../DRUPAL-DEV.md 2>/dev/null && rm -f ../DRUPAL-DEV.md || true"
+  - "[ -f ../.gitignore ] && sed -i.bak -e '/^# ddev-drupal-dev cheat sheet$/d' -e '/^\\/DRUPAL-DEV\\.md$/d' ../.gitignore && rm -f ../.gitignore.bak || true"
   - rm -rf ../test_output
diff --git a/tests/test.bats b/tests/test.bats
@@ -92,6 +92,11 @@ health_checks() {
   run grep -q "#ddev-generated" "${TESTDIR}/.gitignore"
   assert_success
 
+  # Verify the cheat sheet was copied and is gitignored
+  assert_file_exists "${TESTDIR}/DRUPAL-DEV.md"
+  run grep -qxF "/DRUPAL-DEV.md" "${TESTDIR}/.gitignore"
+  assert_success
+
   # Verify ddev phpunit works across all test types
   run ddev phpunit core/tests/Drupal/Tests/Core/Access/AccessGroupAndTest.php
   assert_success
@@ -257,13 +262,15 @@ teardown() {
   # Unmodified files are all cleaned up on removal
   assert_file_exists "${TESTDIR}/composer.local.json"
   assert_file_exists "${TESTDIR}/.envrc"
+  assert_file_exists "${TESTDIR}/DRUPAL-DEV.md"
   run ddev add-on remove drupal-dev
   assert_success
   refute_output --partial "Unwilling to remove"
   assert_file_not_exists "${TESTDIR}/composer.local.json"
   assert_file_not_exists "${TESTDIR}/composer.local.lock"
   assert_file_not_exists "${TESTDIR}/.envrc"
   assert_file_not_exists "${TESTDIR}/.gitignore"
+  assert_file_not_exists "${TESTDIR}/DRUPAL-DEV.md"
   assert_file_not_exists "${TESTDIR}/.ddev/drupal-dev"
   assert_file_not_exists "${TESTDIR}/.ddev/config.drupal-dev.yaml"
   assert_file_not_exists "${TESTDIR}/.ddev/commands/host/phpunit"
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,6 +7,7 @@ @@
     # DDEV
     /.ddev
+    /DRUPAL-DEV.md
     # Ignore files generated by the Finder in macOS
     .DS_Store
@@ Expand Down @@