Interactive Tutorial

Learn Pastoralist step by step

This tutorial follows an express → qs override through tracking and cleanup. The versions are fixture inputs, not package-version recommendations.

Create a Test Project

mkdir test-pastoralistcd test-pastoralistnpm init -ynpm pkg set name=shepherd-clinpm pkg set overrides.qs=6.11.2npm install [email protected] --save-exactnpm install pastoralist --save-dev

Generate Tracking

npx pastoralist

Pastoralist generated this diff from the fixture's dependency graph:

--- package.json+++ package.json@@ -5,5 +5,17 @@   },   "overrides": {     "qs": "6.11.2"+  },+  "pastoralist": {+    "appendix": {+      "[email protected]": {+        "dependents": {+          "shepherd-cli": "qs (required by express)"+        },+        "ledger": {+          "addedDate": "2026-10-16"+        }+      }+    }   } }

dependents identifies the project and the package requiring qs. ledger.addedDate records when Pastoralist first tracked the override. Actual dependents reflect your resolved dependency tree.

Review Before Writing

npx pastoralist doctornpx pastoralist --dry-run

Remove an Unused Override

Remove the dependency that required the override, then preview cleanup:

npm uninstall expressnpx pastoralist --remove-unused --dry-run

If no other package needs qs, apply cleanup:

npx pastoralist --remove-unused

Pastoralist removes the unused override and its appendix entry. Active keep constraints protect entries from removal; uncertain usage is not proof that an override is unused.

Keep Tracking Current

Opt into running Pastoralist after dependency installs:

npx pastoralist --setup-hook

Use Configuration for ledger reasons and keep constraints, or Workspaces for monorepo setup.

Try It Now

Open Interactive Demos to see Pastoralist in action.

Resources