My working unpac space for OCaml projects in development
Document export/upstream workflow for publishing opam packages
Add comprehensive documentation for:
- Option 1: Push project branch (includes vendor/)
- Option 2: Export as standalone library (files at root)
- Branch model diagram showing export/upstream flow
- Full workflow from development to publication
- Export commands reference table
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+359
+359
CLAUDE.md
+359
CLAUDE.md
···
1
+
# Unpac Workspace: mymatrix
2
+
3
+
This is an unpac-managed workspace containing vendored dependencies.
4
+
5
+
## Unpac Executable
6
+
7
+
```bash
8
+
/workspace/unpac/_build/default/bin/main.exe
9
+
```
10
+
11
+
For convenience, create an alias:
12
+
```bash
13
+
alias unpac='/workspace/unpac/_build/default/bin/main.exe'
14
+
```
15
+
16
+
**Important:** git-filter-repo must be in PATH:
17
+
```bash
18
+
export PATH="$HOME/.local/bin:$PATH"
19
+
```
20
+
21
+
## Workspace Structure
22
+
23
+
```
24
+
/workspace/mymatrix/
25
+
├── git/ # Bare git repository (all branches)
26
+
├── main/ # Main worktree with unpac.toml config
27
+
├── project/
28
+
│ └── ocaml-matrix/ # Project with merged vendors
29
+
│ └── vendor/
30
+
│ ├── git/ # Git-vendored repos
31
+
│ └── opam/ # Opam packages
32
+
└── vendor/ # Editing worktrees (created on demand)
33
+
```
34
+
35
+
## Branch Model
36
+
37
+
Each vendored item has three branches:
38
+
39
+
| Branch | Purpose |
40
+
|--------|---------|
41
+
| `*/upstream/<name>` | Original upstream code |
42
+
| `*/vendor/<name>` | Clean snapshot for merge base |
43
+
| `*/patches/<name>` | Your local modifications |
44
+
45
+
## Common Commands
46
+
47
+
### Listing Vendored Items
48
+
```bash
49
+
unpac opam list # List opam packages
50
+
unpac git list # List git repositories
51
+
unpac project list # List projects
52
+
```
53
+
54
+
### Making Changes to Vendored Code
55
+
56
+
1. **Open for editing** (creates worktrees):
57
+
```bash
58
+
unpac opam edit <package>
59
+
unpac git edit <repo>
60
+
```
61
+
62
+
2. **Make changes** in the patches worktree:
63
+
```bash
64
+
cd vendor/opam/<package>-patches/ # or vendor/git/<repo>-patches/
65
+
# edit files...
66
+
git add -A && git commit -m 'your changes'
67
+
```
68
+
69
+
3. **Close editing session**:
70
+
```bash
71
+
unpac opam done <package>
72
+
unpac git done <repo>
73
+
```
74
+
75
+
4. **View your changes**:
76
+
```bash
77
+
unpac opam diff <package>
78
+
unpac git diff <repo>
79
+
```
80
+
81
+
### Updating from Upstream
82
+
83
+
```bash
84
+
unpac opam update <package>
85
+
unpac git update <repo>
86
+
```
87
+
88
+
Then re-merge into your project:
89
+
```bash
90
+
unpac opam merge <package> ocaml-matrix
91
+
unpac git merge <repo> ocaml-matrix
92
+
```
93
+
94
+
### Adding New Dependencies
95
+
96
+
```bash
97
+
# Add opam package with dependency solving
98
+
unpac opam add <package> --solve
99
+
100
+
# Add git repository
101
+
unpac git add <url>
102
+
103
+
# Merge into project
104
+
unpac opam merge <package> ocaml-matrix
105
+
unpac git merge <repo> ocaml-matrix
106
+
107
+
# Or merge all opam packages at once
108
+
unpac opam merge --all ocaml-matrix
109
+
```
110
+
111
+
**Important:** Wait for `opam add` to complete before running `opam merge`. The add operation creates three branches (`*/upstream/<name>`, `*/vendor/<name>`, `*/patches/<name>`) and all must exist before merge can succeed.
112
+
113
+
Also ensure your project worktree has no uncommitted changes before merging - git merge will fail if there are uncommitted changes.
114
+
115
+
### Inspecting Vendored Package Source
116
+
117
+
You can inspect a package's source code without merging it into any project:
118
+
119
+
```bash
120
+
# 1. Add the package (if not already added)
121
+
unpac opam add <package>
122
+
123
+
# 2. Open for editing (creates worktrees)
124
+
unpac opam edit <package>
125
+
126
+
# 3. Browse the source
127
+
ls vendor/opam/<package>-patches/
128
+
cat vendor/opam/<package>-patches/src/foo.ml
129
+
130
+
# 4. Close when done (removes worktrees)
131
+
unpac opam done <package>
132
+
```
133
+
134
+
The `edit` command creates two worktrees:
135
+
- `vendor/opam/<package>-vendor/` - clean upstream snapshot
136
+
- `vendor/opam/<package>-patches/` - your modifications (starts same as vendor)
137
+
138
+
This is useful for:
139
+
- Exploring a library's implementation before deciding to use it
140
+
- Understanding how a dependency works
141
+
- Finding code to reference when implementing similar features
142
+
143
+
**Note:** You don't need to merge a package into a project just to view its source. The edit workflow gives you full access to browse the code.
144
+
145
+
## Working in the Project
146
+
147
+
The project directory is a regular git worktree:
148
+
149
+
```bash
150
+
cd project/ocaml-matrix/
151
+
152
+
# All vendored code is in vendor/
153
+
ls vendor/git/matrix-rust-sdk/
154
+
ls vendor/opam/
155
+
156
+
# Build with dune
157
+
dune build
158
+
```
159
+
160
+
## Promoting Projects to Vendored Libraries
161
+
162
+
When you've completed a project (like a library implementation), you can **promote** it to become a vendored library that can be merged into other projects.
163
+
164
+
### Promotion Workflow
165
+
166
+
1. **Check project status**:
167
+
```bash
168
+
unpac project info brotli
169
+
# Project: brotli
170
+
# Origin: local
171
+
# Remote: (none)
172
+
# Promoted: no
173
+
```
174
+
175
+
2. **Promote the project** (filters out vendor/ and creates clean library branches):
176
+
```bash
177
+
unpac project promote brotli --backend opam
178
+
# Promoted brotli as opam vendor
179
+
# Filtered history: 20214 → 12 commits (removed vendor/ directory)
180
+
# Created branches:
181
+
# opam/upstream/brotli
182
+
# opam/vendor/brotli
183
+
# opam/patches/brotli
184
+
```
185
+
186
+
3. **Merge into other projects**:
187
+
```bash
188
+
unpac opam merge brotli parquet # Use brotli in parquet project
189
+
```
190
+
191
+
### Backend Types
192
+
193
+
| Backend | Use Case | Vendor Path | Merge Command |
194
+
|---------|----------|-------------|---------------|
195
+
| `opam` | OCaml libraries built with dune | `vendor/opam/<name>/` | `unpac opam merge` |
196
+
| `git` | Reference code, C libraries, specs | `vendor/git/<name>/` | `unpac git merge` |
197
+
198
+
### Publishing to Independent Repository
199
+
200
+
There are two ways to publish: pushing the project branch directly, or exporting as a standalone library.
201
+
202
+
#### Option 1: Push Project Branch (includes vendor/ directory)
203
+
204
+
```bash
205
+
unpac project set-remote brotli git@github.com:user/ocaml-brotli.git
206
+
unpac project push brotli
207
+
```
208
+
209
+
This pushes the full project including vendored dependencies. Good for archival or when recipients will use the project as-is.
210
+
211
+
#### Option 2: Export as Standalone Library (recommended for opam)
212
+
213
+
The export workflow creates a clean branch with files at repository root (no vendor/ prefix), suitable for publishing as a standalone opam package:
214
+
215
+
```bash
216
+
# 1. Export with your patches (moves files from vendor/opam/<name>/ to root)
217
+
unpac export mylib --backend opam --from-patches
218
+
219
+
# 2. Configure export remote (where to push)
220
+
unpac export-set-remote mylib git@github.com:me/mylib.git
221
+
222
+
# 3. Push export branch as 'main' on the remote
223
+
unpac export-push mylib --backend opam
224
+
225
+
# 4. Configure upstream remote (where to fetch updates from)
226
+
unpac opam set-upstream mylib git@github.com:me/mylib.git
227
+
```
228
+
229
+
After this, you can pull updates from the published repo:
230
+
```bash
231
+
unpac opam update mylib # Fetches from upstream remote
232
+
```
233
+
234
+
### Branch Model for Export/Upstream
235
+
236
+
```
237
+
┌─────────────────────────────────────────┐
238
+
│ github.com/user/mylib │
239
+
│ (files at root) │
240
+
└─────────────────────────────────────────┘
241
+
↑ ↓
242
+
export-push set-upstream + update
243
+
↑ ↓
244
+
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
245
+
│ opam/export/ │ ← │ opam/patches/│ │opam/upstream/│
246
+
│ (root files) │ │(vendor/ path)│ │ (root files) │
247
+
└──────────────┘ └──────────────┘ └──────────────┘
248
+
```
249
+
250
+
- **upstream/** - pristine external state (files at root)
251
+
- **vendor/** - upstream with vendor/opam/<name>/ prefix (merge base)
252
+
- **patches/** - vendor + your local modifications
253
+
- **export/** - patches transformed back to root (for pushing)
254
+
255
+
### Full Example: Library Development to Publication
256
+
257
+
```bash
258
+
# 1. Create and develop a new library
259
+
unpac project new mylib
260
+
cd project/mylib/
261
+
# ... develop the library, vendor dependencies, write tests ...
262
+
263
+
# 2. When complete, promote to vendor library
264
+
unpac project promote mylib --backend opam
265
+
266
+
# 3. Merge into other projects within this workspace
267
+
unpac opam merge mylib other-project
268
+
269
+
# 4. Export for standalone publication
270
+
unpac export mylib --backend opam --from-patches
271
+
unpac export-set-remote mylib git@github.com:me/mylib.git
272
+
unpac export-push mylib --backend opam
273
+
274
+
# 5. Configure upstream for bidirectional sync
275
+
unpac opam set-upstream mylib git@github.com:me/mylib.git
276
+
277
+
# 6. Later, pull updates from published repo
278
+
unpac opam update mylib
279
+
```
280
+
281
+
### Project Commands Reference
282
+
283
+
| Command | Description |
284
+
|---------|-------------|
285
+
| `unpac project new <name>` | Create a new project |
286
+
| `unpac project list` | List all projects |
287
+
| `unpac project info <name>` | Show project details (origin, remote, promoted status) |
288
+
| `unpac project promote <name> --backend <opam\|git>` | Promote to vendor library |
289
+
| `unpac project set-remote <name> <url>` | Configure remote for publishing |
290
+
| `unpac project push <name>` | Push to configured remote |
291
+
292
+
### Export Commands Reference
293
+
294
+
| Command | Description |
295
+
|---------|-------------|
296
+
| `unpac export <name> --backend <opam\|git>` | Export vendor branch to root-level files |
297
+
| `unpac export <name> --backend <opam\|git> --from-patches` | Export patches branch (includes local mods) |
298
+
| `unpac export-set-remote <name> <url>` | Configure where to push exports |
299
+
| `unpac export-push <name> --backend <opam\|git>` | Push export branch to remote |
300
+
| `unpac export-list` | List all exported packages |
301
+
| `unpac opam set-upstream <name> <url>` | Configure where to fetch updates from |
302
+
303
+
## Git Operations
304
+
305
+
### Viewing Branch Contents Without Worktrees
306
+
307
+
You can inspect any branch's contents directly from the bare repo without creating worktrees:
308
+
309
+
```bash
310
+
cd /workspace/mymatrix/git
311
+
312
+
# List files in a branch
313
+
git ls-tree --name-only opam/patches/cohttp
314
+
315
+
# View a specific file
316
+
git show opam/patches/cohttp:src/cohttp.ml
317
+
318
+
# View directory contents
319
+
git ls-tree opam/patches/cohttp:src/
320
+
321
+
# View commit history
322
+
git log opam/patches/cohttp
323
+
324
+
# Compare branches
325
+
git diff opam/vendor/cohttp opam/patches/cohttp
326
+
```
327
+
328
+
This is the fastest way to peek at vendored package source - no worktrees needed.
329
+
330
+
### Branch History
331
+
332
+
```bash
333
+
git log opam/patches/cohttp # View patches history
334
+
git log opam/upstream/cohttp # View upstream history
335
+
git diff opam/vendor/cohttp opam/patches/cohttp # See local changes
336
+
```
337
+
338
+
### Pushing to Remote
339
+
340
+
Push all unpac branches to a remote:
341
+
```bash
342
+
unpac push origin
343
+
```
344
+
345
+
## Current Contents
346
+
347
+
**Git Repositories:**
348
+
- matrix-rust-sdk (https://github.com/matrix-org/matrix-rust-sdk)
349
+
350
+
**Opam Packages:**
351
+
Run `unpac opam list` to see all vendored packages.
352
+
353
+
## Getting Help
354
+
355
+
```bash
356
+
unpac --help
357
+
unpac opam --help
358
+
unpac git --help
359
+
```