---
name: yarn-lock-separate-commit
description: >-
  yarn.lock in its own commit — use when changing Yarn dependencies (package.json deps, workspace renames, yarn install), when organizing or reviewing commits that touch yarn.lock, when a rebase conflicts on yarn.lock, or during a retcon. Every lockfile change ships alone as `chore: Update yarn.lock`, after the package.json commit that caused it.
---

# yarn.lock in a separate commit

Every change that touches `yarn.lock` ships in its own commit, with the
message `chore: Update yarn.lock`. It stays separate from the
`package.json` change that caused it.

## Why

A separate lockfile commit can be dropped on a rebase and cleanly
regenerated. A combined commit turns lockfile churn into merge
conflicts, and those get resolved by re-running `yarn install` and
stitching by hand. That's error-prone and clutters the history.

## Procedure

After the dependency change in `package.json`:

```sh
git add packages/foo/package.json
git commit -m "feat(foo): add bar dependency"

npx corepack yarn install
git add yarn.lock
git commit -m "chore: Update yarn.lock"
```

Order matters. Put the lockfile commit **after** the `package.json`
commit, so dropping the lockfile commit still leaves a coherent state.

## Rebasing past a lockfile conflict

If another PR changed dependencies in the meantime, rebasing onto the
moved base usually conflicts on `yarn.lock`. Don't hand-merge it. Drop
the old lockfile commit and regenerate the lockfile:

```sh
git rebase origin/<base>
# conflict on yarn.lock
git rebase --skip                 # drop the old lockfile commit
# ... any other fixes on top ...
npx corepack yarn install         # regenerate against the new base
git add yarn.lock
git commit -m "chore: Update yarn.lock"
```

## Pitfalls

- **`git commit --amend` on the `package.json` commit** quietly pulls
  the lockfile in if it's staged. Stage and commit the lockfile last.
- **Combined by accident:** run `git reset HEAD~1`, restage selectively,
  and recommit as two commits.
- **Package renames change the lockfile.** Renaming a workspace's
  directory or its `package.json` `name` changes the workspace key
  (`"@scope/<name>@workspace:packages/<dir>"`) in `yarn.lock`. Once all
  the renames are in, regenerate with `npx corepack yarn install`.
  Commit the result on its own as usual, and don't hand-edit the key.

## See also

- [Retcon](../retcon/SKILL.md) applies this rule to a whole branch's
  history after the fact.
- Adapted from
  [the yarn-lock-separate-commit skill in kriscendobot/garden](https://github.com/kriscendobot/garden/blob/f6fd8db6abe012366aa4c843874c07adae46e7f7/skills/yarn-lock-separate-commit/SKILL.md)
  (May 2026).