ng update will update you automatically

During my Angular Update Odyssey, I found that the Angular Update Guide frequently states

ng update will do this automatically for you.
ng update should take care of this automatically.
ng update will migrate you automatically.

and I wondered when ng update would actually perform all those magic tasks, because I did not notice them.

Then I had the relevation, that ng update only performs the update tasks, if the package update was successful.

If the package update fails due to package dependency conflicts, then no update magic. Bad luck. You need to clean-up by yourself.

Analyzing the update log I keep (essentially a copy-and-paste from the npx update console output), this is what happens:

> npx @angular/cli@10 update @angular/core@10 @angular/cli@10

The installed local Angular CLI version is older than the latest stable version.
Installing a temporary version to perform the update.
Installing packages for tooling via npm.
Installed packages for tooling via npm.
Using package manager: 'npm'
Collecting installed dependencies...
Found 54 dependencies.

Fetching dependency metadata from registry...
    Updating package.json with dependency @angular-devkit/build-angular @ "0.1002.4" (was "0.901.15")...
    Updating package.json with dependency @angular/cli @ "10.2.4" (was "9.1.15")...
...

  UPDATE package.json (2249 bytes)

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: my.web.app@1.0.0
npm ERR! Found: @angular-devkit/build-angular@0.901.15
npm ERR! node_modules/@angular-devkit/build-angular
npm ERR!   dev @angular-devkit/build-angular@"^0.1002.4" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! dev @angular-devkit/build-angular@"^0.1002.4" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: @angular/compiler-cli@10.2.5
npm ERR! node_modules/@angular/compiler-cli
npm ERR!   peer @angular/compiler-cli@"^10.0.0" from @angular-devkit/build-angular@0.1002.4
npm ERR!   node_modules/@angular-devkit/build-angular
npm ERR!     dev @angular-devkit/build-angular@"^0.1002.4" from the root project

My interpretation of the log entries is that

• ng update fetches the dependencies of the new packages
• ng update writes package.json with new version numbers
• npm fails to install because of dependency conflicts
• ng update gives up, because the new packages are not there

If you’re lucky, the node_modules directory has been deleted, too.

So, for future updates, I will consider the following update strategy:

• run npx update
• if the update fails as above, revert the changes in package.json
  – apparently there’s a reason npx update warns

Repository is not clean. Please commit or stash any changes before updating.

• run npx update --force
• commit changes
• fix broken dependencies