You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/pnpm-lock-conflict-resolution.md
+89-47Lines changed: 89 additions & 47 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,13 +6,19 @@ When multiple developers work on the same repository and modify dependencies in
6
6
7
7
## Solution
8
8
9
-
This repository includes an **automated merge driver** for `pnpm-lock.yaml` that resolves conflicts automatically by regenerating the lockfile using `pnpm install`.
9
+
This repository uses an **automated conflict resolution strategy** for `pnpm-lock.yaml`:
10
+
11
+
1.**Union Merge Strategy**: Git automatically combines both versions of the lockfile
12
+
2.**Post-Merge Hook**: Automatically runs `pnpm install` after merges to regenerate a valid lockfile
13
+
3.**Version Enforcement**: The repository requires `pnpm >= 10.0.0` to ensure consistency
10
14
11
15
## How It Works
12
16
13
-
1.**`.gitattributes`**: Configures Git to use a custom merge driver for `pnpm-lock.yaml`
14
-
2.**`scripts/pnpm-merge-driver.sh`**: The merge driver script that automatically runs `pnpm install --lockfile-only` to regenerate the lockfile when conflicts occur
15
-
3.**Git configuration**: Local git config that points to the merge driver script
17
+
The solution uses Git's built-in `union` merge strategy combined with a post-merge hook:
18
+
19
+
1.**`.gitattributes`**: Configures pnpm-lock.yaml to use union merge (combines both sides)
20
+
2.**`.git/hooks/post-merge`**: Automatically runs `pnpm install` after any merge that touches pnpm-lock.yaml
21
+
3.**`package.json`**: Enforces pnpm version consistency across all developers
16
22
17
23
## Setup Instructions
18
24
@@ -24,68 +30,75 @@ After cloning this repository, run the setup script once:
24
30
./scripts/setup-merge-driver.sh
25
31
```
26
32
27
-
This will configure your local Git repository to use the automatic merge driver for `pnpm-lock.yaml`.
33
+
This will:
34
+
- Create a post-merge Git hook that auto-runs `pnpm install` after merges
35
+
- Display helpful information about how the system works
28
36
29
37
### What Happens During a Merge?
30
38
31
-
When you merge a branch that has conflicting changes in `pnpm-lock.yaml`:
39
+
When you merge a branch that has changes in `pnpm-lock.yaml`:
32
40
33
-
1. Git detects the conflict and invokes the custom merge driver
34
-
2. The merge driver runs `pnpm install --lockfile-only` to regenerate the lockfile
35
-
3. The newly generated lockfile incorporates dependencies from both branches
36
-
4. The merge completes automatically without manual intervention
41
+
1. Git uses the `union` strategy to combine both versions of the lockfile
42
+
2. The merge completes without stopping for manual conflict resolution
43
+
3. The post-merge hook automatically runs `pnpm install --no-frozen-lockfile`
44
+
4. pnpm regenerates a correct lockfile based on all package.json files
# 📦 pnpm-lock.yaml was updated in merge, running pnpm install...
60
+
# ✅ Dependencies synchronized
51
61
52
-
# Commit the merge
53
-
git commit
62
+
# Review the changes
63
+
git status
64
+
git diff pnpm-lock.yaml
65
+
66
+
# If pnpm-lock.yaml was modified by pnpm install, commit it
67
+
git add pnpm-lock.yaml
68
+
git commit -m "chore: update pnpm-lock.yaml after merge"
54
69
```
55
70
56
71
### Important Notes
57
72
58
73
⚠️ **Prerequisites:**
59
74
- You must have `pnpm` installed and available in your PATH
60
75
- The repository enforces `pnpm >= 10.0.0` (see `package.json` engines field)
76
+
- Run `./scripts/setup-merge-driver.sh` once after cloning
61
77
62
78
⚠️ **Package.json Conflicts:**
63
-
- If there are conflicts in `package.json` files, you must resolve those manually **before** the merge driver can successfully regenerate `pnpm-lock.yaml`
64
-
- The merge driver will fail if `pnpm install` fails due to invalid `package.json` files
79
+
- If there are conflicts in `package.json` files, you must resolve those manually **first**
80
+
- After resolving package.json conflicts, run `pnpm install` manually
81
+
- Then complete the merge
65
82
66
83
⚠️ **Review After Merge:**
67
84
- Always review the regenerated `pnpm-lock.yaml` to ensure dependencies are correct
85
+
- The post-merge hook will remind you to review and commit changes
68
86
- Run tests after merging to verify everything works as expected
69
87
70
88
## Manual Resolution (Fallback)
71
89
72
-
If the automatic merge driver fails or if you prefer manual resolution:
90
+
If you prefer manual resolution or if the automatic process fails:
73
91
74
92
1. Resolve any `package.json` conflicts first
75
-
2. Accept either version of `pnpm-lock.yaml` (doesn't matter which)
76
-
3. Run `pnpm install` to regenerate the lockfile
77
-
4. Stage and commit the regenerated lockfile:
78
-
79
-
```bash
80
-
# After resolving package.json conflicts
81
-
pnpm install
82
-
83
-
# Stage the regenerated lockfile
84
-
git add pnpm-lock.yaml
85
-
86
-
# Complete the merge
87
-
git commit
88
-
```
93
+
2. Run `pnpm install` to regenerate the lockfile:
94
+
```bash
95
+
pnpm install --no-frozen-lockfile
96
+
```
97
+
3. Stage and commit the regenerated lockfile:
98
+
```bash
99
+
git add pnpm-lock.yaml
100
+
git commit -m "chore: regenerate pnpm-lock.yaml"
101
+
```
89
102
90
103
## Version Consistency
91
104
@@ -119,36 +132,65 @@ corepack enable
119
132
corepack prepare pnpm@10.0.0 --activate
120
133
```
121
134
122
-
### Merge driver not being invoked
135
+
### Post-merge hook not running
123
136
124
-
1. Verify the merge driver is configured:
137
+
1. Verify the hook is installed and executable:
125
138
```bash
126
-
git config --local merge.pnpm-merge-driver.driver
139
+
ls -la .git/hooks/post-merge
127
140
```
128
141
129
142
2. Re-run the setup script:
130
143
```bash
131
144
./scripts/setup-merge-driver.sh
132
145
```
133
146
134
-
3. Check that `.gitattributes` exists and contains the merge driver configuration:
147
+
3. Make sure you're using `git merge` (hooks don't run with some Git GUI tools)
148
+
149
+
### pnpm install fails after merge
150
+
151
+
1. Check that you have no `package.json` conflicts remaining:
152
+
```bash
153
+
git status
154
+
```
155
+
156
+
2. Resolve any package.json conflicts manually
157
+
158
+
3. Run `pnpm install` manually:
159
+
```bash
160
+
pnpm install --no-frozen-lockfile
161
+
```
162
+
163
+
4. Complete the merge:
135
164
```bash
136
-
cat .gitattributes
165
+
git add pnpm-lock.yaml
166
+
git commit
137
167
```
138
168
139
-
### Merge driver fails
169
+
### Want to disable automatic pnpm install?
170
+
171
+
If you prefer to run `pnpm install` manually after merges:
140
172
141
-
1. Check that you have no `package.json` conflicts remaining
142
-
2. Try running `pnpm install` manually to see the error
143
-
3. Resolve any dependency issues
144
-
4. Continue the merge manually (see "Manual Resolution" above)
173
+
```bash
174
+
rm .git/hooks/post-merge
175
+
```
176
+
177
+
The union merge strategy will still work, you'll just need to run `pnpm install` yourself.
145
178
146
179
## CI/CD Integration
147
180
148
181
The GitHub Actions workflows in this repository already use pnpm@10 consistently. No additional CI configuration is needed.
149
182
183
+
## How This Compares to Other Solutions
184
+
185
+
| Approach | Pros | Cons |
186
+
|----------|------|------|
187
+
|**Union merge + hook** (This repo) | ✅ Simple<br>✅ Reliable<br>✅ No custom code<br>✅ Works with all Git tools | ⚠️ Requires one-time setup<br>⚠️ May need manual commit |
188
+
|**Custom merge driver**| ✅ Fully automatic | ❌ Complex<br>❌ Hard to debug<br>❌ May fail silently |
189
+
|**Manual resolution**| ✅ Full control | ❌ Tedious<br>❌ Error-prone<br>❌ Slows down workflow |
190
+
|**Always use ours/theirs**| ✅ Never blocks | ❌ Loses changes<br>❌ Must always regenerate |
0 commit comments