Skip to content
GRIMOIRY

Banish a module

$ grim remove cart --dry-run

A module the project stopped using, or one grim update told you has left core and must now be either required or removed. grim remove takes the entry out of grim.json and then clears the disk: the module itself and the dependencies that were only there because of it.

It works on modules you required yourself. A module that came in as somebody's dependency is not yours to remove; grim why shows who asked for it.

Usage

$ grim remove cart --dry-run    # what is an orphan right now
$ grim remove cart              # drop it, then confirm the deletion
$ grim remove Cart --force      # no prompt, local changes discarded

Run it from the project root, next to grim.json. The name can be cart-orders or CartOrders. Themes are not handled here: take a theme out of grim.json by hand.

Arguments and options

Remove a module from grim.json and clean up any now-orphaned transitive dependencies

Usage

grim remove [--dry-run] [-f|--force] [--no-autoload-dump] [--] <module>

Arguments

Argument Description
module Module name (kebab-case or PascalCase) (required)

Options

Option Description
--dry-run Show what would change without writing grim.json or deleting
-f, --force Skip confirmation prompt and dirty-module warning
--no-autoload-dump Skip composer dump-autoload after removal

What it actually does

  1. Rewrites grim.json. The module leaves requires and the file is saved at once, before any question is asked. It prints ✓ Removed cart from grim.json.
  2. Looks for orphans. It reads module.json of every module under src/ and walks the requires from what grim.json still lists. Whatever cannot be reached is an orphan. Core modules are never counted.
  3. Lists them with their size on disk, and marks those with uncommitted changes.
  4. Asks. Delete 2 orphan module(s)? [y/N], with no as the default.
  5. Deletes. Each orphan's directory under src/ goes, and its line in storage/config/modules-enabled.php.
  6. Runs composer dump-autoload -o in the app container, unless --no-autoload-dump.

When another module still requires the one you removed, it is dropped from grim.json and stays on disk, and you are told so: cart stays installed — still reachable transitively.

Pitfalls

Saying no at the prompt does not undo the edit

grim.json was already written in step 1. Answer no and the module is gone from requires while its directory is still there. Restore the file with git checkout grim.json, or finish the job later with grim prune.

The dry run does not count the module itself

With --dry-run the entry is not taken out before orphans are looked for, so the list shows only what is orphaned already. The module you named and its dependencies are missing from it, and the line stays installed — still reachable transitively is printed about a module that the real run will delete. Expect the real list to be longer.

It clears every orphan, not only the ones this removal made

A leftover from a hand edit last month is deleted in the same pass. Read the list before answering yes.

Modules with local changes are skipped

⚠ 1 module has uncommitted changes that would be lost. An installed module is a git checkout, and edits inside it exist nowhere else. The clean orphans are deleted and the edited one stays. Commit and push from inside it first, or pass --force.

--force skips both the prompt and the check for uncommitted changes. Work inside src/<Module>/ that was never pushed is deleted with the directory.

grim.lock is not rewritten

The removed modules stay in the lock until something rebuilds it. grim install writes it again from what grim.json now resolves to, and so does the next grim update. Do one of them before you commit.

After it finishes

The database is untouched: tables the module's migrations created are still there. Bring the lock in line and look at what changed.

$ grim install --no-composer    # resolve again and rewrite the lock, skip the build
$ git diff --stat

grim prune

Clear what nothing asks for

Delete the modules under src/ that can no longer be reached from the requires in grim.json.

grim require

Summon a module or theme

Add a module or theme to grim.json, install it with everything it depends on, and rewrite grim.lock, all inside the train the project is on.

grim why

Ask why a module is here

Show the chain of requirements that leads from grim.json to an installed module, and what that module requires in turn.

grim install

Assemble the whole project

Turn grim.json into a working project by fetching core, every module and theme, writing grim.lock, building the image and starting the stack.

grim update

Board the newest train

Move core, every module and every theme onto the newest release train grim.json allows, or a single module within the train it is on.

Recipes that use it

Add, trace and remove modules

Find a module in the catalogue, require it on the project's train, trace what came along with it, and later remove it, sweep the leftovers and write the lock again.